Budgets

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

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
• Lab: Set a budget and watch the fallback