Budget hierarchy

Every gateway request is checked against every budget that applies. If any level is exhausted, the call is rejected with 429 budget_exceeded before a provider token is spent.

Levels (all must pass)

1. Key — the virtual key's monthly (or 1d / 7d / 30d) budget
2. User — spend attributed to the key owner
3. Application — if the key belongs to an app
4. Team
5. Organization
6. Tag — each tag on the request that has a managed budget
7. Customer — if x-zeallm-customer-id (or user) is present and that customer has a budget

How spend is recorded

Tokens and cost are written asynchronously after the response. The next request sees the updated totals. Soft-alert emails and in-app notifications fire when a configured threshold is crossed; a hard budget blocks traffic.

Reset time is calendar-aligned using ZEALLM_TIMEZONE and ZEALLM_BUDGET_RESET_TIME (default UTC midnight).

Temporary increases

Platform admins can grant a temporary budget increase on a key from Budgets. The overlay adds to the base budget until it expires.

Budget tiers

Reusable presets (name, max budget, duration, RPM, TPM) live under Access & Tiers. A key request can pick a tier instead of typing custom limits. Reviewers can still override those numbers on approve.

Soft alerts

Admins configure threshold percentages on a KEY, TEAM or TAG subject, plus email recipients. Last-fired time is shown on the Budgets page.