Skip to main content
Token budgets cap gateway spend and usage over a recurring time window. You define budget policies scoped to a project, a user, or an API key, and the gateway enforces them on every request. When a budget is exhausted, the gateway rejects further requests until the window resets.
Preview: This is an early preview of the Braintrust gateway’s token budget feature. The behavior described here is subject to change. To try it, reach out to your Braintrust team.

​
Configure budget policies

Configure budget policies from your project’s Settings > Spend control. Each policy applies to one scope and sets a limit over a policy window. Scope determines which requests count toward the budget: Limit is a USD amount (cost) or a token count. Each policy uses one or the other, not both. Policy window is 1 hour, 1 day, 1 week, or 1 month. Windows align to UTC calendar boundaries (the start of the hour, midnight, Monday for weeks, and the first of the month), and usage resets at the start of each window.
Editing budget policies requires the Manage settings permission for the project.

​
Cap total project spend

Use a project budget policy to put a single ceiling on total project usage, regardless of which user or API key sends the request.
  1. Select Set project budget policy.
  2. Set the Limit as USD or Tokens, then choose a Policy window.

​
Limit a user or API key

Use a user or API-key policy to cap how much a single person or key can spend, for example, to keep one integration or teammate from consuming a disproportionate share.
  1. Select Create policy.
  2. Choose the Policy type: User or API key.
  3. Set the Scope to a default (All users or All API and service keys) or a specific override (Specific user or Specific API key).
  4. Set the Limit as USD or Tokens, then choose a Policy window.

​
Set a default budget with overrides

Combine default and override policies when you want one limit to apply to everyone, with higher or lower limits for specific users or keys.
  1. Create default User and API key policies to cover everyone.
  2. Update Specific user or Specific API key overrides for the users or keys that need a higher or lower limit.

​
Edit or remove a policy

Expand a user or API-key policy in the table to open its editor alongside its usage. Change the Limit or Policy window and select Update policy, or select Remove to delete the policy. To change the project policy, select Set project budget policy again.

​
View usage

Track usage against each policy from your project’s Settings > Spend control. The policies table shows current usage and whether each target is blocked, and expanding a policy breaks its usage down over time. The table lists every policy with these columns:

​
Break down who’s consuming a budget

To find which models, users, or API keys are driving usage, expand a policy and group its usage chart.
  1. Select a policy to expand it. Its usage appears in a chart labeled Usage for.
  2. Choose a grouping: Total, Model, User, or API key.
  3. Adjust the time range to the window you want to inspect.

​
Create an override from usage

When one user or API key stands out, create an override to raise or lower its limit without leaving the chart.
  1. Group the chart by User or API key.
  2. Select the target’s series in the chart.
  3. Select the Create override for [target] button to open the policy editor pre-filled for that user or API key.

​
How enforcement works

The gateway checks budgets before routing a request to a provider. Enforcement is scoped to a project, so the gateway must be able to attribute the request to one. It resolves the project from the logging parent set with x-bt-parent (see Enable logging) or from the x-bt-project-id or x-bt-project-name header (see Use project-level AI providers). If a request doesn’t resolve to a project, budget enforcement is skipped for that request. Because usage is measured from the token and cost metrics on logged spans and not from request or response payloads, attributing a request to a project is all budgets need. You don’t have to log request or response contents to use them. When a request would exceed a budget, the gateway rejects it with HTTP 402 Payment Required and a JSON body:
The message begins with Cost budget exceeded for USD budgets or Token budget exceeded for token budgets, names the exhausted policy’s target (the project, a user, or an API key), and gives the UTC time the window resets. The response also sets x-bt-error-origin: braintrust to indicate the error originated in the gateway rather than a provider.
A budget rejection is not retryable. The gateway does not set a Retry-After header, and retrying before the window resets returns 402 again. Wait until the reset time in the error message before sending further requests.
If the gateway can’t read a budget policy or the current usage for a request (for example, during a temporary cache or control-plane error), it allows the request through and updates usage in the background rather than blocking traffic. Usage is measured from observed gateway logs, so enforcement catches up to the limit rather than reserving quota in advance. Because a policy is checked against usage already recorded in the current window, creating or lowering a policy can block a target immediately. Raising its limit or adding an override lets requests through again.

​
Next steps

​
Share feedback

Token budgets are an active area of development, and your feedback shapes them. Tell your Braintrust team what’s working, what isn’t, and what you’d like budgets to do next.