Set a Budget

Tasks

Create a rule to cap spend for an organization, team, or user, set a hard session-level cap, and configure the alerts that notify you as spend approaches those limits.

Create a budget rule

1. Navigate to Cost → Budgets → Rules.

2. Click + New rule in the top-right corner and choose a starting template:

   Template	Use for
   Org spend ceiling	Global limit across all models for the whole organization
   Team budget	Total cap for one team across all models
   Model cap	Limit one model family (e.g. claude-opus*) at any scope
   Blank rule	Start from scratch

3. Set the rule's Scope — Global (all identities), Team (a named group), or User (a specific identity) — and its Target (the team name or user email, or * for Global).

4. Set the Model match — a glob pattern such as claude-opus*, gpt-4o, or * for all models. The first matching rule within each scope applies.

5. Set the Limit (maximum spend in USD) and the Window — a rolling period of 1h, 24h, 7d, or 30d.

6. Choose what happens when the limit is reached:

   Mode	What happens
   Deny	Requests are blocked until the window resets.
   Audit	Requests are allowed; overage is tracked and shown in the Overview "Audit-mode Overage" tile.
   Warn	Requests are allowed and recorded as a warning.
   Require approval	Requests are held for a manager to approve or deny in the Approvals queue.

7. Set Warn at — the percentage of the limit above which every request is recorded as a warning, for as long as spend stays under the hard limit (this repeats on each request, not just the first crossing — there's no per-window dedupe yet). Default: 80%. A budget_warning notification at this threshold is not yet wired for per-model rules — track spend via the Overview and Effective budget inspector in the meantime.

8. Save the rule. Use the Effective budget inspector at the top of the Rules tab to type any identity and model and confirm which rules bind, the remaining headroom, and the decision for the next request.

note

Rules are AND-enforced: a request must pass the first matching rule in every applicable scope (global, team, user — plus agent and token, configurable via the API; see the warning below). If multiple rules match a request, all of them apply.

warning

If you (or an integration) configured an agent- or token-scoped budget rule directly via the API — the Rules UI currently only exposes Global/Team/User — that rule now enforces for the first time. Previously, agent- and token-scoped rules were saved successfully but silently never matched any request; if you have one, verify its limit is still what you intend before your next request hits it. The Effective budget inspector will now show these rules binding where it previously showed nothing.

tip

To promote an audit-mode rule to Deny once you've reviewed the overage it would have caught, use the one-click promote action from the Overview tab.

Set the default session cap

1. Navigate to Cost → Budgets → Limits.

2. Set Default session cap — the maximum spend (USD) for any single session. When a session hits this cap, further requests are blocked until the session ends or an admin resets it. Set to 0 to disable.

Individual sessions can override the default via their PAT settings.

Configure alerts

Alerts notify you as spend approaches a limit — they do not, on their own, block requests. Configure them in Cost → Budgets → Alerts.

1. Under Budget warning thresholds, add one or more percentage values (e.g. 75, 90). Each threshold fires a budget_warning notification at most once per window per rule. Notifications are delivered to:

   • The developer whose spend triggered the alert (in-app and email if configured)
   • Administrators (configurable in Settings → Notifications)
   • Slack or Teams (if an integration is configured)

2. Under Session spend alert, set a USD threshold at which an in-app notification fires the first time a session's spend crosses that value. Set to 0 to disable. This is independent of the session cap configured in Limits — it only notifies, it does not block requests.

note

For conditional enforcement near a budget threshold — for example, requiring a ticket ID once spend exceeds 80% — use a CEL policy with object.modelBudget.team.pctUsed.

Exceptions

A developer denied by a model-cap rule can be granted a time-bounded exception: an approved exception targeting controller budget.model-cap, scoped to the same team/user/agent/token tier as the rule, with the model pattern (e.g. claude-opus*) as its subject, adds the exception's USD amount to that rule's limit for the developer's next request. When the exception expires (or is revoked), the added amount is dropped automatically — no cleanup needed.

Policies can read the resolved, exception-adjusted limits as object.defaults.budget.limits. See Request a config-target exception for how a developer requests one and how you approve it.

note

This is a durable, rolling-cap exception — separate from a one-time, single-session top-up. If a developer just needs a bit more headroom to finish their current session, see Grant a session budget top-up instead; approving one never affects the other.

See also

• Cost Governance