Skip to main content
GET /api/v1/billing/balance returns the authenticated organization’s available balance and top-up amounts. All amounts are integer USD nanos serialized as strings: 1000000000 is $1. Keep them as strings or use integer arithmetic such as JavaScript BigInt.

​
Authentication

Use an API key with admin: true whose owner is currently an organization owner or admin. An OAuth bearer with cli:inference also works when its user is a current owner or admin. Ordinary inference keys and browser cookies alone cannot read this endpoint. See API keys to provision an admin key. The credential determines the organization. Optional X-Org-ID must match it; query parameters and request bodies cannot select another organization.
X-API-Key is also accepted. The read does not require a funded balance, a subscription, unused key spend-cap budget, or available inference capacity. Its own management request limits still apply.

​
Response

If top-up attribution fails, HTTP 200 still returns the ledger balance:
Do not turn omitted top-up fields into zero. A missing balance account returns zero amounts with projection state available; a ledger outage returns 503, not a fabricated zero balance. Responses use Cache-Control: no-store.

​
Errors and limits

  • 401: missing, expired, revoked, or invalid credentials.
  • 403: insufficient admin authority or an organization mismatch.
  • 429: the balance read’s management request limit was exhausted; honor Retry-After when supplied.
  • 503: billing is disabled or a required dependency is unavailable.
Management reads are rate-limited separately from inference and do not reserve inference concurrency slots. A balance is a snapshot, not authorization for a future model call.

​
Usage history

This endpoint does not return request history, provider costs, or margins. A public billing-usage history endpoint is not available yet. Use response usage data and the developer console for usage history. See Get usage.