Budgets
Budget overview
Zelyx enforces spend caps at seven independent layers. Every layer uses atomic reservation — parallel agents cannot race past the same cap.
The seven layers
| Layer | Scope | Resets | Where to configure |
|---|---|---|---|
| Company daily | All calls in your workspace | Midnight UTC | Budgets page |
| Team daily | Calls tagged with a specific team | Midnight UTC | Budgets page → Teams |
| Project daily | Calls tagged with a specific project | Midnight UTC | Budgets page → Projects |
| Per-key daily | Calls from one Zelyx key | Midnight UTC | API Keys → key creation |
| Per-model daily | Calls to one specific model | Midnight UTC | Budgets page → Models |
| Run budget | One job or pipeline run | Never (exhausted or manual reset) | X-Zelyx-Run-Budget-USD header |
| Session limit | One interactive session | Never (in-memory, resets on restart) | X-Zelyx-Session-Limit-USD header |
Enforcement order
On each call, the gate checks all applicable budget layers. If any layer is exhausted, the call is blocked. The first exhausted layer wins — the call does not proceed even if all other layers have remaining budget.
- Session limit (if
X-Zelyx-Session-Id+X-Zelyx-Session-Limit-USDprovided) - Per-model daily budget (if the model has a cap)
- Per-key daily budget (if the Zelyx key has a daily budget set)
- Company daily budget
- Team daily budget (if the call is tagged with a team)
- Project daily budget (if the call is tagged with a project)
- Run budget (if
X-Zelyx-Run-Idprovided)
Atomic reservation
Before forwarding a call to the provider, Zelyx reserves the estimated cost against every applicable budget layer. This happens in a single atomic database write — no other request can consume the same budget slot simultaneously.
After the call completes, the actual cost (from the provider's usage response) replaces the estimate. If the actual cost is lower, the difference is returned to the budget. If higher, the overage is added.
Setting a company daily budget
- Go to Budgets.
- Enter a daily cap in the Company budget section and click Save.
- Select an overage policy — what happens when the cap is hit (see Overage policies).
- Optionally set an alert threshold (e.g. 80%) to get notified before the cap is hit.
Setting a team or project budget
On the Budgets page, scroll to Team budgets or Project budgets. Enter a team or project name (must match exactly the value you send in X-Zelyx-Team or X-Zelyx-Project) and a daily cap.
Important: tagging must match
A team budget for backend only applies to calls where the request (or the key default) carries X-Zelyx-Team: backend. If calls are untagged, they are not counted against the team budget — only the company budget applies.