Balance API

GET /billing/balance

Returns the organization’s remaining prepaid credit — the same number the console shows on the billing page. Use it from scripts that watch for a low balance and alert before requests start failing with 402 Payment Required.

Response

{
  "balance": "42.75000000",
  "currency": "usd"
}

Field	Type	Description
`balance`	string	Remaining credit in the billing currency, as a decimal string.
`currency`	string	`usd` or `jpy`, your organization’s billing currency.

balance is a string so no precision is lost. Parse it with a decimal library rather than a float.

What the number means

The balance is the settled ledger value, so it can briefly read higher than what is actually spendable:

Chat and completion requests are deducted after they finish, through an asynchronous settlement queue. Expect a lag of a few seconds, longer if settlement is backed up or retrying.
Video generations reserve credit when accepted but deduct it only when the render completes. A queued or running render is not yet reflected here.
In-flight requests can push the balance slightly negative. The next top-up clears that first.

For alerting, polling once a minute is plenty. Pick a threshold that leaves room for the lag above.

Auth

API key or JWT + X-Org-ID. See Authentication.

With an API key the balance is always that of the organization the key belongs to; X-Org-ID is ignored.

Example

curl https://api.aiand.com/billing/balance \
  -H "Authorization: Bearer $AIAND_API_KEY"