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 currently recorded in CNY, yet unit says "USD": balance, remaining and the unsuffixed quota.* values are all CNY. For reconciliation, read the _cny / _usd fields directly (_usd = _cny ÷ 6.8, fixed). 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 cost / cost_cny / cost_usd in the root usage object once the task has ended; see Charges.

Get balance and quota

curl https://api.hop-base.com/v1/usage \
  -H "Authorization: Bearer $HOPBASE_API_KEY"

200application/json

{
  "is_active": true,
  "balance": 54.4,
  "remaining": 54.4,
  "unit": "USD",
  "ledger_currency": "CNY",
  "exchange_rate": {
    "cny_per_usd": 6.8,
    "basis": "fixed unit rate"
  },
  "balance_cny": 54.4,
  "balance_usd": 8,
  "quota": {
    "remaining": 54.4,
    "api_key_remaining": 54.4,
    "total": 68,
    "used": 13.6,
    "unlimited": false,
    "remaining_cny": 54.4,
    "remaining_usd": 8,
    "api_key_remaining_cny": 54.4,
    "api_key_remaining_usd": 8,
    "total_cny": 68,
    "total_usd": 10,
    "used_cny": 13.6,
    "used_usd": 2
  }
}

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 (ledger currency)

remaining:optionalnumber

Same as balance

unit:optionalstring

Always "USD"; does not indicate the currency

ledger_currency:optionalstring

Actual currency of unsuffixed amounts, currently "CNY"

exchange_rate:optionalobject

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

Headers

Returns

Errors

Related