PricingConsole

Management API: Budgets

Last updated 3 November 2026

View .md

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.

List the account's monthly spend budgets

GET /v1/budgets · CLI: tonbo budget list

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.

Response

StatusAnswer
200The account's budgets
FieldTypeRequiredDescription
dataarray of BudgetyesThe budgets.
HeaderStatusDescription
Tonbo-Budget200Planned (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.
WWW-Authenticate401Authentication scheme required by this API.
Retry-After429Seconds before the client should retry.
Example 200 body
{
  "data": [
    {
      "id": "bdg_3f1c2a9e5b7d4c8e9f102a3b4c5d6e7f",
      "scope": "account",
      "stage": "ok",
      "resets_at": "2026-11-02T09:30:00.000Z",
      "raise_url": "https://example.com",
      "name": "<name>",
      "limit_micros": 1000000,
      "settled_micros": 0,
      "committed_micros": 0,
      "principals": [
        "agent.3f1c2a9e-5b7d-4c8e-9f10-2a3b4c5d6e7f"
      ],
      "covers_caller": false,
      "created_at": "2026-11-02T09:30:00.000Z",
      "updated_at": "2026-11-02T09:30:00.000Z",
      "observed_at": "2026-11-02T09:30:00.000Z"
    }
  ]
}

Errors

StatusCodeWhenSend againWhat to do
401exchange_requiredThe key acts as an Agent, and an Agent’s key is never sent itself.NoExchange the key for a token at the endpoint the answer’s token_endpoint names, and send the token as Authorization: Bearer. (more)
401unauthenticatedThe request carries no key or token, or one that is invalid, expired or revoked.NoSend a valid key, or a token that has not expired, as Authorization: Bearer. (more)
403forbiddenThe 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.NoUse 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)
429rate_limitedThe key or the account sent more requests than its rate allows.After Retry-AfterWait for the seconds Retry-After names, then send the request again; spread requests out if it recurs. (more)

Retries

  • A read: sending it again changes nothing.
  • 429 carry Retry-After: wait that many seconds, then send the same request again.
Request
curl -sS "https://api.tonbo.dev/v1/budgets" \
  -H "Authorization: Bearer $TONBO_API_KEY"

Create a monthly spend budget

POST /v1/budgets · CLI: tonbo budget add

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

NameInTypeRequiredDescription
Idempotency-KeyheaderstringyesA 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.

FieldTypeRequiredDescription
scopeone of "account" or "principals"yesprincipals through this API; account only in the console.
namestringyesThe budget's name, 1 to 80 characters without surrounding spaces, unique in the account. 1 to 80 characters.
limit_microsintegeryesThe monthly limit in micro-dollars at list price, $1 to $100,000. 1000000 to 100000000000.
principalsarray of stringnoFor 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.

Response

StatusAnswer
201The budget, created or replayed
FieldTypeRequiredDescription
dataBudgetyesA 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.
HeaderStatusDescription
ETag201Current resource version for optional conditional updates.
WWW-Authenticate401Authentication scheme required by this API.
Retry-After429Seconds before the client should retry.
Example 201 body
{
  "data": {
    "id": "bdg_3f1c2a9e5b7d4c8e9f102a3b4c5d6e7f",
    "scope": "account",
    "stage": "ok",
    "resets_at": "2026-11-02T09:30:00.000Z",
    "raise_url": "https://example.com",
    "name": "<name>",
    "limit_micros": 1000000,
    "settled_micros": 0,
    "committed_micros": 0,
    "principals": [
      "agent.3f1c2a9e-5b7d-4c8e-9f10-2a3b4c5d6e7f"
    ],
    "covers_caller": false,
    "created_at": "2026-11-02T09:30:00.000Z",
    "updated_at": "2026-11-02T09:30:00.000Z",
    "observed_at": "2026-11-02T09:30:00.000Z"
  }
}

Errors

StatusCodeWhenSend againWhat to do
401exchange_requiredThe key acts as an Agent, and an Agent’s key is never sent itself.NoExchange the key for a token at the endpoint the answer’s token_endpoint names, and send the token as Authorization: Bearer. (more)
401unauthenticatedThe request carries no key or token, or one that is invalid, expired or revoked.NoSend a valid key, or a token that has not expired, as Authorization: Bearer. (more)
403budget_raise_in_consoleThe 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.NoAsk an owner or admin to make the change in the console at raise_url. (more)
403forbiddenThe 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.NoUse 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)
409conflictThe 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.NoPick another name or a new Idempotency-Key, or read the resource again and act on its current state. (more)
409idempotency_conflictThe Idempotency-Key was already sent with a different request.NoSend the request with a new Idempotency-Key, or send the request the key was first used for. (more)
422validation_errorA parameter, header or body field breaks its rule; errors names each field.NoCorrect the fields errors names; the operation’s reference gives each one’s rule. (more)
429rate_limitedThe key or the account sent more requests than its rate allows.After Retry-AfterWait 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.
Request
curl -sS "https://api.tonbo.dev/v1/budgets" \
  -H "Authorization: Bearer $TONBO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"scope":"account","name":"<name>","limit_micros":1000000}'

Read a monthly spend budget

GET /v1/budgets/{budget_id} · CLI: tonbo budget show

Needs account.read, which owner, admin and member hold. A narrowed key may call it.

One budget, with the figures the caller may see (as listBudgets).

Parameters

NameInTypeRequiredDescription
budget_idpathstringyesThe budget's id. Matches ^bdg_[0-9a-f]{32}$.

Response

StatusAnswer
200The budget
FieldTypeRequiredDescription
dataBudgetyesA 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.
HeaderStatusDescription
ETag200Current resource version for optional conditional updates.
Tonbo-Budget200Planned (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.
WWW-Authenticate401Authentication scheme required by this API.
Retry-After429Seconds before the client should retry.
Example 200 body
{
  "data": {
    "id": "bdg_3f1c2a9e5b7d4c8e9f102a3b4c5d6e7f",
    "scope": "account",
    "stage": "ok",
    "resets_at": "2026-11-02T09:30:00.000Z",
    "raise_url": "https://example.com",
    "name": "<name>",
    "limit_micros": 1000000,
    "settled_micros": 0,
    "committed_micros": 0,
    "principals": [
      "agent.3f1c2a9e-5b7d-4c8e-9f10-2a3b4c5d6e7f"
    ],
    "covers_caller": false,
    "created_at": "2026-11-02T09:30:00.000Z",
    "updated_at": "2026-11-02T09:30:00.000Z",
    "observed_at": "2026-11-02T09:30:00.000Z"
  }
}

Errors

StatusCodeWhenSend againWhat to do
401exchange_requiredThe key acts as an Agent, and an Agent’s key is never sent itself.NoExchange the key for a token at the endpoint the answer’s token_endpoint names, and send the token as Authorization: Bearer. (more)
401unauthenticatedThe request carries no key or token, or one that is invalid, expired or revoked.NoSend a valid key, or a token that has not expired, as Authorization: Bearer. (more)
403forbiddenThe 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.NoUse 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)
404not_foundNo live resource of the key’s account has that name or id, or the key is narrowed away from it.NoCheck the name, and that the key belongs to the account that holds it; list the resources to see what exists. (more)
429rate_limitedThe key or the account sent more requests than its rate allows.After Retry-AfterWait for the seconds Retry-After names, then send the request again; spread requests out if it recurs. (more)

Retries

  • A read: sending it again changes nothing.
  • 429 carry Retry-After: wait that many seconds, then send the same request again.
Request
curl -sS "https://api.tonbo.dev/v1/budgets/<budget_id>" \
  -H "Authorization: Bearer $TONBO_API_KEY"

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

NameInTypeRequiredDescription
budget_idpathstringyesThe budget's id. Matches ^bdg_[0-9a-f]{32}$.
If-MatchheaderstringnoOptional conditional update; omitted requests use last-write-wins. At most 500 characters.

Request body

application/json, required. Unknown fields are refused.

FieldTypeRequiredDescription
namestringnoA new name; only in the console. 1 to 80 characters.
limit_microsintegernoA new limit in micro-dollars; through this API only a lower one. 1000000 to 100000000000.
add_principalsarray of stringnoMembers to cover; through this API only the caller itself and Agents it created that no budget covers. At most 100 items.
remove_principalsarray of stringnoMembers to stop covering; only in the console. At most 100 items.

Response

StatusAnswer
200The budget, changed
FieldTypeRequiredDescription
dataBudgetyesA 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.
HeaderStatusDescription
ETag200Current resource version for optional conditional updates.
WWW-Authenticate401Authentication scheme required by this API.
Retry-After429Seconds before the client should retry.
Example 200 body
{
  "data": {
    "id": "bdg_3f1c2a9e5b7d4c8e9f102a3b4c5d6e7f",
    "scope": "account",
    "stage": "ok",
    "resets_at": "2026-11-02T09:30:00.000Z",
    "raise_url": "https://example.com",
    "name": "<name>",
    "limit_micros": 1000000,
    "settled_micros": 0,
    "committed_micros": 0,
    "principals": [
      "agent.3f1c2a9e-5b7d-4c8e-9f10-2a3b4c5d6e7f"
    ],
    "covers_caller": false,
    "created_at": "2026-11-02T09:30:00.000Z",
    "updated_at": "2026-11-02T09:30:00.000Z",
    "observed_at": "2026-11-02T09:30:00.000Z"
  }
}

Errors

StatusCodeWhenSend againWhat to do
401exchange_requiredThe key acts as an Agent, and an Agent’s key is never sent itself.NoExchange the key for a token at the endpoint the answer’s token_endpoint names, and send the token as Authorization: Bearer. (more)
401unauthenticatedThe request carries no key or token, or one that is invalid, expired or revoked.NoSend a valid key, or a token that has not expired, as Authorization: Bearer. (more)
403budget_raise_in_consoleThe 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.NoAsk an owner or admin to make the change in the console at raise_url. (more)
403forbiddenThe 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.NoUse 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)
404not_foundNo live resource of the key’s account has that name or id, or the key is narrowed away from it.NoCheck the name, and that the key belongs to the account that holds it; list the resources to see what exists. (more)
409conflictThe 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.NoPick another name or a new Idempotency-Key, or read the resource again and act on its current state. (more)
412precondition_failedIf-Match does not name the resource’s current ETag: it changed since you read it. Nothing changed.NoRead the resource again, check that the change still applies, and send it with the new ETag. (more)
422validation_errorA parameter, header or body field breaks its rule; errors names each field.NoCorrect the fields errors names; the operation’s reference gives each one’s rule. (more)
429rate_limitedThe key or the account sent more requests than its rate allows.After Retry-AfterWait for the seconds Retry-After names, then send the request again; spread requests out if it recurs. (more)

Retries

  • It takes no Idempotency-Key; its description above says what sending it again does.
  • If-Match is optional: send the ETag you read, and a 412 precondition_failed means the resource changed since; read it again and decide (see If-Match).
  • 429 carry Retry-After: wait that many seconds, then send the same request again.
Request
curl -sS -X PATCH "https://api.tonbo.dev/v1/budgets/<budget_id>" \
  -H "Authorization: Bearer $TONBO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Objects

Budget

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.

FieldTypeRequiredDescription
idstringyesThe budget's id. Matches ^bdg_[0-9a-f]{32}$.
scopeone of "account" or "principals"yesWhat the budget counts.
stageone of "ok", "notice", "slow" or "exhausted"yesThe budget's stage this month, as Billing last observed it.
resets_atstring (date-time)yesWhen the month ends and the budget resets, 00:00 UTC on the 1st.
raise_urlstring (uri)yesThe budget's page in the console, where an owner or admin raises or changes it.
namestringnoThe budget's name, unique in the account. 1 to 80 characters.
limit_microsintegernoThe monthly limit in micro-dollars at list price. 1000000 to 100000000000.
settled_microsintegernoThis month's charges at list price, the allowance's included. At least 0.
committed_microsintegernoWhat is reserved or used and not yet charged, such as awake Machines' current slices. At least 0.
principalsarray of stringnoThe members a principals budget covers, each a user id or agent.<agent id>; empty for the account budget.
covers_callerbooleannoWhether the budget covers the caller's own principal.
created_atstring (date-time)noWhen the budget was created.
updated_atstring (date-time)noWhen its name, limit or principals last changed.
observed_atstring (date-time) or nullnoWhen Billing last observed the stage and the figures; null before its first pass.
Example Budget
{
  "id": "bdg_3f1c2a9e5b7d4c8e9f102a3b4c5d6e7f",
  "scope": "account",
  "stage": "ok",
  "resets_at": "2026-11-02T09:30:00.000Z",
  "raise_url": "https://example.com",
  "name": "<name>",
  "limit_micros": 1000000,
  "settled_micros": 0,
  "committed_micros": 0,
  "principals": [
    "agent.3f1c2a9e-5b7d-4c8e-9f10-2a3b4c5d6e7f"
  ],
  "covers_caller": false,
  "created_at": "2026-11-02T09:30:00.000Z",
  "updated_at": "2026-11-02T09:30:00.000Z",
  "observed_at": "2026-11-02T09:30:00.000Z"
}

BudgetRefusal

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.

FieldTypeRequiredDescription
idstringyesThe budget's id. Matches ^bdg_[0-9a-f]{32}$.
scopeone of "account" or "principals"yesWhat the budget counts.
namestringnoThe budget's name.
stageone of "ok", "notice", "slow" or "exhausted"yesThe budget's stage.
limit_microsintegernoThe monthly limit in micro-dollars.
settled_microsintegernoThis month's charges at list price.
committed_microsintegernoWhat is reserved or used and not yet charged.
resets_atstring (date-time)yesWhen the budget resets, 00:00 UTC on the 1st.
retry_atstring (date-time)noPresent only on budget_exhausted; when to try again, the reset plus up to ten minutes.
slow_rate_micros_per_hourintegernoPresent only on budget_slowdown; the hourly list price the budget's awake Machines may hold together.
largest_shape_that_fitsstring or nullnoPresent only on budget_slowdown; the largest shape a wake fits now, or null when none does.
raise_urlstring (uri)yesThe budget's page in the console.
raise_rolesarray of one of "owner", "admin" or "member"yesThe roles that may raise it.
raise_channelone of "console"yesWhere it is raised; always console.
Example BudgetRefusal
{
  "id": "bdg_3f1c2a9e5b7d4c8e9f102a3b4c5d6e7f",
  "scope": "account",
  "name": "<name>",
  "stage": "ok",
  "limit_micros": 1,
  "settled_micros": 1,
  "committed_micros": 1,
  "resets_at": "2026-11-02T09:30:00.000Z",
  "retry_at": "2026-11-02T09:30:00.000Z",
  "slow_rate_micros_per_hour": 1,
  "largest_shape_that_fits": "<largest_shape_that_fits>",
  "raise_url": "https://example.com",
  "raise_roles": [
    "owner"
  ],
  "raise_channel": "console"
}