# Budgets

Cap spend per period for every agent or one agent, cap any scope in dollars or tokens, choose to refuse or fall back at the limit, and pace callers with rate limits.

## Kinds of budget

- **Per-agent budgets:** a default that covers every agent, and an override for one agent (`/api/budgets`). Dollars only.
- **Scoped budgets:** a limit on any scope, in dollars, tokens or both (`/api/budgets/scoped/{name}`).

| Scope kind | Counts |
| --- | --- |
| instance | Everything |
| tenant | One tenant's calls |
| tag | Agents with a tag, such as `team=hr` |
| model / provider | Calls to one model or provider |
| user | One person's calls, across agents |
| agent | One agent, including its sub-agents |

A cap stops the model call, never the ticket. Triage, deduplication and routing keep running, and a self-managed agent is told to retry after the reset.

## The per-agent table

Open **AI Gateway › Budgets**. The table lists the default and every agent that uses a model, with its **Status** (Capped, Warning, Exhausted or No cap), **Spend this period** against the cap, the **Limit** as set ("$200 a month, warns at 80%" or "No cap") and the **Recipients** of its warnings.

- Search by agent name, id, display name or tag.
- Filter by **Status**.
- Sort by **Agent**, **Spend this period** or **Limit** by clicking the heading. Pages hold 25 rows.
- **+ Create default** and **+ Create override** at the top open the quick create flows.

### Edit a budget

1. Choose **Edit** on the row. A drawer opens with the budget's seven fields.

   | Field | Notes |
   | --- | --- |
   | Limit (USD) | Dollars per period. Leave it empty to remove the cap: you are asked to confirm, and the budget is deleted |
   | Period | Per month, per week or per day. Calendar periods in UTC: a month resets on the 1st, a week on Monday |
   | Warn at (%) | The share of the limit at which a warning is recorded and governance alert integrations are notified. 0 is off |
   | Notify | Console usernames, comma separated, up to 50. Each is emailed at the warning and at the cap. An unknown name is refused |
   | Display name | Descriptive only, up to 253 characters. The budget stays the agent's |
   | Tags | `key=value`, comma separated, up to 50 tags with values up to 256 characters. A key given twice is refused |

2. Choose **Save**. A refusal is shown under the field it concerns, or above the footer when it is a policy's. The drawer keeps what you typed until it is saved, and asks before discarding it.

A cap counts from the hour it was set, and changing it later keeps that count. An agent's own cap only tightens the default: the lower of the two binds. On an instance with tenants, a tenant's page edits that tenant's budgets. A shared agent is shown read-only there, since its cap is an instance budget.

Readers see the table and the fields but not **Edit**, which needs `budgets.create` for a new cap and `budgets.update` or `budgets.delete` for a stored one.

## Create a scoped budget

1. Open **Budgets** and fill in the row under **Scoped budgets**.

   | Field | Notes |
   | --- | --- |
   | Name | Lowercase. It is the budget's identity in the URL and the audit log |
   | Scope | Kind and value, for example **A tag** `team=hr` |
   | USD / tokens | Either or both |
   | Period | Per month, per week or per day, counted from the start of the period |
   | At the limit | **At the limit: refuse** or **At the limit: fall back** |
   | Fallback | For fall back: the cheaper model, and optionally a provider (blank keeps the same one) |

   A display name can be set through the API (`display_name`).

2. Choose **Add scoped budget**. The list shows **Spend this period** and **Status** (Warning, Capped or Exhausted), with an **At risk** note when the projection says the cap will run out before the reset. Headings sort the list.

## At the limit

- **Refuse** (the default): further calls in scope are refused until the period resets.
- **Fall back:** calls are re-routed to the cheaper model you named, and each is audited as `budget.fallback`. Falling back to the same model, or to one that is not cheaper on the rate card, is not allowed (unless the budget is on a model or provider and the fallback leaves it).
- Only governed model calls can be re-routed. Gateway pre-flight checks and delegation are refused instead.
- If any budget that applies to a call is exhausted, the call is refused, even if another would fall back.

## Rate limits

The same page has **Rate limits** (**Add rate limit**): **Requests a minute**, **Requests a second**, **Tokens a minute** and **Calls in flight at the same time**, per scope: agent, client, tenant, person, tool, model or provider (`/api/rate-limits`). The list sorts by rule, scope or refusals. Loosening or removing a rule asks for a reason.

## Next steps

- [Cost and usage](/docs/monitor/cost-usage)
- [Lab: Set a budget and watch the fallback](/docs/labs/budget-fallback)