> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Budget levels and interaction
> How the six budget levels (workspace, project, identity, API key, provider, model) interact when multiple budgets apply to the same request, including worked examples and reset behavior.
Budgets can be set at six levels: **Workspace**, **Project**, **Identity**, **API Key**, **Provider**, and **Model**. When several budgets apply to the same request, every one of them is enforced independently and cumulatively. There is no precedence: a budget at one level never overrides a budget at another level, and a request must satisfy every budget that matches it.
Set up and manage budgets under **Settings > Organization > Budgets**. See [Budgets](/docs/ai-gateway/budgets) for creating budgets, configuring limits, and setting up alerts.
## Budget levels
| Level | Scopes to |
| ------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Workspace** | The entire workspace. |
| **Project** | One project. |
| **Identity** | One contact, by external ID. |
| **API Key** | One API key. |
| **Provider** | All requests to a provider, any model. Matches the provider segment of the model reference (`openai` in `openai/gpt-4o`). |
| **Model** | One model, matched by the full model reference as sent in the request (`openai/gpt-4o`). |
Only one budget is allowed per target, so a request can match at most one scoped budget per level, up to six in total. Dynamic budgets created through the API with a custom matching expression can apply in addition.
When a budget is exhausted, only requests that match it are rejected.
## How multiple budgets interact
* **Every applicable budget is enforced.** A request must pass every budget that matches it. No budget overrides another.
* **Each budget tracks its own usage.** A request counts toward every budget that applies to it, at the same time.
* **The most restrictive budget binds.** The effective cap for a dimension is the most restrictive applicable budget.
* **Requests per minute are enforced per budget**, each with its own rolling 60-second window.
* **Expired budgets stop enforcing.** After the expiration date a budget no longer blocks requests, even though it stays in the list.
## Worked examples
The workspace has a \$1,000/month budget. The **Production** project has a \$300/month budget.
* Requests to Production count toward both budgets; requests to other projects count only toward the workspace budget.
* When Production reaches \$300, requests to Production are rejected until the monthly reset. Other projects keep working until the workspace budget is exhausted at \$1,000.
The **Support** project has a \$500/month budget. The identity `customer-acme` has a \$50/month budget.
* The identity budget applies across all projects: the \$50/month cap is enforced whenever `customer-acme` makes a request, regardless of project.
* Requests from `customer-acme` count toward both budgets. When the identity budget is exhausted, those requests are rejected even though the project budget has room; other identities keep working.
The workspace has a \$2,000/month budget. The model `anthropic/claude-sonnet-5` has an \$800/month budget.
* When the model budget is exhausted, requests to that model are rejected; other models keep working.
* When total workspace spend reaches \$2,000, all requests are rejected until the monthly reset, regardless of model.
## When a limit is exceeded
A request that matches an exhausted budget is rejected with `429 Too Many Requests`. The response identifies the budget and the exceeded dimension (`cost`, `tokens`, or `requests`); the response headers report the limit, remaining usage, and seconds until reset. Only requests that match the exhausted budget are blocked.
| Dimension | Behavior when exceeded |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Cost** and **Tokens** | Counters update as requests complete. When a budget reaches 100%, the next matching request is rejected. Requests stay blocked until the budget's period resets, or an admin raises the limit. |
| **Requests per minute** | Requests are rejected for the rolling 60-second window only, independent of the reset period. |
For budgets with a **One-time** reset period, there is no automatic reset: matching requests stay blocked until an admin raises the limit, deletes the budget, or its expiration date passes.
## Reset periods
Each budget has its own reset period and its own counters. Budgets at different levels can use different periods: **Daily**, **Weekly**, **Monthly**, **Yearly**, or **One-time** (no reset). See [Budgets](/docs/ai-gateway/budgets) for the reset schedule. Requests per minute always use a rolling 60-second window, regardless of the reset period.
## See also
Create, edit, and monitor budgets and their alerts.
Create and manage AI Gateway API keys with optional spending limits.
Track user interactions and usage per identity.