# Get key quota, balance and usage

> GET /v1/usage on BigModel.io returns the calling key's balance or quota, its 5h/1d/7d spend windows, expiry and token usage. Works even when the key is expired or out of quota.

Web version: https://bigmodel.io/docs/api-usage · Updated 2026-10-18

`GET https://bigmodel.io/v1/usage`

Returns what the calling key has left and what it has used: account balance, plan allowances or the key's own quota, its spend windows, expiry, and token totals. Any key can call it, and it skips billing checks, so tools such as [CC Switch](https://bigmodel.io/docs/cc-switch) can show why a key stopped working even after it expired or ran out of quota. The fields depend on `mode`.

## Request

```http
GET https://bigmodel.io/v1/usage
```

### Authentication

| Header | Value |
|---|---|
| `Authorization` | `Bearer $BIGMODEL_API_KEY` |
| `x-api-key` | `$BIGMODEL_API_KEY` |

Send one of these.

### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `start_date` | string |  | Start of the `model_stats` range (YYYY-MM-DD). Default: 30 days ago. |
| `end_date` | string |  | End of the `model_stats` range (YYYY-MM-DD). Default: today. |

## Response

| Status | Meaning |
|---|---|
| `200` | Usage for the key. Fields depend on `mode`. |
| `400` | `api_key_in_query_deprecated`: the key was sent as `?key=` or `?api_key=`. Send it in a header. |
| `401` | `API_KEY_REQUIRED`, `INVALID_API_KEY`, `API_KEY_DISABLED`, `USER_NOT_FOUND`, `USER_INACTIVE`. |
| `403` | `ACCESS_DENIED` (IP rule) or `permission_error` (key without a group). |

### Response fields

| Field | Type | Description |
|---|---|---|
| `mode` | string | `quota_limited` when the key has its own quota or rate limits; otherwise `unrestricted` (it draws on your balance or plan). One of: `quota_limited`, `unrestricted` |
| `isValid` | boolean | True for keys that are active, out of quota or expired. Check `status` to see which. |
| `status` | string | `quota_limited` only: `active`, `quota_exhausted`, `expired`, … |
| `planName` | string | `unrestricted` only: plan (group) name, or the wallet. |
| `remaining` | number | Remaining USD: key quota, balance, or the smallest plan allowance (`-1` when unlimited). |
| `unit` | any |  |
| `balance` | number | Wallet balance in USD, when the key uses the balance. |
| `quota` | object | `quota_limited` keys with a quota. |
| `quota.limit` | number |  |
| `quota.used` | number |  |
| `quota.remaining` | number |  |
| `quota.unit` | any |  |
| `rate_limits` | array<object> | Spending windows set on the key. |
| `rate_limits[].window` | string | One of: `5h`, `1d`, `7d` |
| `rate_limits[].limit` | number |  |
| `rate_limits[].used` | number |  |
| `rate_limits[].remaining` | number |  |
| `rate_limits[].window_start` | string |  |
| `rate_limits[].reset_at` | string |  |
| `expires_at` | string | Key expiry, if set. |
| `days_until_expiry` | integer |  |
| `subscription` | object | Plan allowances and usage, in USD. |
| `subscription.daily_usage_usd` | number |  |
| `subscription.weekly_usage_usd` | number |  |
| `subscription.monthly_usage_usd` | number |  |
| `subscription.daily_limit_usd` | number |  |
| `subscription.weekly_limit_usd` | number |  |
| `subscription.monthly_limit_usd` | number |  |
| `subscription.expires_at` | string |  |
| `usage` | object | Token usage of this key. Omitted if unavailable. |
| `usage.today` | object |  |
| `usage.total` | object |  |
| `usage.average_duration_ms` | number |  |
| `usage.rpm` | number |  |
| `usage.tpm` | number |  |
| `model_stats` | array<object> | Per-model usage for the date range. Omitted if unavailable. |


## Examples

```bash [cURL]
curl "https://bigmodel.io/v1/usage?start_date=2026-10-01&end_date=2026-10-18" \
  -H "Authorization: Bearer $BIGMODEL_API_KEY"
```

```python [Python]
import os, requests

usage = requests.get(
    "https://bigmodel.io/v1/usage",
    headers={"Authorization": f"Bearer {os.environ['BIGMODEL_API_KEY']}"},
    timeout=30,
).json()
print(usage["mode"], usage.get("remaining"), usage.get("unit"))
```

```js [Node.js]
const usage = await (await fetch('https://bigmodel.io/v1/usage', {
  headers: {Authorization: `Bearer ${process.env.BIGMODEL_API_KEY}`},
})).json()
console.log(usage.mode, usage.remaining, usage.unit)
```

### Key that uses the account balance

Values are illustrative. `usage` is trimmed to `today`; `total` has the same fields.

```json
{
  "mode": "unrestricted",
  "isValid": true,
  "planName": "钱包余额",
  "remaining": 12.5,
  "unit": "USD",
  "balance": 12.5,
  "usage": {
    "today": {"requests": 42, "input_tokens": 51200, "output_tokens": 8300, "cache_creation_tokens": 0, "cache_read_tokens": 20480, "total_tokens": 79980, "cost": 0.091, "actual_cost": 0.091},
    "average_duration_ms": 2350,
    "rpm": 0,
    "tpm": 0
  }
}
```

### Key with its own quota and spend windows

Values are illustrative; timestamps use the server's time zone.

```json
{
  "mode": "quota_limited",
  "isValid": true,
  "status": "active",
  "quota": {"limit": 20, "used": 4.2, "remaining": 15.8, "unit": "USD"},
  "remaining": 15.8,
  "unit": "USD",
  "rate_limits": [
    {"window": "5h", "limit": 2, "used": 0.6, "remaining": 1.4, "window_start": "2026-10-18T08:00:00+08:00", "reset_at": "2026-10-18T13:00:00+08:00"}
  ],
  "expires_at": "2026-11-17T00:00:00+08:00",
  "days_until_expiry": 30
}
```

## Notes

- **Three shapes.** `quota_limited` when the key has its own quota or 5h/1d/7d spend limits; `unrestricted` with `subscription` when the key's group bills against an active plan; `unrestricted` with `balance` otherwise. `planName` is the literal string `钱包余额` ("wallet balance") in the balance case.
- **`remaining`** is in USD: the key quota, the balance, or the smallest remaining plan allowance (`-1` when the plan has no limit).
- **In `quota_limited` mode, `isValid` stays `true` for expired or exhausted keys.** Check `status` (`active`, `quota_exhausted`, `expired`) and `days_until_expiry` to see whether the key can make requests.
- **Spend windows are fixed, not rolling.** A window starts when first used and resets once its length has passed; `reset_at` is only present while the window is running. See [Per-key limits & budgets](https://bigmodel.io/docs/key-limits).
- **Usage is best effort.** `usage` and `model_stats` are omitted when statistics are unavailable. `start_date` / `end_date` (YYYY-MM-DD) only affect `model_stats`; the default range is the last 30 days. `cost` is at list price, `actual_cost` is what was charged.
- **Not every check is skipped.** Disabled keys still get `401` `API_KEY_DISABLED`, and IP rules still apply. Full list: [Errors](https://bigmodel.io/docs/errors).
- For per-request detail and CSV export, use [Usage](https://bigmodel.io/usage) in the console.

## Related

- [Per-key limits & budgets](https://bigmodel.io/docs/key-limits)
- [Billing & top-ups](https://bigmodel.io/docs/billing)
- [CC Switch](https://bigmodel.io/docs/cc-switch)