GET /v1/balance

Returns the balance of the account that owns the API key, and what is left of that key's spend caps. Use it to show remaining credit in your app, to top up before a batch runs out, or to pause an agent before it hits a 402.

Placeholders: $API_BASE is https://api.abliteratedllm.dev/v1, $API_ORIGIN is https://api.abliteratedllm.dev, and $YOUR_KEY is your API key.

curl $API_BASE/balance -H "Authorization: Bearer $YOUR_KEY"

{
  "balance_usd": "12.345678",
  "held_usd": "0.000000",
  "trial": false,
  "available_usd": "12.345678",
  "key_daily_remaining_usd": "4.500000",
  "key_monthly_remaining_usd": null,
  "key_lifetime_remaining_usd": "40.000000"
}

Fields

Field	Meaning
`balance_usd`	Credit available for new requests, in USD with 6 decimals. Credit held by running requests is already taken out.
`held_usd`	Credit reserved by requests that are still running. When each one finishes, its hold returns to the balance minus the actual cost.
`trial`	`true` until the account's first top-up is credited. Trial accounts have tighter limits.
`available_usd`	The account's credit minus what running requests hold. Holds are taken out of the balance as they are placed, so this always equals `balance_usd`. It is shared by every key on the account; a key's caps can limit it further (the fields below).
`key_daily_remaining_usd`	What is left of this key's daily cap today (UTC), or `null` when the key has no daily cap.
`key_monthly_remaining_usd`	What is left of this key's monthly cap this calendar month (UTC), or `null` without one.
`key_lifetime_remaining_usd`	What is left of this key's lifetime budget, or `null` without one.

The amounts are decimal strings so that no precision is lost. Parse them as decimals, not floats.

Notes

balance_usd can dip slightly below zero: a request is always billed its actual usage, even when that exceeds its hold. While the balance is below the next request's hold, requests fail with 402 insufficient_balance until you top up.
held_usd is normally "0.000000" when nothing is running. Holds of requests that never finish are released automatically after 15 minutes.
A remaining cap is the cap minus the key's settled spend in the period and the holds of its running requests, the same sum the gateway checks before forwarding a request. It never goes below zero. A request fails with 402 key_spend_cap_reached when its own hold doesn't fit, so a small remainder may still refuse a request with a large output budget. See Authentication.
Spend caps are per key and don't change the balance. Each key reports its own caps; the balance is shared by every key on the account.
Top up in Billing. Credit never expires.