API reference · Billing
Turn auto-recharge on or off (threshold → target, monthly cap, saved card)
/v1/orgs/{org_id}/billing/auto-rechargeWhen enabled, the saved card is charged whenever available credit falls below threshold, bringing it back to target, never more than monthly_cap in a calendar month. Omitted fields keep their previous values; enabling needs a threshold, a target and an active saved card, amounts in whole cents. A suspended account cannot enable it.
Console session only: no API key can be granted the billing:manage permission it needs. Requires the billing:manage permission (a key's scope, or a role that includes it).
Request
Path parameters
org_idstringYour organization. The SDKs and the CLI fill it in from the API key.
ID with prefix org_
Body
JSON (application/json): UpdateAutoRechargeRequest.
enabledbooleanrequiredtrue turns auto-recharge on with the settings below; false turns it off
thresholdstringInteger nano-USD as a decimal string
pattern ^(0|[1-9][0-9]{0,18})$
targetstringPositive integer nano-USD as a decimal string
pattern ^[1-9][0-9]{0,18}$
monthly_capstringPositive integer nano-USD as a decimal string
pattern ^[1-9][0-9]{0,18}$
payment_method_idstringID of the payment method
ID with prefix pmth_
Response
200 BillingAccount — The updated 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 |
|---|---|---|
400 | invalid_request_error | A parameter or body field is missing or not allowed; param names it. |
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. |