Skip to main content

Budget hierarchy

Every gateway request is checked against every active budget that applies. An exhausted blocking budget rejects the call before a provider token is spent. Monitor and warn budgets continue serving traffic.

Levels (all must pass)​

  1. Key — the virtual key budget
  2. User — spend attributed to the key owner
  3. Team
  4. Organization
  5. Application — if the key belongs to an app
  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
  8. Cost center — the effective managed allocation resolved from the application, team, organization, or user
  9. Agent and Tool — if the request names an agent or tool with x-zeallm-agent-id / x-zeallm-tool-id (or metadata.agent_id / metadata.tool_id) and it has a budget

Cost-center resolution is Application → Team → Organization → User. The first direct assignment wins. Managed cost centers are not tags, so a cost-center budget is matched by the resolved cost-center ID rather than a request header.

First-class budgets can use daily, weekly, monthly, quarterly, yearly, custom-day or one-time periods. Calendar periods close into an immutable period history before current spend resets.

How spend is recorded​

Tokens and cost are written asynchronously after the response. The same transaction increments all matching first-class budgets. The next request sees the updated totals.

The effective cost-center ID is also snapshotted on the SpendLog. Reassigning a subject changes future attribution and does not rewrite historical spend.

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.

Thresholds and enforcement​

Budgets default to 70%, 90% and 100% thresholds and can add custom thresholds. Threshold actions notify, block, or require approval. Budget enforcement can independently be set to monitor, warn, block, or require approval.

Legacy entity budgets and alerts continue to be checked during the migration period. New limits should be created from the central Budgets page.

Where budgets show up​

Platform admins manage budgets on Budgets. Other users see their own keys' budgets and increases there. The Budgets gauge on the Dashboard shows one headline budget with spend so far, the forecast to the next reset and the amount left. Platform admins see every active budget; other users see budgets they own.

See FinOps relationship and data flow for the request-to-SpendLog and governance loop.