Quotas
Quota subjects, windows, model Quota options, and related audit events
This page lists subject types and exhaustion behavior, reset windows, model Quota options, and audit event names.
For how spend caps work, see the Quotas concept. To create and manage Quotas, see Set Usage Limits.
Subjects
| Subject | What the Quota covers | Exhaustion behavior |
|---|---|---|
| Workspace | Aggregate governed LLM usage in one workspace | Rejects affected calls with HTTP 429 |
| Agent | Calls made by one agent | Rejects that agent's affected calls with HTTP 429 |
| Act-as | Calls made under one verified end-user OIDC subject | Rejects that subject's affected calls with HTTP 429 |
| Gateway | Every LLM call routed through one Gateway | Rejects calls through that Gateway with HTTP 429 |
| Pool | Every call routed through one model pool | Rejects calls to that pool with HTTP 429 |
| Model | Calls dispatched to one model, globally or within one pool | Removes the exhausted model from pool routing when another member remains; otherwise rejects with HTTP 429 |
| Tool | Calls to one discovered tool on an MCP server connection | Rejects calls to that tool with HTTP 429 |
| Tool connection | Every call to any tool served by one MCP server connection | Rejects calls through that connection with HTTP 429 |
A model Quota can also use per-caller scope. Each agent and each verified end user then receives an independent budget against that model.
Quota scope is cumulative. A request proceeds only when every applicable limit has remaining budget.
Workspace and agent Quotas can cover all governed traffic together, only LLM traffic, or only tool traffic. Act-as Quotas can cover LLM or tool traffic. Pools, models, and Gateways are LLM-only; tools and tool connections are tool-only.
Organization and tenant allowances
At an organization or tenant context, Quotas are usage allowances, rather than a budget for one resource. An allowance caps all governed traffic, LLM traffic, or tool traffic at that scope for a daily or monthly window. It applies to the scope itself; it does not take an agent, model, pool, or Gateway subject.
Use allowances when a shared organization- or tenant-level traffic budget is the policy you need. Refer to Set usage limits for the CLI workflow.
Windows
Cost limits are stored in micro-USD. CLI, MCP, and dashboard expose them in USD. On the API, 1000000000 micro-USD is $1,000.00.
| Window | Reset |
|---|---|
daily | UTC midnight |
monthly | Start of each UTC calendar month |
The default window on create is monthly. One Quota may exist for each subject identity and window pair.
Reported usage and write-offs
Quota reads combine the durable usage baseline with recent Gateway usage. The reported value excludes recorded non-billable excess before per-caller totals are reduced to the highest-usage caller.
| Unit | Reported usage |
|---|---|
| Dome USD | Billable usage, clamped to the Quota limit |
| Tokens | Billable usage, clamped to the Quota limit |
| Calls | Billable usage, clamped to the Quota limit |
| Provider USD | Unclamped estimate of the upstream provider bill |
A zero limit means unlimited and is not clamped. Write-offs are tied to the capped subject and window, so deleting and recreating a Quota cannot reset prior usage or make excluded excess billable. When several caps cover the same call, billing excludes the excess once rather than once per Quota.
Model Quotas
A model Quota can be global, limited to one pool, or per-caller:
| Option | What it counts |
|---|---|
| Global | Direct calls and calls through every pool |
| Within one pool | Only dispatches from that pool |
| Per-caller | Separate counter for each agent and verified end user |
Exhausted within-pool model Quotas spill to another eligible pool member when one remains. Direct exhausted model calls do not spill. Refer to Quotas concept.
Observability
| Event | When it fires |
|---|---|
model.call at stage=completed | Model call with token counts |
The refused operation with result=denied, denial.reason=quota_exceeded | Quota exhaustion |
quota.create | Quota created |
quota.update | Quota updated |
quota.delete | Quota deleted |
Next steps
Create Quotas from the how-to. Routing and Act-As subjects show up in pools and delegated agents:
- Quotas concept for cumulative scopes, spillover, and passthrough
- Set Usage Limits to create, update, list, and remove Quotas
- Pools for routing strategies and failover
- Delegated agents for Act-As subjects
- Event catalog reference for the broader audit catalog