Skip to main content
Budgets prevent a key from starting a request that could exceed its configured spend period.

​
Create a budgeted key

Set both fields when creating the key:
Supported periods are 1d, 7d, and 30d. Budgets require Postgres persistence and reviewed pricing for every route the key can reach.

​
How enforcement works

  1. The gateway estimates input and maximum requested output tokens.
  2. It reserves the highest possible cost across weighted and fallback routes.
  3. Concurrent reservations lock the budget period, preventing oversubscription.
  4. After completion it settles using provider-reported cost, observed usage with reviewed pricing, or the reserved amount.
  5. Failed provider calls release their reservation when no spend occurred.
Budgeted chat and Responses requests require an explicit output token limit or a configured default. When available balance cannot cover a reservation, the request receives HTTP 429 budget_exceeded with Retry-After pointing toward period reset.

​
View budgets

Each result includes limit_usd, spent_usd, reserved_usd, available_usd, utilization, starts_at, and ends_at. Existing-period summaries are advisory snapshots and do not lock budget keys or periods. At rollover, the endpoint briefly locks only keys missing a current period while it initializes that period. Concurrent reservations or settlements may complete immediately after a snapshot; admission enforcement remains authoritative.

​
Budget alerts

Settled spend creates deduplicated alerts at 80% and 100%. Self-managed deployments can configure one Slack or Google Chat destination through an environment variable or, preferably for containers, a read-only secret file:
The environment and file sources are mutually exclusive, and only one provider may be enabled for an outbox. The file must contain one HTTPS URL; the gateway reads it at startup and never exposes it through the Admin API. Delivery is asynchronous and retried from a durable outbox. Inspect it with:

​
Stale reservations

A process crash can leave a reservation without final provider usage. Active provider operations heartbeat their reservation. After the configured stale window without a heartbeat, the reconciler charges the full reserved amount rather than silently allowing possible spend to bypass the cap.
If a malformed historical row cannot settle, the gateway retains its reserve and applies bounded exponential retry backoff so it cannot block newer reservations. Repeated failures are marked as soft-quarantined. The reservation response exposes reconciliation_attempts, reconciliation_error_type, reconcile_after, quarantined, and reconciliation_quarantined_at; repair the underlying record and use the manual reconcile endpoint when immediate recovery is required. The budget ledger is enforcement-grade. Reserved entries remain until settlement or reconciliation. Finalized per-request entries remain queryable until data_governance.budget_ledger_retention_days expires, while budget-period spend/reserved aggregates remain authoritative after that cleanup. The ledger is not an invoice, and it does not reconcile provider bills, taxes, credits, or negotiated pricing automatically.