The account's monthly spend budgets (contracts/billing/budgets-v1.json). The overview covers what every operation shares: authentication, roles, errors, pagination, idempotency and If-Match.
GET /budgets List the account's monthly spend budgets
Needs account.read, which owner, admin and member hold. A narrowed key may call it.
The account budget first, then the principal budgets by name (contracts/billing/budgets-v1.json). A caller with usage.read sees every field; a caller a principal budget covers sees every field of that budget; any other member sees only id, scope, stage, resets_at and raise_url.
Planned (ADR-0022 section 7). A Structured Field dictionary on every answer to a caller whose budget is at stage notice or above, such as stage=slow, scope=principals, used=0.91, resets="2026-12-01T00:00:00Z", from Billing's view at most 120 s old; used is left out for a caller who may not see the budget's figures.
The key’s role does not hold the capability the operation needs, the key is narrowed away from the resource, or the account already holds as many of the resource as it may.
No
Use a key whose role holds the capability, or one that is not narrowed; delete what you no longer need, or ask for a higher limit. (more)
Needs budgets.write, which owner and admin hold. A narrowed key may not.
Creates a budget for the UTC month, limit limit_micros at list price. Through this API (any key or CLI login) only a principals budget over principals the caller is or created (itself, or an Agent it created) is created; the account budget and another member's principal answer 403 budget_raise_in_console with raise_url, since they are the console's (contracts/billing/budgets-v1.json change_rules). An Agent a covered person creates later joins the same budget. A principal another budget covers answers 409 conflict.
Parameters
Name
In
Type
Required
Description
Idempotency-Key
header
string
yes
A value you choose for this one creation, 1 to 255 characters, such as a new UUID. Send a new one for each resource you create, and the same one only to retry that request after a timeout or a lost answer: the retry answers what the first request created, in its current state, and never creates a second. A key reused for a different database, stream or Machine answers 409. 1 to 255 characters.
Request body
application/json, required. Unknown fields are refused.
Field
Type
Required
Description
scope
one of "account" or "principals"
yes
principals through this API; account only in the console.
name
string
yes
The budget's name, 1 to 80 characters without surrounding spaces, unique in the account. 1 to 80 characters.
limit_micros
integer
yes
The monthly limit in micro-dollars at list price, $1 to $100,000. 1000000 to 100000000000.
principals
array of string
no
For a principals budget, the members it covers, at least one; through this API only the caller itself and Agents it created. 1 to 100 items.
A monthly spend budget (contracts/billing/budgets-v1.json). The figures, name, principals and created_at are present only for a caller who may see them (usage.read, or a caller the budget covers); any other member sees id, scope, stage, resets_at and raise_url.
Header
Status
Description
ETag
201
Current resource version for optional conditional updates.
The change would loosen a budget or touch one that is not the caller's own: the account budget, a raise, a rename, removing a budget, adding another member's principal or moving a principal out. Outside the console a caller only creates a budget over principals it is or created, lowers the budget that covers it and adds its own principals to it (contracts/billing/budgets-v1.json change_rules). raise_url names the budget's page in the console.
No
Ask an owner or admin to make the change in the console at raise_url. (more)
The key’s role does not hold the capability the operation needs, the key is narrowed away from the resource, or the account already holds as many of the resource as it may.
No
Use a key whose role holds the capability, or one that is not narrowed; delete what you no longer need, or ask for a higher limit. (more)
The name is held by another live resource of the account, the Idempotency-Key already created another resource or one since deleted, or the resource’s current state does not allow the change. detail says which, and errors names the field.
No
Pick another name or a new Idempotency-Key, or read the resource again and act on its current state. (more)
The key or the account sent more requests than its rate allows.
After Retry-After
Wait for the seconds Retry-After names, then send the request again; spread requests out if it recurs. (more)
Retries
Send a new Idempotency-Key with each request and the same one when you send it again: a repeat answers what the first request did, and the key reused for a different request answers 409 (see Idempotency).
429 carry Retry-After: wait that many seconds, then send the same request again.
A monthly spend budget (contracts/billing/budgets-v1.json). The figures, name, principals and created_at are present only for a caller who may see them (usage.read, or a caller the budget covers); any other member sees id, scope, stage, resets_at and raise_url.
Header
Status
Description
ETag
200
Current resource version for optional conditional updates.
Tonbo-Budget
200
Planned (ADR-0022 section 7). A Structured Field dictionary on every answer to a caller whose budget is at stage notice or above, such as stage=slow, scope=principals, used=0.91, resets="2026-12-01T00:00:00Z", from Billing's view at most 120 s old; used is left out for a caller who may not see the budget's figures.
The key’s role does not hold the capability the operation needs, the key is narrowed away from the resource, or the account already holds as many of the resource as it may.
No
Use a key whose role holds the capability, or one that is not narrowed; delete what you no longer need, or ask for a higher limit. (more)
Lower a monthly spend budget or add principals to it
PATCH /v1/budgets/{budget_id} · CLI: tonbo budget set
Needs budgets.write, which owner and admin hold. A narrowed key may not.
Through this API (any key or CLI login) only the principal budget that covers the caller's own principal changes, and only by lowering limit_micros or adding principals the caller is or created (add_principals); a raise, a rename, remove_principals, the account budget and any other budget answer 403 budget_raise_in_console with raise_url, since loosening a budget is the console's (contracts/billing/budgets-v1.json change_rules). A lower limit takes effect at the next wake, rollover or create.
Parameters
Name
In
Type
Required
Description
budget_id
path
string
yes
The budget's id. Matches ^bdg_[0-9a-f]{32}$.
If-Match
header
string
no
Optional conditional update; omitted requests use last-write-wins. At most 500 characters.
Request body
application/json, required. Unknown fields are refused.
Field
Type
Required
Description
name
string
no
A new name; only in the console. 1 to 80 characters.
limit_micros
integer
no
A new limit in micro-dollars; through this API only a lower one. 1000000 to 100000000000.
add_principals
array of string
no
Members to cover; through this API only the caller itself and Agents it created that no budget covers. At most 100 items.
remove_principals
array of string
no
Members to stop covering; only in the console. At most 100 items.
A monthly spend budget (contracts/billing/budgets-v1.json). The figures, name, principals and created_at are present only for a caller who may see them (usage.read, or a caller the budget covers); any other member sees id, scope, stage, resets_at and raise_url.
Header
Status
Description
ETag
200
Current resource version for optional conditional updates.
The change would loosen a budget or touch one that is not the caller's own: the account budget, a raise, a rename, removing a budget, adding another member's principal or moving a principal out. Outside the console a caller only creates a budget over principals it is or created, lowers the budget that covers it and adds its own principals to it (contracts/billing/budgets-v1.json change_rules). raise_url names the budget's page in the console.
No
Ask an owner or admin to make the change in the console at raise_url. (more)
The key’s role does not hold the capability the operation needs, the key is narrowed away from the resource, or the account already holds as many of the resource as it may.
No
Use a key whose role holds the capability, or one that is not narrowed; delete what you no longer need, or ask for a higher limit. (more)
The name is held by another live resource of the account, the Idempotency-Key already created another resource or one since deleted, or the resource’s current state does not allow the change. detail says which, and errors names the field.
No
Pick another name or a new Idempotency-Key, or read the resource again and act on its current state. (more)
A monthly spend budget (contracts/billing/budgets-v1.json). The figures, name, principals and created_at are present only for a caller who may see them (usage.read, or a caller the budget covers); any other member sees id, scope, stage, resets_at and raise_url.
Field
Type
Required
Description
id
string
yes
The budget's id. Matches ^bdg_[0-9a-f]{32}$.
scope
one of "account" or "principals"
yes
What the budget counts.
stage
one of "ok", "notice", "slow" or "exhausted"
yes
The budget's stage this month, as Billing last observed it.
resets_at
string (date-time)
yes
When the month ends and the budget resets, 00:00 UTC on the 1st.
raise_url
string (uri)
yes
The budget's page in the console, where an owner or admin raises or changes it.
name
string
no
The budget's name, unique in the account. 1 to 80 characters.
limit_micros
integer
no
The monthly limit in micro-dollars at list price. 1000000 to 100000000000.
settled_micros
integer
no
This month's charges at list price, the allowance's included. At least 0.
committed_micros
integer
no
What is reserved or used and not yet charged, such as awake Machines' current slices. At least 0.
principals
array of string
no
The members a principals budget covers, each a user id or agent.<agent id>; empty for the account budget.
covers_caller
boolean
no
Whether the budget covers the caller's own principal.
created_at
string (date-time)
no
When the budget was created.
updated_at
string (date-time)
no
When its name, limit or principals last changed.
observed_at
string (date-time) or null
no
When Billing last observed the stage and the figures; null before its first pass.
The budget a budget_exhausted or budget_slowdown refusal is about (ADR-0022 section 7). The figures and name are present only for a caller who may see them, as on Budget.
Field
Type
Required
Description
id
string
yes
The budget's id. Matches ^bdg_[0-9a-f]{32}$.
scope
one of "account" or "principals"
yes
What the budget counts.
name
string
no
The budget's name.
stage
one of "ok", "notice", "slow" or "exhausted"
yes
The budget's stage.
limit_micros
integer
no
The monthly limit in micro-dollars.
settled_micros
integer
no
This month's charges at list price.
committed_micros
integer
no
What is reserved or used and not yet charged.
resets_at
string (date-time)
yes
When the budget resets, 00:00 UTC on the 1st.
retry_at
string (date-time)
no
Present only on budget_exhausted; when to try again, the reset plus up to ten minutes.
slow_rate_micros_per_hour
integer
no
Present only on budget_slowdown; the hourly list price the budget's awake Machines may hold together.
largest_shape_that_fits
string or null
no
Present only on budget_slowdown; the largest shape a wake fits now, or null when none does.