Skip to content

Key usage limits

How usage limits work

Admins configure quotas as spend budgets per period, in the unit LiteLLM prices its models in (BUDGET_UNIT labels them on the page; default $). LiteLLM enforces spend directly, so the figure an admin enters is the figure the gateway enforces, whatever mix of models a key uses. A model priced at 0 or null accrues no spend, so a budget never binds on it; the server warns about such models at startup.

Requests fail with HTTP 422 (budget_exceeded, "Budget has been exceeded!") once the allowance is spent and resume when the period resets. The TPM and RPM rate limits answer 429 instead.

Several windows per profile. A profile can hold one allowance per period (hourly, daily, weekly, monthly) and LiteLLM enforces each independently — a key takes budget_limits as a list of {budget_duration, max_budget} objects and rejects with ExceededBudget: Key over 1h budget when any one is spent. The tightest window binds, so a shorter period may not carry a larger budget than a longer one; the admin form rejects that. This needs LiteLLM v1.105.0 or later: the dashboard reads what has been spent in each window from the budget_limits_usage that its /key/info reports.

Only the widest window applies to the person. It is held on the person's LiteLLM internal user, so it counts every key they hold and survives a key rotation. The shorter windows stay on the key: each key counts them on its own, and a regenerated key starts them over. With "5/day + 50/month" a person can therefore spend more than 5 in a day by regenerating their key, but never more than 50 in a month. Treat the shorter windows as a guard that protects users against runaway spend, such as a script stuck in a loop, not as a cap on what a person may spend; put that cap in the widest window. The dashboard and the profile help mark the shorter windows as "per key".

LiteLLM leaves no better option. An internal user holds a single window: it accepts budget_limits and drops them. The spend counted in a key's window cannot be carried over to a new key, and /key/regenerate, which keeps the counters, needs an Enterprise licence.

Usage reporting

The dashboard shows what a person has consumed, from two sources with different granularity:

  • Over the history window (USAGE_HISTORY_DAYS, default 30) — read from the daily totals LiteLLM keeps per user, key and model (/user/daily/activity), filtered by the person's LiteLLM user. The chart spans the whole window, empty days included, so a bar's position says when the person used the gateway. Windows up to two months draw a bar per day; up to two years, per ISO week (Monday first); beyond that, per calendar month. Labels are thinned on wide windows; every bar names its date on hover. The days are UTC days, as LiteLLM buckets them.
  • Per model, over the same window — the same daily totals by the public model name, with the requests sent and the prompt/completion split.
  • Against the quota — read from the spend counter the gateway keeps for each window, which is what it enforces against. Shown as a percentage of the budget with the amounts beside it. It resets on the budget period, so it need not agree with the 30-day chart above it.

The usage card: a daily and a monthly allowance as percentage bars with the amounts and when they reset, a bar chart of the tokens used on each of the last 30 days, and a table of requests and tokens per model The usage card: a daily and a monthly allowance as percentage bars with the amounts and when they reset, a bar chart of the tokens used on each of the last 30 days, and a table of requests and tokens per model

The history belongs to the person, across every key they have held, so regenerating a key does not start it over.

LiteLLM writes the daily totals whether or not disable_spend_logs is set, and maximum_spend_logs_retention_period does not remove them, so neither setting affects the dashboard. It never reads the per-request spend log: that response grows with every request, and LiteLLM builds it on the worker that serves everyone else.