Skip to content

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.

GET/v1/usage

balance 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

Authorization:requiredstring

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

is_active:optionalboolean

true when balance is greater than 0

balance:optionalnumber

What this key can spend right now (USD)

remaining:optionalnumber

Same as balance

unit:optionalstring

Always "USD", matching ledger_currency

ledger_currency:optionalstring

Currency of unsuffixed amounts: "USD" (it was "CNY" before 2026-10-01)

balance_cny:optionalnumber

balance in CNY

balance_usd:optionalnumber

balance in USD

quota:optionalobject

Key quota

message:optionalstring

Only on anomalies: api key expired, member disabled, etc.

group:optionalobject

The group this key belongs to; omitted for exclusive groups

Errors

401No key sent or not starting with sk-: missing or invalid api key; key does not exist or is disabled: invalid api key

Related