# Per-key limits and budgets

> Give each BigModel.io API key its own USD quota, 5-hour, daily and weekly spend limits, an expiry date and IP rules, then read them back with GET /v1/usage.

Web version: https://bigmodel.io/docs/key-limits · Updated 2026-10-18

Every API key can carry its own budget and access rules, so you can hand a key to a teammate, a script or a customer without risking your whole balance. Set them when you create or edit a key in [API Keys](https://bigmodel.io/keys).

| Setting | What it does | When it trips |
|---|---|---|
| Quota (USD) | Total spend allowed for this key. `0` = unlimited. Used quota can be reset. | 429 `API_KEY_QUOTA_EXHAUSTED` |
| 5h / 1d / 7d limits (USD) | Spend allowed per window. `0` = unlimited. Window usage can be reset. | 429 `rate_limit_exceeded` |
| Expiry | Preset 7, 30 or 90 days, or a custom date | 403 `API_KEY_EXPIRED` |
| IP whitelist / blacklist | IPs or CIDR ranges, one per line | 403 `ACCESS_DENIED` |
| Status | Enable or disable the key | 401 `API_KEY_DISABLED` |
| Group | Which models and endpoints the key can call, and the rate multiplier | — |

All limits are in USD of actual cost, after the group multiplier. The key also stops when your account balance runs out (403 `INSUFFICIENT_BALANCE`), whatever its own limits say.

## How the spend windows work

The 5-hour, 1-day and 7-day limits use **fixed windows**, not rolling ones. A window starts when the key is first used after the previous window ended, and resets once its full duration has passed. For example, with a $5 daily limit, a key first used at 14:00 can spend $5 until 14:00 the next day, and then gets a fresh $5.

When a window is used up, requests fail with HTTP 429, error type `rate_limit_exceeded`, and a message such as `api key 5小时限额已用完` ("the key's 5-hour limit is used up"). There is no `Retry-After` header. Read `reset_at` from `/v1/usage` to know when to resume.

A request that is already running can finish and go slightly over a limit; the next request is blocked.

## What keys cannot limit

- **Models.** There is no per-key model allow-list. A key can call every model its group serves. To restrict models, use a key in a different group.
- **Request rate.** There is no per-key requests-per-minute or concurrency setting. Rate and concurrency limits apply per account and per group. See [Limits & rate limits](https://bigmodel.io/docs/rate-limits).

For a cap across all your keys, set the weekly and monthly account spend caps on [Balance & billing](https://bigmodel.io/purchase). Reaching one returns 402 `spend_cap_reached` until the reset; see [Billing & top-ups](https://bigmodel.io/docs/billing).

## Read limits with GET /v1/usage

`GET /v1/usage` returns the calling key's limits and usage. It works even when the key is expired or out of quota, so a script can always check why it stopped.

```bash [cURL]
curl https://bigmodel.io/v1/usage \
  -H "Authorization: Bearer $BIGMODEL_API_KEY"
```

```python [Python]
import os, requests

r = requests.get(
    "https://bigmodel.io/v1/usage",
    headers={"Authorization": f"Bearer {os.environ['BIGMODEL_API_KEY']}"},
    timeout=10,
)
data = r.json()
print(data.get("status"), data.get("remaining"))
for w in data.get("rate_limits", []):
    print(w["window"], w["used"], "/", w["limit"], "resets", w.get("reset_at"))
```

```js [Node.js]
const r = await fetch("https://bigmodel.io/v1/usage", {
  headers: { Authorization: `Bearer ${process.env.BIGMODEL_API_KEY}` },
});
const data = await r.json();
console.log(data.status, data.remaining);
for (const w of data.rate_limits ?? []) console.log(w.window, w.used, "/", w.limit, "resets", w.reset_at);
```

A key with a quota or a spend window returns `"mode": "quota_limited"`. Abbreviated example:

```json
{
  "mode": "quota_limited",
  "isValid": true,
  "status": "active",
  "quota": {"limit": 20, "used": 3.42, "remaining": 16.58, "unit": "USD"},
  "remaining": 16.58,
  "unit": "USD",
  "rate_limits": [
    {"window": "1d", "limit": 5, "used": 1.2, "remaining": 3.8,
     "window_start": "2026-10-18T06:00:00Z", "reset_at": "2026-10-19T06:00:00Z"}
  ],
  "expires_at": "2026-11-17T00:00:00Z",
  "days_until_expiry": 30,
  "usage": {"today": {"requests": 12, "cost": 0.4, "actual_cost": 0.4}, "total": {"requests": 310}}
}
```

- `status` is `active`, `quota_exhausted`, `expired` or `disabled`.
- `quota` appears only if the key has a quota; `rate_limits` only lists windows that are set. `reset_at` is missing when the window has not started or has already ended.
- A key without a quota or spend windows returns `"mode": "unrestricted"` with your balance (or plan limits for a plan group) in `remaining`. Expiry is not included in that mode.
- `usage` has `today` and `total` request, token and cost counters. Add `?start_date=2026-10-01&end_date=2026-10-18` to set the date range of `model_stats` (default: last 30 days).

The full schema is in the [Usage API reference](https://bigmodel.io/docs/api-usage).

## Verify the setup

Create a key with a small 1d limit, for example $0.10, and call `GET /v1/usage` with it. The response should be `quota_limited` and list a `1d` window with `limit: 0.1`. Send a few requests and call it again: `used` goes up. The [API Keys](https://bigmodel.io/keys) page shows the same numbers.

## Troubleshooting

**429 `API_KEY_QUOTA_EXHAUSTED`.** The key's total quota is used up. Raise the quota or reset used quota in [API Keys](https://bigmodel.io/keys).

**429 `rate_limit_exceeded` with a message like `api key 1天限额已用完`.** A 5h, 1d or 7d window is used up. Wait until `reset_at`, raise the limit, or reset the window usage on the key.

**429 `rate_limit_exceeded` with a `Retry-After` header.** That is an account or group requests-per-minute limit, not a key budget. Wait the number of seconds in `Retry-After`.

**403 `API_KEY_EXPIRED`.** Set a later expiry date on the key, or create a new key.

**403 `ACCESS_DENIED`.** The caller's IP is not on the key's whitelist, or is on its blacklist. The message is deliberately vague. Check the egress IP of your server, and remember that CIDR ranges are allowed.

**401 `API_KEY_DISABLED`.** The key is switched off. Enable it in [API Keys](https://bigmodel.io/keys).

## Related

- [Authentication](https://bigmodel.io/docs/authentication) for creating and sending keys.
- [Limits & rate limits](https://bigmodel.io/docs/rate-limits) for account and group limits.
- [Usage API reference](https://bigmodel.io/docs/api-usage) and [Errors](https://bigmodel.io/docs/errors).