Budgets

A budget caps spend in USD for a scope: domain, organisation, team, key, or per user.

teams:
  payments:
    budget:
      limit_usd: 100
      period: monthly
      action: downgrade
      downgrade_to: {bedrock: azure-openai}
      alert_at: [50, 80, 100]
    user_budget: {limit_usd: 5, period: daily}

Actions

action	At 100%
block	The request is refused with 402 budget_exceeded.
downgrade	The request is sent to the cheaper alias given in downgrade_to. If a model has no entry, it is blocked. The downgraded model must still be allowed by policy.

TIP

Spend is counted from each successful call's response cost, and cache hits cost zero. On a scope that should downgrade, do not also set LiteLLM's native max_budget: it rejects the request before the gateway can offer a downgrade.

Periods

daily or monthly. Counters are stored under keys that include the period, so a new day or month starts from zero with no scheduler.

Alerts

At each alert_at percentage the gateway logs a line such as:

[LLM gateway] team 'payments' crossed 80% of its daily budget ($40.00 of $50.00); action at 100%: block

Set GATEWAY_ALERT_WEBHOOK_URL to also receive a JSON webhook (Slack, Teams or any receiver).

Per-user budgets

user_budget on a team is the default budget each user of that team gets, counted per user. Send the user with X-User-Id or the OpenAI user field. See caller identity.

Where spend is stored

Mode	Counters
Server	The proxy's cache. Use Redis so the budget is shared across instances.
SDK	In memory, unless you pass a Redis-backed cache= to Gateway.