> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.aiplanet.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Budgets and alerts

> Cap spend per key with monetary budgets, reservations, resets, and alert destinations.

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:

```json theme={null}
{
  "budget_usd": "100.00",
  "budget_duration": "30d"
}
```

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

```bash theme={null}
curl -sS \
  "$GATEWAY_ADMIN_URL/admin/budgets?api_key_id=invoice-agent-prod" \
  -H "Authorization: Bearer $GATEWAY_ADMIN_KEY"
```

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:

```yaml theme={null}
alerts:
  google_chat_webhook_url_file: /run/secrets/llm_gateway_google_chat_webhook_url
```

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:

```bash theme={null}
curl -sS "$GATEWAY_ADMIN_URL/admin/budget-alerts?limit=100" \
  -H "Authorization: Bearer $GATEWAY_ADMIN_KEY"
```

## 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.

```bash theme={null}
curl -sS \
  "$GATEWAY_ADMIN_URL/admin/budget-reservations?stale_only=true" \
  -H "Authorization: Bearer $GATEWAY_ADMIN_KEY"
```

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.