Macro-budget & micro-budget

Two budgets apply to every request. Both must have headroom, otherwise the request is rejected.

Macro-budget — the workspace pool

Set once for your workspace (for example 50 $). Every v-key spend is also debited from this shared pool at real model pricing (see Models). You choose the amount when the workspace is provisioned.

Workspace pool: 50 $  |->   v-key A (1 $/30d) ─┐
                      |->  v-key B (5 $/30d)  ─┤ draws at provider price
                      |->  v-key C (no cap)   ─┘

The pool is global. Even a “no cap” v-key still counts against it.

Micro-budget — per v-key

Each POST /key/generate can carry:

Field	Example	Meaning
`max_budget`	`5`, `1`, `0.5`	Hard cap in USD for that key
`budget_duration`	`30d`, `1d`, `1h`	Window after which spend resets to `0`

If max_budget is omitted/null → unlimited for that key (still bounded by the workspace pool).
budget_duration is the reset cadence. After 30d the key’s spend resets and it can spend another max_budget block.

Popular presets you can issue via management key:

# Per-user monthly — 2 $ that resets every month
{ "key_alias": "user-42", "max_budget": 2, "budget_duration": "30d" }

# Anonymous global pot — 1 $ that resets daily
{ "key_alias": "default", "max_budget": 1, "budget_duration": "1d" }

# Checkout-only burst — 0.5 $ one-shot (no reset)
{ "key_alias": "checkout-widget", "max_budget": 0.5 }

How enforcement works

The proxy checks balances at inference time. When either cap would be exceeded, the chat completion is rejected before reaching the model.

Safe even when leaked. A v-key for a single user with max_budget: 0.2 and budget_duration: 1d cannot spend more than 20c that day, even if posted publicly. The workspace pool adds a second ceiling.

Choosing durations

budget_duration accepts a single duration string <number><unit>. If omitted or null, the budget never resets. Per official LiteLLM docs (budget_reset_and_tz):

Unit	Meaning	Examples
`m`	minutes	`5m`, `30m`, `60m`
`h`	hours	`1h`, `12h`, `24h`
`d`	days	`1d`, `7d`, `30d`

Weekly and monthly are not 1w/1mo — use 7d for weekly and 30d for monthly:

Daily (1d / 24h) — resets at midnight every day
Weekly (7d) — resets on Monday at midnight
Monthly (30d) — resets on the 1st of each month at midnight
Sub-day (1h, 30m, 10s) — rolls forward by interval from current time

Common choices:

30d ≈ monthly billing period (resets 1st at midnight)
7d ≈ weekly billing period (resets on Monday at midnight)
1d ≈ daily anonymous pot (see Strategies → default key)
1h for aggressive demos or load tests

Next: Watermarking — page lock · Managing keys