API reference · Billing
Get the credit balance
/v1/orgs/{org_id}/billing/balance- TypeScript
client.billing.getBalance()- Python
client.billing.get_balance()- CLI
hayonix balance
Returns paid and promotional credit, the amount reserved by work in progress, and what is available for new work. Recent inference spending can take up to about 30 seconds to appear.
Project API key (Authorization: Bearer sk_…), or a console session. Requires the billing:read permission (a key's scope, or a role that includes it).
Examples
The samples read API_KEY and API_BASE_URL from the environment (see Setup). Values are examples.
# The org of your key: GET /v1/caller
ORG_ID=$(curl -sS "$API_BASE_URL/caller" -H "Authorization: Bearer $API_KEY" | jq -r .org_id)
curl -sS "$API_BASE_URL/orgs/$ORG_ID/billing/balance" \
-H "Authorization: Bearer $API_KEY"Request
| Header | Required | Description |
|---|---|---|
Authorization | yes | Bearer and your API key. The key implies its project. |
Path parameters
org_idstringYour organization. The SDKs and the CLI fill it in from the API key.
ID with prefix org_
Response
200 Balance — The current balance
objectstringrequiredAlways `balance`: the type of this object
One of
balanceorg_idstringrequiredOrganization it belongs to
ID with prefix org_
currencystringrequiredAlways `usd`
One of
usdpaidstringrequiredPaid credit; negative when overdrawn
pattern ^-?[0-9]+$
promostringrequiredSpendable promotional credit
pattern ^-?[0-9]+$
heldstringrequiredReserved by in-flight work
pattern ^-?[0-9]+$
availablestringrequiredpaid + promo: what new work may use
pattern ^-?[0-9]+$
as_ofstring (date-time)requiredWhen these amounts were read (ISO 8601, UTC)
Example response
{
"object": "balance",
"org_id": "org_01jc5zq4m8k3v6x9t2w7r0b1e4",
"currency": "usd",
"paid": "1500000000",
"promo": "1500000000",
"held": "1500000000",
"available": "1500000000",
"as_of": "2026-01-01T00:00:00.000Z"
}Errors
Errors use the standard envelope. What this operation can answer:
| Status | Type | When |
|---|---|---|
401 | authentication_error | The key or session is missing, revoked or expired. |
403 | permission_error | The credential lacks the permission this needs, or the organization is suspended. |
402 | insufficient_credit_error | The organization is out of credit or over a spend limit. |
429 | rate_limit_error rate_limited | Too many requests; retry after retry-after seconds. |