> ## Documentation Index
> Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Token budgets
> Cap gateway spend and token usage with budget policies scoped to a project, user, or API key, and enforce them on every gateway request.
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**](https://www.braintrust.dev/app/~/configuration/spend-control). Each policy applies to one scope and sets a limit over a policy window.
**Scope** determines which requests count toward the budget:
| Scope | What it caps | Levels |
| ----------- | ---------------------------- | -------------------------------------------------------------------------- |
| **Project** | All usage in the project | One policy per project. |
| **User** | Usage attributed to users | A default for all users, or an override for a specific user. |
| **API key** | Usage attributed to API keys | A default for all API and service keys, or an override for a specific key. |
**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**](https://www.braintrust.dev/app/~/configuration/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:
| Column | Shows |
| ----------------- | -------------------------------------------------------------------------------------------------- |
| **Policy type** | Whether the policy applies to the project, a user, or an API key. |
| **Name** | The policy's target, such as a specific user or key, or a scope-wide default. |
| **Policy window** | The recurring window the limit applies over. |
| **Limit** | The USD or token limit. |
| **Usage** | Usage in the current window. Default policies show the average across their targets. |
| **Blocked** | Whether the target is over its limit. Default policies show how many of their targets are blocked. |
### 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](/docs/deploy/gateway#enable-logging)) or from the `x-bt-project-id` or `x-bt-project-name` header (see [Use project-level AI providers](/docs/deploy/gateway#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:
```json theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
{
"error": {
"type": "budget_exceeded",
"message": "Cost budget exceeded for project . Resets at 2026-07-15T00:00:00Z"
}
}
```
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
* [Use the Braintrust gateway](/docs/deploy/gateway) to route requests through a unified LLM API.
* [Enable logging](/docs/deploy/gateway#enable-logging) so gateway usage is attributed to a project.
* [Monitor gateway usage](/docs/deploy/gateway#monitor-gateway-usage) to track usage, costs, and errors.
## 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.