LiteLLM budgets and spend tracking

LiteLLM spend tracking requires a database (Postgres). Without it, you cannot cap keys or export spend reports.

This page answers litellm budget, litellm spend tracking, and litellm cost.

Enable spend tracking

Deploy LiteLLM with a Postgres connection — see proxy setup
Open the admin UI at http://localhost:4000/ui
Send a test request; verify x-litellm-response-cost in response headers

Virtual keys with budgets

Generate keys with spending caps:


curl -X POST 'http://localhost:4000/key/generate' \
  -H 'Authorization: Bearer sk-<master-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "max_budget": 20.0,
    "budget_duration": "30d",
    "models": ["gpt-4o-mini", "claude-3-5-haiku-20241022"],
    "metadata": {"tags": ["env:dev"]}
  }'

Key type	`max_budget`	`models` allowlist
Dev	$20 / 30d	Mini + haiku
CI	$5 / 30d	Haiku only
Prod	Team budget	Per workload

Spend reports

Query aggregated spend:


curl 'http://localhost:4000/global/spend/report?start_date=2026-01-01&end_date=2026-01-31&group_by=team' \
  -H 'Authorization: Bearer sk-<master-key>'

Use group_by=customer or group_by=team for cost attribution.

Tag requests

Pass tags in the request body for feature-level slicing:


response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}],
    user="jane_smith",
    extra_body={"metadata": {"tags": ["feature:code-review", "env:prod"]}},
)

Per-user spend


curl 'http://localhost:4000/user/info?user_id=jane_smith' \
  -H 'Authorization: Bearer sk-<master-key>'

Warning: End users can set user in request bodies. For backend services, always issue per-user virtual keys with user_id set at key creation — not self-declared in the request.

Spending guardrails

Never share the master key with developers
Set max_budget on every virtual key
Use models allowlist on CI keys
Export weekly spend reports via /global/spend/report
Sync the model cost map when provider prices change

Troubleshooting

Spend does not match provider bill — align time ranges, compare cache token categories, verify model cost map is current. See LiteLLM’s cost discrepancy workflow.

Key blocked unexpectedly — max_budget reached. Check /user/info for spend breakdown.