Get key quota, balance and 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 can show why a key stopped working even after it expired or ran out of quota. The fields depend on mode.

#Request

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

#Authentication

Send one of these.

#Query parameters

#Response

#Response fields

#Examples

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

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"))

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.

{
  "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.

{
  "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.
• 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.
• For per-request detail and CSV export, use Usage in the console.

#Related

• Per-key limits & budgets
• Billing & top-ups
• CC Switch