> Fetch the index of every Tonbo docs page as Markdown at https://tonbo.dev/llms.txt

# Management API: Budgets

Last updated 3 November 2026

The account's monthly spend budgets (contracts/billing/budgets-v1.json). [The overview](https://tonbo.dev/docs/reference/management.md) covers what every operation shares: authentication, roles, errors, pagination, idempotency and If-Match.

- [`GET /budgets`](#list-budgets) List the account's monthly spend budgets
- [`POST /budgets`](#create-budget) Create a monthly spend budget
- [`GET /budgets/{budget_id}`](#get-budget) Read a monthly spend budget
- [`PATCH /budgets/{budget_id}`](#change-budget) Lower a monthly spend budget or add principals to it
- [Objects](#objects): [Budget](#schema-budget) and [BudgetRefusal](#schema-budget-refusal)

## List the account's monthly spend budgets {#list-budgets}

`GET /v1/budgets` · CLI: `tonbo budget list`

Needs [`account.read`](https://tonbo.dev/docs/reference/management.md#capability-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 {#list-budgets-response}

| Status | Answer |
| --- | --- |
| `200` | The account's budgets |

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array of [Budget](https://tonbo.dev/docs/reference/management/budgets.md#schema-budget) | yes | The budgets. |

| Header | Status | Description |
| --- | --- | --- |
| `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. |
| `WWW-Authenticate` | 401 | Authentication scheme required by this API. |
| `Retry-After` | 429 | Seconds before the client should retry. |

**Example 200 body**

```json
{
  "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 {#list-budgets-errors}

| Status | Code | When | Send again | What to do |
| --- | --- | --- | --- | --- |
| `401` | [`exchange_required`](https://tonbo.dev/docs/reference/management.md#exchange_required) | The key acts as an Agent, and an Agent’s key is never sent itself. | No | Exchange the key for a token at the endpoint the answer’s `token_endpoint` names, and send the token as `Authorization: Bearer`. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#exchange_required)) |
| `401` | [`unauthenticated`](https://tonbo.dev/docs/reference/management.md#unauthenticated) | The request carries no key or token, or one that is invalid, expired or revoked. | No | Send a valid key, or a token that has not expired, as `Authorization: Bearer`. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#unauthenticated)) |
| `403` | [`forbidden`](https://tonbo.dev/docs/reference/management.md#forbidden) | 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](https://tonbo.dev/docs/databases/troubleshooting/manage.md#forbidden)) |
| `429` | [`rate_limited`](https://tonbo.dev/docs/reference/management.md#rate_limited) | 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](https://tonbo.dev/docs/databases/troubleshooting/manage.md#rate_limited)) |

### Retries {#list-budgets-retries}

- A read: sending it again changes nothing.
- `429` carry `Retry-After`: wait that many seconds, then send the same request again.

**Request**

```shell
curl -sS "https://api.tonbo.dev/v1/budgets" \
  -H "Authorization: Bearer $TONBO_API_KEY"
```

## Create a monthly spend budget {#create-budget}

`POST /v1/budgets` · CLI: `tonbo budget add`

Needs [`budgets.write`](https://tonbo.dev/docs/reference/management.md#capability-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 {#create-budget-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 {#create-budget-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. |

### Response {#create-budget-response}

| Status | Answer |
| --- | --- |
| `201` | The budget, created or replayed |

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | [Budget](https://tonbo.dev/docs/reference/management/budgets.md#schema-budget) | yes | 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. |
| `WWW-Authenticate` | 401 | Authentication scheme required by this API. |
| `Retry-After` | 429 | Seconds before the client should retry. |

**Example 201 body**

```json
{
  "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 {#create-budget-errors}

| Status | Code | When | Send again | What to do |
| --- | --- | --- | --- | --- |
| `401` | [`exchange_required`](https://tonbo.dev/docs/reference/management.md#exchange_required) | The key acts as an Agent, and an Agent’s key is never sent itself. | No | Exchange the key for a token at the endpoint the answer’s `token_endpoint` names, and send the token as `Authorization: Bearer`. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#exchange_required)) |
| `401` | [`unauthenticated`](https://tonbo.dev/docs/reference/management.md#unauthenticated) | The request carries no key or token, or one that is invalid, expired or revoked. | No | Send a valid key, or a token that has not expired, as `Authorization: Bearer`. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#unauthenticated)) |
| `403` | [`budget_raise_in_console`](https://tonbo.dev/docs/reference/management.md#budget_raise_in_console) | 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](https://tonbo.dev/docs/machines/troubleshooting/manage.md#budget_raise_in_console)) |
| `403` | [`forbidden`](https://tonbo.dev/docs/reference/management.md#forbidden) | 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](https://tonbo.dev/docs/databases/troubleshooting/manage.md#forbidden)) |
| `409` | [`conflict`](https://tonbo.dev/docs/reference/management.md#conflict) | 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](https://tonbo.dev/docs/databases/troubleshooting/manage.md#conflict)) |
| `409` | [`idempotency_conflict`](https://tonbo.dev/docs/reference/management.md#idempotency_conflict) | The Idempotency-Key was already sent with a different request. | No | Send the request with a new Idempotency-Key, or send the request the key was first used for. ([more](https://tonbo.dev/docs/machines/troubleshooting/manage.md#idempotency_conflict)) |
| `422` | [`validation_error`](https://tonbo.dev/docs/reference/management.md#validation_error) | A parameter, header or body field breaks its rule; `errors` names each field. | No | Correct the fields `errors` names; the operation’s reference gives each one’s rule. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#validation_error)) |
| `429` | [`rate_limited`](https://tonbo.dev/docs/reference/management.md#rate_limited) | 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](https://tonbo.dev/docs/databases/troubleshooting/manage.md#rate_limited)) |

### Retries {#create-budget-retries}

- Send a new [`Idempotency-Key`](#create-budget-header-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](https://tonbo.dev/docs/reference/management.md#idempotency)).
- `429` carry `Retry-After`: wait that many seconds, then send the same request again.

**Request**

```shell
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-budget}

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

Needs [`account.read`](https://tonbo.dev/docs/reference/management.md#capability-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 {#get-budget-parameters}

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `budget_id` | path | string | yes | The budget's id. Matches `^bdg_[0-9a-f]{32}$`. |

### Response {#get-budget-response}

| Status | Answer |
| --- | --- |
| `200` | The budget |

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | [Budget](https://tonbo.dev/docs/reference/management/budgets.md#schema-budget) | yes | 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. |
| `WWW-Authenticate` | 401 | Authentication scheme required by this API. |
| `Retry-After` | 429 | Seconds before the client should retry. |

**Example 200 body**

```json
{
  "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 {#get-budget-errors}

| Status | Code | When | Send again | What to do |
| --- | --- | --- | --- | --- |
| `401` | [`exchange_required`](https://tonbo.dev/docs/reference/management.md#exchange_required) | The key acts as an Agent, and an Agent’s key is never sent itself. | No | Exchange the key for a token at the endpoint the answer’s `token_endpoint` names, and send the token as `Authorization: Bearer`. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#exchange_required)) |
| `401` | [`unauthenticated`](https://tonbo.dev/docs/reference/management.md#unauthenticated) | The request carries no key or token, or one that is invalid, expired or revoked. | No | Send a valid key, or a token that has not expired, as `Authorization: Bearer`. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#unauthenticated)) |
| `403` | [`forbidden`](https://tonbo.dev/docs/reference/management.md#forbidden) | 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](https://tonbo.dev/docs/databases/troubleshooting/manage.md#forbidden)) |
| `404` | [`not_found`](https://tonbo.dev/docs/reference/management.md#not_found) | No live resource of the key’s account has that name or id, or the key is narrowed away from it. | No | Check the name, and that the key belongs to the account that holds it; list the resources to see what exists. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#not_found)) |
| `429` | [`rate_limited`](https://tonbo.dev/docs/reference/management.md#rate_limited) | 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](https://tonbo.dev/docs/databases/troubleshooting/manage.md#rate_limited)) |

### Retries {#get-budget-retries}

- A read: sending it again changes nothing.
- `429` carry `Retry-After`: wait that many seconds, then send the same request again.

**Request**

```shell
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 {#change-budget}

`PATCH /v1/budgets/{budget_id}` · CLI: `tonbo budget set`

Needs [`budgets.write`](https://tonbo.dev/docs/reference/management.md#capability-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 {#change-budget-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 {#change-budget-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. |

### Response {#change-budget-response}

| Status | Answer |
| --- | --- |
| `200` | The budget, changed |

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | [Budget](https://tonbo.dev/docs/reference/management/budgets.md#schema-budget) | yes | 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. |
| `WWW-Authenticate` | 401 | Authentication scheme required by this API. |
| `Retry-After` | 429 | Seconds before the client should retry. |

**Example 200 body**

```json
{
  "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 {#change-budget-errors}

| Status | Code | When | Send again | What to do |
| --- | --- | --- | --- | --- |
| `401` | [`exchange_required`](https://tonbo.dev/docs/reference/management.md#exchange_required) | The key acts as an Agent, and an Agent’s key is never sent itself. | No | Exchange the key for a token at the endpoint the answer’s `token_endpoint` names, and send the token as `Authorization: Bearer`. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#exchange_required)) |
| `401` | [`unauthenticated`](https://tonbo.dev/docs/reference/management.md#unauthenticated) | The request carries no key or token, or one that is invalid, expired or revoked. | No | Send a valid key, or a token that has not expired, as `Authorization: Bearer`. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#unauthenticated)) |
| `403` | [`budget_raise_in_console`](https://tonbo.dev/docs/reference/management.md#budget_raise_in_console) | 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](https://tonbo.dev/docs/machines/troubleshooting/manage.md#budget_raise_in_console)) |
| `403` | [`forbidden`](https://tonbo.dev/docs/reference/management.md#forbidden) | 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](https://tonbo.dev/docs/databases/troubleshooting/manage.md#forbidden)) |
| `404` | [`not_found`](https://tonbo.dev/docs/reference/management.md#not_found) | No live resource of the key’s account has that name or id, or the key is narrowed away from it. | No | Check the name, and that the key belongs to the account that holds it; list the resources to see what exists. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#not_found)) |
| `409` | [`conflict`](https://tonbo.dev/docs/reference/management.md#conflict) | 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](https://tonbo.dev/docs/databases/troubleshooting/manage.md#conflict)) |
| `412` | [`precondition_failed`](https://tonbo.dev/docs/reference/management.md#precondition_failed) | If-Match does not name the resource’s current ETag: it changed since you read it. Nothing changed. | No | Read the resource again, check that the change still applies, and send it with the new ETag. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#precondition_failed)) |
| `422` | [`validation_error`](https://tonbo.dev/docs/reference/management.md#validation_error) | A parameter, header or body field breaks its rule; `errors` names each field. | No | Correct the fields `errors` names; the operation’s reference gives each one’s rule. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#validation_error)) |
| `429` | [`rate_limited`](https://tonbo.dev/docs/reference/management.md#rate_limited) | 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](https://tonbo.dev/docs/databases/troubleshooting/manage.md#rate_limited)) |

### Retries {#change-budget-retries}

- It takes no Idempotency-Key; its description above says what sending it again does.
- [`If-Match`](#change-budget-header-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](https://tonbo.dev/docs/reference/management.md#if-match)).
- `429` carry `Retry-After`: wait that many seconds, then send the same request again.

**Request**

```shell
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 {#objects}

### Budget {#schema-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`.

| 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. |

**Example Budget**

```json
{
  "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 {#schema-budget-refusal}

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. |
| `raise_url` | string (uri) | yes | The budget's page in the console. |
| `raise_roles` | array of one of `"owner"`, `"admin"` or `"member"` | yes | The roles that may raise it. |
| `raise_channel` | one of `"console"` | yes | Where it is raised; always `console`. |

**Example BudgetRefusal**

```json
{
  "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"
}
```
