Budgets and limits

A budget limits usage. It does not purchase credit, move money into a team wallet or guarantee that a request can be funded. Applicable usage limits and prepaid credit admission are checked separately.

Build a budget

With organization limit-management permission, open Organization › Budgets & limits in the sidebar and choose Set budget.

1. Give it a name, such as "Opus research". The name appears in alerts, in the member's view and in the 429 a refused request receives.
2. Choose who it is for: the organization, a named team or a named member. For an organization or a team, choose One shared budget (one pool) or A separate budget per member (each member of the team gets the same allowance).
3. Enter the Usage budget (USD) and choose a period:
   • Calendar month, week (Monday start), quarter or year: resets at 00:00 on the boundary.
   • Rolling days (1–90): the trailing N days, today included. Spend is kept per day, and the oldest day's spend is released at midnight.
   • Date range: from the first day to the end of the last day, once. Outside the range the budget neither counts nor blocks.
   • Fixed duration: from the first request, for the chosen length.
4. Calendar periods and rolling days follow the budget's time zone. New budgets use the organization's default zone, shown under the page title (change it there). Changing the default never moves an existing budget.
5. Optionally limit the budget to models. Type to search the catalog, then pick an exact model, a model line such as anthropic/claude-opus-*, or a vendor such as openai/*. A pattern also covers models added to the catalog later. A model that is not in the catalog is struck through and refused on save.
6. Choose Track only — requests continue or Stop requests at the limit, and the alerts (50%, 80% and 100% by default).
7. Choose Review budget, check the summary, then save.

If the organization changes while you are saving, return to the intended workspace and review again. A stale save is refused rather than applied to the new organization.

How limits combine

Every budget that applies to a request is checked, and the tightest one decides. A more specific budget does not override a stricter parent.

A request to a model outside a budget's model set is not counted by that budget. It is checked against the other budgets that apply. So an Opus-only team budget stops Opus requests at its limit, while the same key keeps working for other models, within the organization's budget.

A team budget binds the requests of keys attributed to that team. Choose the team when you create the key. Membership alone does not attribute a request.

In-flight requests reserve capacity. Completion settles actual usage against the original reservation. A request finishing after a boundary still belongs to its original period, and retrying settlement does not charge the budget twice.

Alerts

When settled usage crosses one of a budget's thresholds, Tokamak emails the organization's owners, administrators and billing administrators. It also emails the members the budget binds: the team's members, or the member whose own allowance it is. Each threshold is announced once per period (once per day for rolling budgets). Track-only budgets alert too.

Open a budget to see its Alerts log: every threshold crossed and each delivery, marked sent, failed or skipped. A self-hosted deployment without email configured still records the alert and marks its deliveries skipped. See upgrading for the TOKAMAK_NOTIFICATION_SMTP_* settings.

Read a budget

Choose a budget's name to open it. The page shows:

• used, reserved and remaining for the current period, and for a rolling budget the spend released at the next midnight;
• spend by member and by model, exactly as the budget counted it;
• its settings and its alert log.

Reset ends the current period and releases its reservations; for a rolling budget, every day in its range. It is not a refund or a credit purchase.

Your budgets

Budgets & limits shows members every budget that can apply to their requests: their own, their teams' and the organization's. Each card shows what is left, when it frees up and what they spent in it. Members never see other members' spend.

Responses to requests that a stopping budget covers carry two headers, so agents and scripts can show the same figures:

Both are set before the first byte, so streamed responses carry them too.

When requests stop

A blocking usage-limit breach returns 429. The body's budget object names the budget, its period and when it resets. Retry-After and X-RateLimit-* give the same information as headers. Adding credit does not remove a budget cap. A credit refusal is usually 402 and belongs in Billing & credits. A service failure is not evidence of either an empty wallet or an exhausted budget.

See Usage and spending for cost interpretation.