Usage Limits & Thresholds
The Zuplo AI Gateway provides hierarchical usage limits and budget controls to manage LLM spending across the gateway's Zuplo project. Limits can be set at the gateway, team, and app levels.
Budget Hierarchy
Limits at every level apply together—a request is blocked when any level's limit is exceeded, and the error names the level that blocked it:
- Gateway - Limits across the Zuplo project (for example, $1,000/day), covering all teams and apps combined
- Teams - Team-specific limits covering all of the team's apps combined (for example, $500/day for the Engineering team)
- Apps - Per-app limits for granular control (for example, $10/day for a hackathon app)
Where limits are configured
| Level | Where |
|---|---|
| Gateway | Settings → Usage Limits |
| Team | The team's Usage & Limits tab |
| App | The Budgets and Costs policy in the app's policy chain |
Each level supports the same three meters, each with independent daily and monthly settings:
- Budget - spend in dollars
- Tokens - input plus output tokens
- Requests - request count
For each meter and period you can set a Limit (usage at or above it gets blocked) and a Warning threshold (a percentage of the limit that triggers a warning notification without blocking). Leave a field empty to not enforce it.
Daily and monthly periods are anchored to your gateway, not the calendar: a daily period rolls over at the time of day (UTC) the gateway was created, and a monthly period runs anchor-day to anchor-day. Changing a limit mid-period doesn't reset the period's usage.
Setting an app's limits
-
Open the Apps & Teams tab and select the app.
-
On the Policies tab, configure the Budgets and Costs policy (add it from Add Policy if the chain doesn't have it).
-
Set daily or monthly limits for budget, tokens, or requests, and optional warning thresholds.
-
Save. The change applies within about a minute.
Each period in the Budgets and Costs policy's options carries an enabled flag
next to its number, and so does each warning threshold. A period enforces
nothing until enabled is true and limit is set—options that set only
limit are silently inert. Watch for this when editing the policy's options
directly, such as in config/policies.json or a
policy template.
If the app has a quota fallback model configured, an exceeded limit routes
requests to that model instead of blocking with a 429—see
Fallback Models. The fallback's usage still counts toward the
limits.
An app without the Budgets and Costs policy in its chain doesn't enforce app-level limits. Team and gateway limits still protect overall spend, but per-app budgets need Budgets and Costs in the chain—use a policy template to make sure every app starts with it.
Budgets fail open by default
The Budgets and Costs policy's throwOnFailure option defaults to false, so
if the metering service is unavailable the request proceeds unmetered: no limit
is checked and the request reaches the provider even if the app is already over
budget. Set throwOnFailure to true to fail closed instead, so a metering
outage rejects the request rather than letting it escape the budget.
Monitoring Usage
Each app, team, and the gateway show current usage against their limits:
- Open the Apps & Teams tab and select an app or team
- The Overview tab shows daily and monthly usage—spend, tokens, and requests—with progress against any configured limits
- The same tab's Metrics frame charts request count, token usage, and cost over time; View in Analytics opens the full request-level breakdown scoped to that app or team
Related Resources
- Getting Started - Set up your first AI Gateway project with budget controls
- Managing Teams - Configure team-level budgets
- Managing Apps - Configure app-level limits
- Fallback Models - Serve a cheaper model instead of blocking when a limit is exceeded