Budgets
A budget is an amount of money for one period, 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 measuring does. Stopping calls is the budget's action: it reads the budget's threshold as its trigger and acts on the request path once the threshold is crossed.
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, its action 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 the meter itself never stops a request. What crossing the limit changes is decided by the budget's action, and the default action only watches.
Its action enforces. An enforcing action takes the budget's threshold as its trigger and acts on the request path when the threshold is crossed. Where the 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. A budget whose action enforces is what the documentation calls a budget policy: same object, enforcing action chosen.
The meter owns the number and the report, the action 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.
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 | daily, weekly, or monthly. A daily period resets at midnight UTC, a weekly period on Monday, and a monthly period on the 1st at 00:00 UTC, the same instant in every timezone. Chosen when the budget is created and editable 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.
| 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 | the client behind the key, within the key's project | every key of that client in the project, so a rotation pair is covered while both keys are live |
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 key budget binds to the client, not the credential. Since 0.3.0, a budget created on an API key records the key's client (the application behind the key) at write time and caps that client within the key's project. Rotating the key carries the budget to the replacement, and the period's spend is summed across every key of the client in that project. Before 0.3.0 the budget named the key row itself, so a rotation stranded it on the retired credential. The binding is also what the write-time refusals protect: a per-key budget can only be created on, or retargeted to, a key in the project named in the request (a key in another project is reported as not found), and a key cannot be moved out of a client whose budget is active until the budget is deactivated.
A subject carries one budget policy. One budget per team, per each-user amount, and per project, client, and intent for a key budget (one default and one bound may coexist); creating, retargeting, or activating a second key budget on another key of the same client is refused, as is attaching an already budgeted key to such a client. Periods therefore replace rather than nest: a second budget on the same subject and target takes the place of the first, so a daily amount cannot sit underneath a 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. A spent team pool stops every member's key, even a key with a far larger budget of its own.
- 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. That is the behavior that ships.
Settings come from the most specific budget; ceilings come from all of them. The allowance a key spends against, what happens when that allowance runs out, and the fallback model where the action is fall back are all the most specific covering budget's: a key's own budget beats its owner's amount, which beats the team's. Exhaustion is still checked against every covering budget, which is what keeps a broader pool binding on a key whose own budget is larger.
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 limit for one period, in US dollars. |
| Period | Daily, weekly, or monthly. Chosen when the budget is created and editable afterward. |
| 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.