Budgets
A budget is an amount of money for one calendar month, a subject that says whose spend the amount covers, and an action taken when the amount is reached. A budget on its own measures: it tracks spend against its limit and reports on it, and that is the whole of what it does. Stopping calls takes a budget policy, which reads the budget's threshold as its trigger and acts on the request path once the threshold is crossed. Budgets ship today, and budget policies are planned for the 2026 Q3 release.
Policies covers the machinery every control on the request path shares: the five types, the six scopes, how resolution works, and monitor mode. The budget type builds on that machinery, and there are points at which a budget stops being a guarantee.
Three pages cover budgets, and they answer different questions. This page defines what a budget is made of, and where its limits are. Set a budget and track spend against it covers creating one and reading it. Enforce budget caps with policies works through nine enforcement scenarios, including the cases where two budgets cover one key. Whether a budget is the right instrument at all is settled in Choose the right cost control for each workload.
A budget measures, a policy enforces
The split between measuring and enforcing runs through the whole policy model, and a budget is the clearest case of it.
A budget measures. It tracks spend, attributes it to a subject, and holds the threshold. Spend is evaluated in the management plane against aggregated request logs rather than inline at the gateway, so a budget never stops a request, whatever the meter reads. Crossing the limit changes nothing about what a caller can do next.
A policy enforces. It takes the budget's threshold as its trigger and acts on the request path when the threshold is crossed. Where its action is block, an exhausted budget means the user or client cannot make calls at all until the period resets or the limit is raised.
One surface owns the number and the report, the other owns the consequence, so the two never compete for the same job. The budget threshold is a cross-cutting trigger: unlike a guardrail match or a model failure, it originates outside the request path and reaches into it.
An amount, a subject, and an action
Budgets live in the Admin Console, under Usage → Budgets. Grouping them with the other policy types instead is proposed, on the reasoning that a budget carries a target, an action, and a status, and a status is something only a rule has.
A budget is money, never tokens or requests. To cap how fast something can call, a request rate or a token rate, use a rate limit instead. See Stop runaway workloads before they burn the budget.
| Part | What it is |
|---|---|
| Amount | US dollars |
| Subject | a team, each user on a team, or one API key |
| Period | the calendar month, starting on the 1st at 00:00 UTC, the same instant in every timezone. Fixed when the budget is created and not changeable afterward |
| Action | block, which refuses the request, or fall back, which switches to another model and keeps serving. Falling back is available on an API key budget only: a team spans projects, and models are enabled per project, so a team budget has no single model it could name. The same constraint decides which scopes each policy type offers |
| Mode | monitor or active, the same two modes every policy type carries. A budget in monitor records what it would have done and changes nothing. Monitor is not a third action |
A subject reaches keys by owner or by name
The subject is the whole of what a budget can address. There are three kinds, and the difference between them is which API keys the amount ends up covering.
Three subjects is the simplified set the dashboard offers. A budget can take all six scopes in the policy model, and the dashboard work in flight adds a project and a tag selector, so narrowing to three is a proposal rather than a settled decision.
| Subject | The amount covers | Keys it reaches |
|---|---|---|
| a team | one shared total for the whole team | every key owned by every member |
| each user on a team | the same amount applied to each member separately | every key owned by that member |
| one API key | that key alone | exactly the key named |
So a budget reaches a key one of two ways: through the person who owns it, or by naming the key. There is nothing in between. No budget can name an application, a model, a project, or a piece of work, which is why capping a piece of work means capping the key it uses.
A subject carries one budget policy. One budget per team, per each-user amount, per API key, so there is no shorter limit sitting underneath the monthly one.
Overlapping budgets all apply, and the first exhausted wins
A narrower policy can never loosen a broader one takes this shape for budgets.
- Every budget covering a key applies. They are checked together.
- The request stops when any one of them is exhausted: the first to run out, not the smallest and not the most specific.
- One exception, and only one: an API key with its own budget stops drawing on its owner's amount. Nothing else is ever replaced, so a team's total cannot be circumvented by giving a key a bigger number.
The exception covers what a key draws on, not what it adds up to. That key's spend still counts toward its owner's amount, so an exception key can exhaust the allowance behind every other key its owner holds. Taking an exception key out of its owner's amount in both directions is proposed, but it is implemented in neither change currently open, so the behavior described here is what ships.
Because nothing overrides anything, adding a budget can only reduce what a key is able to spend, never raise it. The one exception above is the only way a new budget gives a key more room, and even then only in place of the amount it displaces. 5: Extra room for one agent is that case worked through.
A blocked caller gets 429 and the budget that stopped it
A blocked request is refused with 429, carrying a payload that says which budget stopped it. The key stays blocked until the period resets or its limit is raised. Raising a limit is covered in Raise a spend ceiling without interrupting delivery.
Because a 429 is also what a rate limit returns, the payload is what distinguishes the two. 8: The budget that blocked a key covers reading it.
Enforcement lags by minutes and fails open
A budget does not take effect the instant it is reached. Token counts have to be translated into currency spend and totaled, the list of exhausted keys sent to the data plane, and the data plane has to pick it up, which takes a few minutes.
Enforcement also fails open. Where the list of exhausted keys does not arrive, or cannot be read, requests are served. A delivery failure means allow rather than deny, so a budget is never a guarantee that spend stops at the number.
Both are why a budget cannot always stop a runaway loop on its own. Pair it with a rate limit, the token control the data plane enforces inline.
Spend is calculated from tokens, not read from the invoice
Spend is worked out from the tokens in each response and the price of the model that served it. Prices come from a catalog of published provider pricing, refreshed regularly. It is not read from the provider's bill.
Three consequences follow, and they matter most when a budget is meant to hold a number agreed with finance.
A negotiated rate has to be entered and kept current. A discount is entered as a per-model override. Nothing detects a rate changing, so an override left behind after a contract renegotiation quietly moves every budget that touches that model.
Where capacity is bought rather than tokens, the two numbers are not comparable at all. Provisioned throughput, committed spend and subscriptions cost the same whether one request is sent or a million, so a figure calculated per token cannot track that invoice.
So a budget caps what usage is worth at the configured prices, not what is billed. The two agree while usage is paid per token at the prices in the catalog, and drift apart when it is not. Reconciling the calculated figure against the invoice is a separate exercise, covered in Split the AI bill across the teams that caused it.
Terms introduced on this page
Terms below appear only on this page.
Also used here and defined in the Glossary, with the definition on hover: budget, budget policy, calculated cost.
| Term | Meaning |
|---|---|
| Subject | What a budget's amount covers: a team, each user on a team, or one API key. |
| Amount | The monthly limit, in US dollars. |
| Period | The calendar month, from the 1st at 00:00 UTC. Fixed when the budget is created. |
| Exhausted | The state of a budget whose spend has reached its amount. |
| Cross-cutting trigger | A trigger originating outside the request path, such as a budget threshold, that reaches into it. |
| Fail open | Serving requests where the list of exhausted keys does not arrive at the data plane. |
| Monitor | The mode in which a budget policy records what it would have done and changes nothing. |
Where to go next
Set a budget and track spend against it
Turn a number agreed with finance into a budget that tracks spend and alerts as the ceiling nears.
Enforce budget caps with policies
Nine scenarios, from one key with one ceiling to overlapping subjects and a cheaper model instead of a refusal.
Policies
The shared model behind every control: the five types, the six scopes, resolution, and monitor mode.
Cost and quota management
The three stages of cost control: analytics, budget monitoring, and enforcement.