Keep each team's spend inside an agreed ceiling
Enterprise Tier
Spend questions rarely arrive as questions about API keys. They arrive as questions about people and the parts of the business those people belong to. A finance partner wants to know when the data-science organisation is approaching the number agreed for the quarter, without anyone having to watch it by hand. This guide turns that agreed ceiling into a budget that tracks spend and raises an alert as the limit is approached or crossed: baseline the existing spend, create the budget at the right scope, and set the monthly limit that drives the alert.
Persona: Platform operator working in the Admin Dashboard, implementing a ceiling agreed with finance or the relevant business owner.
Estimated time: 20 to 30 minutes for an initial setup with one or two teams; 5 to 10 minutes per budget thereafter.
Outcomes
By the end of this guide:
- Usage and cost, in both tokens and money, can be read per user and per team over a chosen period.
- A monthly spend ceiling exists for a chosen team or person, at a scope that matches how the cost is owned.
- Spend is tracked against that ceiling and an alert is raised as the budget is approached or crossed, so the operator and business owner can act in time.
Agent Router budgets are an observability control, not an inline gateway block. Spend is evaluated on the management plane against aggregated request logs, so a budget raises alerts and shows burn against the ceiling but does not reject requests once the limit is reached. To cut traffic off inline, use a rate limit instead. See Stop runaway workloads.
Prerequisites
- Administrator access to the Admin Dashboard, typically the
super_adminorbilling_adminrole. - API keys that follow the per-purpose convention, so that usage attributed to a user or team is precise rather than blurred across shared credentials. The convention is established in Onboard developers and issue keys.
- Group identity flowing in from the identity provider. Team budgets are only as meaningful as the team membership behind them; the mapping is covered in Map Entra ID groups to business functions.
- Agreement with finance or the relevant business owner on the ceiling itself and on what should happen when it is reached. A budget is a policy decision before it is a configuration; the operator implements the decision rather than originating it.
Step 1: Read the baseline before setting the number
Before a budget can be set sensibly, the existing consumption has to be visible at the same dimension the budget will use.
- Sign in to the Admin Dashboard and open Usage → Analytics.
- Select tab Cost.
- Apply a time range that matches the budgeting cadence: last 30 days or the last billing cycle is the usual choice for a monthly budget.
- Select the Group by User breakdown and review the ranked list. Each row carries the request count, token totals, and estimated cost for that user across all of their keys.
- Select a user row to drill into the specific keys, models, and costs behind it. To compare several people or teams side by side before you set the number, see Compare user and team spend in Analytics.
The team dimension is the aggregate of its members. Where the deployment surfaces a team breakdown directly, it is read the same way; where it does not, team spend is derived by summing the cost of the users mapped to that team, which is exactly why the group-to-team mapping has to be correct before team budgets carry any weight. A user counted in the wrong team is spend charged to the wrong cost centre.
Size the ceiling from this baseline rather than guesswork: comfortably above normal consumption but well below any level that would be a problem. A budget for a team with no history is tightened rather than left loose; real traffic surfaces the true shape quickly, and relaxing a tight ceiling is a low-risk adjustment.
Step 2: Choose the budget scope
Open the New budget dialog from Usage → Budgets in the Admin Dashboard and select one of the three scopes.
| Scope | What the limit covers | When it fits |
|---|---|---|
| Whole team | One shared limit pooled across all members of the team | A cost centre with a single ceiling over everyone charged to it, where one member's heavy month can be offset by another's light one |
| Each teammate | The same limit applied to every member individually | A per-person allowance that should hold for each member regardless of what the rest of the team spends |
| One person | A limit that applies to a single user | An individual whose consumption is bounded on its own, independent of any team |
A pooled limit bounds the team as a unit and tolerates uneven consumption between members; a per-member limit holds each person to the same allowance and flags any single member who exceeds it. The two layers coexist: a team can carry an overall ceiling while individual members carry their own, tighter ceilings underneath it, and the most restrictive applicable limit governs.
Step 3: Select the team or person
The selection list below the scope reflects the scope chosen in Step 2: a team scope lists teams, and the single-user scope lists individual users.
- Use the search box to filter the list by name when the list is long. The match count is shown alongside the field.
- Select the target team or person from the list. Each team row carries its member count, so that the reach of a pooled or per-member limit is visible before the budget is created.
Step 4: Set the monthly spend limit
The spend limit is the ceiling itself, expressed in US dollars per month, because the conversation behind it was conducted in money.
- Enter the amount in the Spend limit field, or select one of the preset amounts ($100, $500, $1,000, $5,000, or $10,000) as a starting point.
- Confirm the reset cadence. The budget resets at the start of every calendar month in UTC, so a limit set mid-month still governs the remainder of that month against spend already recorded.
Step 5: Understand what happens at the ceiling
A budget tracks cumulative spend against the ceiling and raises an alert as the limit is approached or crossed. It does not stop traffic: requests continue to be served after the ceiling is reached, because spend is evaluated on the management plane against aggregated request logs rather than enforced inline at the gateway. A budget is therefore a forecasting and accountability tool that gives the operator and business owner time to act, not a hard contractual cap that cuts requests off automatically.
Because the ceiling does not block, the alerting behind it has to be wired to someone who will act on it. When the budget is approached, the legitimate responses are to investigate the spend, raise the ceiling if the growth is agreed and funded, or accept the overspend for the remainder of the period. See See budget exhaustion coming for reading the burn in time to intervene.
When you need a genuine hard stop, that job belongs to a rate limit rather than a budget: a rate limit is enforced inline at the gateway and rejects requests over the ceiling as they arrive. Pair a budget with aggressive rate limits on dedicated keys for evaluation or experimentation workloads where a runaway must be cut off automatically.
Step 6: Name the budget and create it
- Enter a descriptive name in the Name field, for example
Engineering monthly cap. The name identifies the budget in the admin list where every budget is reviewed together, so it should describe what the budget covers rather than restate the amount. - Review the policy summary, which confirms the scope, target, and limit about to be applied.
- Select Create budget to save the policy.
Once the budget exists, the reasoning behind the ceiling belongs somewhere durable alongside it. The audit trail in Audit Agent Router activity records that the budget was created and who created it; the business justification for the number belongs next to that record.
What to do next
- See budget exhaustion coming: read the burn against the ceiling created here, in time to intervene. See See budget exhaustion coming in time to act.
- Bill AI spend back to the teams that incur it: turn the budgets into the statements finance consumes. See Bill AI spend back to the teams that incur it.
- Stop runaway workloads: the inline blocking companion to this budget. A budget alerts on cumulative spend; a rate limit rejects requests at the gateway when a hard stop is required. See Stop runaway workloads before they burn the budget.
Where to go next