Get balance and quota
Check how much this key can spend right now and its quota; not billed, and a positive balance is not required.
/v1/usagebalance is what this key can spend right now: without a key quota it is the account balance; with a key quota it is the key's remaining quota. Keys of team members and departments are further capped by the remaining quota for the current period. A key with a quota still draws from the account balance, so once the account balance runs out, requests return 402 even if balance still shows credit.
Amounts are in USD (since 2026-10-01 ledger_currency is "USD", matching unit): balance, remaining and the unsuffixed quota.* values are all USD. For CNY, read the _cny fields, which hold the same amounts in CNY (fixed conversion, not a live exchange rate). This endpoint accepts only Authorization: Bearer and does not use the standard error shape: check is_active rather than relying only on the HTTP status.
Async task queries include the per-task charge in the root usage object once the task has ended (the USD amount cost_usd, the CNY amount cost, and currency, the currency of cost), and every finished task in a task list carries the same fields in its usage (the _cny / _usd fields above belong to this endpoint only); see Charges.
Headers
Bearer sk-…: an API key created in the console under API keys; its group must include the requested model
Returns
200Balance and quota; also 200 when the key has expired or the member is disabled, with is_active: false
true when balance is greater than 0
What this key can spend right now (USD)
Same as balance
Always "USD", matching ledger_currency
Currency of unsuffixed amounts: "USD" (it was "CNY" before 2026-10-01)
balance in CNY
balance in USD
Key quota
Same as balance
Remaining key quota; equals the account balance when no quota is set
Key quota; 0 means no quota is set
Total amount charged to this key so far
true when the key has no quota set
CNY
USD
null when no quota is set
null when no quota is set
null when no quota is set
null when no quota is set
CNY
USD
Only on anomalies: api key expired, member disabled, etc.
The group this key belongs to; omitted for exclusive groups
Group ID
Group name
Localized group names keyed by locale code (such as en, zh-tw, es, ja), as shown in the console
The group's protocol family, such as openai, claude, gemini
Errors
sk-: missing or invalid api key; key does not exist or is disabled: invalid api key