API reference · Billing
Billing settings, credit standing, spend limits, auto-recharge and limits
/v1/orgs/{org_id}/billing/account- TypeScript
client.billing.getAccount()- Python
client.billing.get_account()- CLI
hayonix billing account
Everything that decides whether the organization may spend: balance, suspension, out-of-credit and compute-stop state, spend limits and spend so far, auto-recharge settings, top-up limits and quotas.
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/account" \
-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 BillingAccount — The billing account
objectstringrequiredAlways `billing_account`: the type of this object
One of
billing_accountorg_idstringrequiredOrganization it belongs to
ID with prefix org_
statusstringrequired`active`, or `suspended` by the platform: nothing can be launched, running compute is stopped (volumes kept) and API requests that spend credit are refused
One of
activesuspendedsuspended_reasonstring | nullrequiredWhy the account was suspended; null while it is active
paidstringrequiredInteger nano-USD as a decimal string
pattern ^-?[0-9]+$
promostringrequiredInteger nano-USD as a decimal string
pattern ^-?[0-9]+$
heldstringrequiredInteger nano-USD as a decimal string
pattern ^-?[0-9]+$
availablestringrequiredInteger nano-USD as a decimal string
pattern ^-?[0-9]+$
out_of_creditbooleanrequiredavailable ≤ 0: new launches and API requests are refused
compute_stops_atstring (date-time) | nullrequiredWhen running compute will be stopped if no credit arrives
compute_stopped_atstring (date-time) | nullrequiredTime compute stopped (ISO 8601, UTC)
compute_stop_reasonstring | nullrequiredWhy running compute was stopped: `zero_balance` (out of credit past the grace period), `overdraft_limit`, `spend_limit_hourly` or `spend_limit_monthly`; null when it is not stopped
low_balance_thresholdstringrequiredInteger nano-USD as a decimal string
pattern ^-?[0-9]+$
min_launch_balancestringrequiredInteger nano-USD as a decimal string
pattern ^-?[0-9]+$
spendobjectrequiredSpend limits and spend so far
ShowHide 5 fields of
spendhourly_limitstring | nullrequiredInteger nano-USD as a decimal string
pattern ^-?[0-9]+$
monthly_limitstring | nullrequiredInteger nano-USD as a decimal string
pattern ^-?[0-9]+$
last_hourstringrequiredInteger nano-USD as a decimal string
pattern ^-?[0-9]+$
month_to_datestringrequiredInteger nano-USD as a decimal string
pattern ^-?[0-9]+$
breachedstring | nullrequiredWhich spend limit has been reached (running compute is stopped and new work refused until spend falls below it or it is raised); null when neither
One of
hourlymonthly
auto_rechargeobjectrequiredAutomatic top-ups: when available credit falls below `threshold`, the saved card is charged to bring it back to `target`, at most `monthly_cap` per calendar month
ShowHide 7 fields of
auto_rechargeenabledbooleanrequiredWhether the saved card is charged automatically when credit runs low
thresholdstring | nullrequiredInteger nano-USD as a decimal string
pattern ^-?[0-9]+$
targetstring | nullrequiredInteger nano-USD as a decimal string
pattern ^-?[0-9]+$
monthly_capstring | nullrequiredInteger nano-USD as a decimal string
pattern ^-?[0-9]+$
payment_method_idstring | nullrequiredID of the payment method
disabled_reasonstring | nullrequiredWhy the platform turned auto-recharge off (for example a failed charge or a removed card); null when you turned it off or it is on
charged_this_monthstringrequiredInteger nano-USD as a decimal string
pattern ^-?[0-9]+$
top_upobjectrequiredSmallest and largest top-up allowed for this organization
ShowHide 2 fields of
top_upminstringrequiredInteger nano-USD as a decimal string
pattern ^-?[0-9]+$
maxstringrequiredInteger nano-USD as a decimal string
pattern ^-?[0-9]+$
card_verifiedbooleanrequiredA card payment has succeeded; until then GPU compute cannot run on promotional credit alone
new_org_limitsbooleanrequiredSmall quotas apply until a payment has aged
quotasobjectrequiredLimits in force for this organization, by quota name (for example `sandboxes` or `inference_rpm`)
payment_driverstring | nullHow top-ups are taken here: `stripe` (hosted Checkout), `development` (test credit granted at once, no money taken), or null when payments are disabled. Present on the customer billing routes.
One of
stripedevelopment
Example response
{
"object": "billing_account",
"org_id": "org_01jc5zq4m8k3v6x9t2w7r0b1e4",
"status": "active",
"suspended_reason": "string",
"paid": "1500000000",
"promo": "1500000000",
"held": "1500000000",
"available": "1500000000",
"out_of_credit": true,
"compute_stops_at": "2026-01-01T00:00:00.000Z",
"compute_stopped_at": "2026-01-01T00:00:00.000Z",
"compute_stop_reason": "string",
"low_balance_threshold": "1500000000",
"min_launch_balance": "1500000000",
"spend": {
"hourly_limit": "1500000000",
"monthly_limit": "1500000000",
"last_hour": "1500000000",
"month_to_date": "1500000000",
"breached": "hourly"
},
"auto_recharge": {
"enabled": true,
"threshold": "1500000000",
"target": "1500000000",
"monthly_cap": "1500000000",
"payment_method_id": "string",
"disabled_reason": "string",
"charged_this_month": "1500000000"
},
"top_up": {
"min": "1500000000",
"max": "1500000000"
},
"card_verified": true,
"new_org_limits": true,
"quotas": {},
"payment_driver": "stripe"
}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 | quota_exceeded_error quota_exceeded | An organization quota is reached; param names it. |
429 | rate_limit_error rate_limited | Too many requests; retry after retry-after seconds. |