Spend limits let you set cost-based budgets on your AI Gateway. When cumulative spend reaches the limit within a time window, AI Gateway blocks further requests with a 429 response until the window resets.
Unlike rate limiting, which caps the number of requests, spend limits track actual dollar cost per request based on model pricing. You can scope limits to any combination of model, provider, or custom metadata dimensions like user ID, team, or application.
Spend limits apply to both Unified Billing requests and BYOK requests for models with known pricing.
Each spend limit rule defines a budget (in dollars) over a rolling or fixed time window. AI Gateway calculates the cost of each request based on token usage and model pricing, then tracks cumulative spend against the limit in real time.
Before sending a request to the provider, AI Gateway evaluates all applicable spend limit rules at once. If any individual rule is over budget, the request is blocked with a 429 response.
Spend limits are eventually consistent. The current request's cost is recorded after completion, so a burst of concurrent requests can briefly exceed the limit before enforcement catches up.
Each rule can be scoped by one or more dimensions:
- Limit by provider — the provider used for the request.
- Limit by model — the model used for the request.
- Limit by metadata — a custom metadata key you attach to requests. Enter the metadata key name (for example,
agent_idorenvironment).
Each dimension can be configured in one of two modes:
| Mode | Behavior | Example |
|---|---|---|
| Split by value | Each distinct value gets its own independent budget bucket. | For example, if you pass in agent_id, splitting by agent_id gives every agent its own budget. |
| Filter by value | The rule applies only when the dimension equals a specific value. | For example, if you pass in agent_id, filtering agent_id to agent_42 limits only that agent's requests. |
If a dimension is not configured on a rule, all values share one budget bucket. For example, a rule without a provider dimension tracks spend across all providers together.
Given a request with model openai/gpt-5.5 and an agent_id metadata value of agent_42:
| Scenario | Dimensions | Budget bucket |
|---|---|---|
| Global budget for everyone | None | One shared bucket |
| Per-agent budget | agent_id metadata: split by value |
Separate bucket per agent |
| Per-provider, per-agent | agent_id metadata: split by value, provider: split by value |
Separate bucket per agent+provider combination |
| Specific model only | model: filter by value openai/gpt-5.5 |
Only applies to openai/gpt-5.5 requests |
| Per-agent, per-model | agent_id metadata: split by value, model: split by value |
Separate bucket per agent+model combination |
Spend limits are configured on the gateway via the dashboard or the API. You can define up to 20 rules per gateway.
To scope spend limits by custom dimensions like user ID or team, attach custom metadata to your requests.
You can give every user their own budget by scoping a rule to a user identifier. How you get that identifier depends on how your gateway is authenticated.
If your gateway is protected by Cloudflare Access, AI Gateway automatically adds the authenticated Access user ID to each request as the reserved cf.user_id metadata key. You do not need to pass user IDs from your client application.
To set a per-user budget:
- In the Cloudflare dashboard ↗, go to AI > AI Gateway and select your gateway.
- Go to the spend limits settings and add a rule.
- Under Limit by metadata, select Add metadata dimension and enter
cf.user_idas the key. - Set the dimension to Split by value.
- Set the budget amount and time window, then save.
Each authenticated Access user now gets an independent budget. To instead limit a single user, set the dimension to Filter by value and enter that user's Access JWT sub claim.
If your gateway is not behind Access, pass your own user identifier as custom metadata (for example, a user_id key). Then, under Limit by metadata, add a dimension with the key user_id and set it to Split by value.
When a spend limit is exceeded, AI Gateway returns a 429 Too Many Requests response. You have two options:
- Block requests (default) - The request is rejected until the budget window resets.
- Fall back to a cheaper model - Create a Dynamic Route with a primary model and a fallback (for example,
anthropic/claude-opus-4.7with a fallback to@cf/moonshotai/kimi-k2.6). Then set a spend limit on the primary model using this feature. When the primary model's budget is exceeded, AI Gateway automatically routes requests to the fallback model instead of blocking them.
You can track your spend per model, provider, or any custom metadata attribute on the Analytics dashboard. Use this to understand usage patterns and set informed budgets.
- Cost tracking is a best-effort estimation based on token counts and model pricing. Refer to your provider's dashboard for exact billing amounts.
- A maximum of 20 spend limit rules can be configured per gateway.