# Usage, limit আর alert

> Dashboard, CSV export, GET /v1/tokens/usage endpoint বা CLI দিয়ে Tokens-এ খরচ আর বাকি allowance দেখুন, usage alert চালু করুন, আর rate limit ও Retry-After ঠিকমতো সামলান।

একটা লম্বা session-এ coding agent অনেক খরচ করে ফেলতে পারে। তাই শুরুর আগেই জেনে রাখা ভালো usage কোথায় দাঁড়িয়ে আছে, পরে নয়। এই পেজে আছে Tokens-এ usage দেখার চারটা উপায়, ইমেইল alert, আর প্রতিটা অ্যাকাউন্টে যে rate limit খাটে সেগুলো।

## Usage dashboard পড়ুন

Dashboard-এর Usage পেজে এগুলো দেখা যায়:

- **Totals**: খরচ আর request-এর সংখ্যা, সাথে সাম্প্রতিক burn rate।
- **Usage limits**: আপনার plan-এর প্রতিটা usage window, তার কতটা খরচ হয়েছে আর কখন reset হবে।
- **একটা chart**: গত 7, 14 বা 30 দিনের দৈনিক খরচ ও request, সাথে খরচ অনুযায়ী সাজানো ভাগ-ভাগ হিসাব।
- **Recent activity**: সাম্প্রতিক request, model, token আর খরচ সহ।

Dashboard Overview-তে এই সংখ্যাগুলোরই ছোট রূপ আছে, আর Wallet পেজে প্রতিটা top-up ও charge-এর তালিকা পাবেন।

## Usage CSV হিসেবে নামান

Usage পেজের **Export CSV** চাপলে গত 30 দিনের request record নামে, প্রতি request-এ এক সারি:

| Column                                         | মানে                                              |
| ---------------------------------------------- | ------------------------------------------------- |
| Record ID                                      | Usage record-এর ভেতরের id                          |
| Request ID                                     | ওই request-এর `x-tokens-request-id`               |
| Date                                           | কখন হয়েছে (UTC, ISO 8601)                         |
| Model                                          | আপনি যে model id দিয়ে call করেছিলেন                |
| Input Tokens, Output Tokens, Cache Read Tokens | ওই request-এর token সংখ্যা                         |
| Cost (USD)                                     | খরচ কত, দশমিকের পর ছয় ঘর পর্যন্ত                  |
| Source                                         | কোথা থেকে এসেছে, যেমন API call হলে `v1`            |

কোনো নির্দিষ্ট call নিয়ে [Support](/docs/support)-কে জিজ্ঞেস করতে হলে Request ID column কাজে লাগবে।

## কোড থেকে usage দেখুন: GET /v1/tokens/usage

`GET /v1/tokens/usage` আপনার plan, usage window, Wallet ব্যালান্স আর যে key দিয়ে call করছেন তার limit ফেরত দেয়। এটা inference-এর মতো একই API key-তে চলে, আর এর কোনো খরচ ধরা হয় না। তাই script, status bar বা CI থেকে বারবার poll করা যায়।

```bash
curl -s https://tokens.bd/v1/tokens/usage \
  -H "Authorization: Bearer $TOKENS_API_KEY"
```

একটা উদাহরণ response (মানগুলো শুধু বোঝানোর জন্য):

```json
{
  "object": "tokens.usage",
  "plan": { "name": "Example Plan", "tier": "monthly", "periodEnd": "2026-10-31T00:00:00.000Z" },
  "windows": [
    {
      "type": "session_5h",
      "label": "5-Hour Session",
      "unit": "usd",
      "limit": 5,
      "used": 1.85,
      "remaining": 3.15,
      "percentUsed": 37,
      "resetsAt": "2026-10-03T14:20:00.000Z"
    },
    {
      "type": "weekly",
      "label": "Weekly Ceiling",
      "unit": "usd",
      "limit": 25,
      "used": 9.4,
      "remaining": 15.6,
      "percentUsed": 38,
      "resetsAt": "2026-10-05T00:00:00.000Z"
    }
  ],
  "wallet": { "balanceUsd": 12.5 },
  "key": { "monthlySpendCapUsd": 20, "allowedModels": null }
}
```

| Field                    | মানে                                                                               |
| ------------------------ | ---------------------------------------------------------------------------------- |
| `plan`                   | আপনার চালু plan, আর শুধু pay-as-you-go হলে `null`                                  |
| `windows[].type`         | `session_5h`, `weekly` বা `monthly`                                                |
| `windows[].unit`         | Credit-ভিত্তিক window-এ `usd` (ডলারে), request-সংখ্যার window-এ `requests`          |
| `windows[].percentUsed`  | Window-র কত শতাংশ খরচ হয়েছে (round করা সংখ্যা)                                |
| `windows[].resetsAt`     | Window কখন reset হবে (UTC)                                                         |
| `wallet.balanceUsd`      | USD-তে Wallet ব্যালান্স                                                            |
| `key.monthlySpendCapUsd` | এই key-এর monthly cap, আর কোনো cap না থাকলে `null`                                 |
| `key.allowedModels`      | এই key-এ যেসব model চলবে, আর আপনার সব model চললে `null`                           |

শুধু window-গুলো `jq` দিয়ে print করতে:

```bash
curl -s https://tokens.bd/v1/tokens/usage -H "Authorization: Bearer $TOKENS_API_KEY" \
  | jq -r '.windows[] | "\(.label): \(.percentUsed)% (resets \(.resetsAt))"'
```

## Tokens CLI দিয়ে usage দেখুন

আপনার agent যদি [Tokens CLI](/docs/tokens-cli) দিয়ে সেটআপ করা হয়ে থাকে, তাহলে সেটাও একই endpoint পড়ে:

```bash
node tokens.mjs usage
node tokens.mjs usage --json
```

প্রথম command-টা দেখায় আপনার plan, প্রতিটা window-র progress bar ও reset-এর সময়, Wallet ব্যালান্স আর key-এর cap। `--json` দিলে ওপরের মতো raw response print হয়।

## Usage alert চালু করুন

Dashboard-এর Notifications থেকে বেছে নিতে পারেন কোন কোন ইমেইল পাবেন:

- **Usage warning**: plan-এর limit-এর 50%, 75% ও 90%-এ (প্রতিটা ধাপ আলাদা করে চালু বা বন্ধ করা যায়), আর limit ছুঁয়ে ফেললে। প্রতিটা ধাপে alert যায় একবারই, প্রতি request-এ নয়।
- **Low balance**: Wallet $5-এর নিচে নামলে। ডিফল্টে চালু।
- **Renewal reminder**: plan-এর period শেষ হওয়ার আগে। Plan নিজে থেকে renew হয় না, তাই এটা চালু রাখুন।
- **Billing receipt** আর **payment failure**।

:::tip[টিপ]
Agent-কে নিজে নিজে চলতে দিয়ে যাওয়ার আগে দুটো জিনিস দেখে নিন: usage warning চালু আছে কি না, আর agent যে key ব্যবহার করে তাতে monthly spend cap আছে কি না। Cap দিতে হয় key তৈরির সময়; দেখুন [API key](/docs/api-keys)।
:::

## Rate limit আর concurrency

Usage window আর credit-এর পাশাপাশি প্রতিটা অ্যাকাউন্টে আলাদা করে দুটো limit খাটে:

| Limit                                   | ডিফল্ট                                                                                         | Error                   |
| --------------------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------- |
| প্রতি মিনিটে request, প্রতি user        | 60 RPM (আপনার plan অন্য মান ঠিক করে দিতে পারে); Dashboard playground-এর নিজের 10 RPM           | `429 rate_limited`      |
| একসাথে চলা request, প্রতি অ্যাকাউন্ট    | Plan ঠিক করে; plan না থাকলে 3                                                                   | `429 concurrency_limit` |

Rate limit খাটে আপনার অ্যাকাউন্টে, আলাদা আলাদা key-তে নয়। বেশি key বানালে limit বাড়ে না।

Tokens `X-RateLimit-*` header পাঠায় না। এর বদলে 429 response-এর `Retry-After` header দেখুন:

| Code                  | `Retry-After` কী বলে                                                                                                                 |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `rate_limited`        | পরের মিনিট শুরু হতে কত সেকেন্ড বাকি                                                                                                  |
| `concurrency_limit`   | 2 সেকেন্ড                                                                                                                            |
| `model_limit_reached` | Billing period শেষ হয়ে model-এর allowance reset হতে কত সেকেন্ড বাকি (কয়েক দিনও হতে পারে)                                             |
| `window_exhausted`    | Usage window reset হতে কত সেকেন্ড বাকি (কয়েক ঘণ্টাও হতে পারে)                                                                        |
| `rate_limit_exceeded` | এটা আসে upstream provider থেকে, Tokens-এর automatic failover-এ চেষ্টা করার মতো আর কোনো source না থাকার পর। একটু থেমে retry করুন, নয়তো অন্য model নিন |

## আপনার কোডে Retry-After সামলানো

Coding agent নিজেই 429 retry করে। নিজের কোডে ছোট limit-এর বেলায় `Retry-After` পর্যন্ত অপেক্ষা করুন, আর `window_exhausted` এলে থেমে যান। কারণ request loop-এর ভেতরে ঘণ্টার পর ঘণ্টা ঘুমিয়ে থাকা সাধারণত কেউ চায় না:

```python title="retry.py"
import os
import time
from openai import OpenAI, RateLimitError

client = OpenAI(
    base_url="https://tokens.bd/v1",
    api_key=os.environ["TOKENS_API_KEY"],
    max_retries=0,  # we handle retries below
)

def ask(messages, attempts=5):
    for attempt in range(attempts):
        try:
            return client.chat.completions.create(
                model="deepseek/deepseek-v4.1-flash",
                messages=messages,
            )
        except RateLimitError as err:
            if err.code == "window_exhausted":
                raise  # resets in hours; report it instead of sleeping
            wait = float(err.response.headers.get("retry-after", 2 ** attempt))
            time.sleep(wait)
    raise RuntimeError("Still rate limited after retries")

print(ask([{"role": "user", "content": "One-line summary of HTTP 429."}]).choices[0].message.content)
```

Concurrency error কমাতে চাইলে আপনার script একসাথে যত request পাঠায় তা plan-এর concurrency limit-এর মধ্যে রাখুন। আরও বিস্তারিত আছে [rate limit](/docs/rate-limits) ও [error](/docs/errors) পেজে।

## আরও পড়ুন

- [Plan, credit আর Wallet](/docs/plans-and-wallet): window বা ব্যালান্স শেষ হলে কী হয়
- [API key](/docs/api-keys): প্রতি key-র monthly spend cap
- [Model ও usage endpoint](/docs/models-and-usage)

---
Page: https://tokens.bd/bn/docs/usage-and-alerts