feat(key management): show budget window usage on /key/info

[Thijmen]

TLDR

Problem this solves:

• A key's budget windows show the limits but never how much is used
• The only usage signal today is the 429 once a window runs out

How it solves it:

• /key/info and /v2/key/info add a budget_limits_usage field keyed by budget_duration with current_spend per window, a sibling of budget_limits in the same spirit as model_max_budget_usage
• budget_limits comes back exactly as stored, so nothing that round-trips it into /key/update ever sees a computed field
• The number comes from the same counter and LiteLLM_BudgetWindowSpend row enforcement reads, not a spend-log aggregate

User Flow

Before: an admin who put an hourly and a daily budget on a key cannot see how close either window is to its cap

1. They send POST https://litellm-domain/key/generate with "budget_limits": [{"budget_duration": "1h", "max_budget": 2.0}, {"budget_duration": "1d", "max_budget": 20.0}] and get back an sk-... key
2. Their app sends POST https://litellm-domain/v1/chat/completions with that key and gets a 200 with x-litellm-response-cost: 0.000295
3. They send GET https://litellm-domain/key/info?key=sk-... and each budget_limits entry shows only reset_at, max_budget, and budget_duration
4. The first time they learn a window is used up is a 429 ExceededBudget: Key over 1h budget on a real request

After: the same admin sees per-window usage on the key

1. They send POST https://litellm-domain/key/generate with the same budget_limits and get back an sk-... key
2. Their app sends POST https://litellm-domain/v1/chat/completions with that key and gets a 200 with x-litellm-response-cost: 0.000295
3. They send GET https://litellm-domain/key/info?key=sk-... and the response now carries "budget_limits_usage": {"1h": {"current_spend": 0.0003}, "1d": {"current_spend": 0.0003}} next to the unchanged budget_limits
4. POST https://litellm-domain/v2/key/info with {"keys": ["sk-..."]} returns the same budget_limits_usage on every key

Relevant issues

Linear ticket

Pre-Submission checklist

Please complete all items before asking a LiteLLM maintainer to review your PR

• I have added meaningful tests
• The handful of test files covering my change pass locally, e.g. uv run pytest tests/test_litellm/<your_test_file>.py -v. Leave the suites (make test-unit-*, make test-unit) to CI: it finishes in ~15 minutes where a laptop takes an hour or more
• My PR passes all required CI/CD checks (e.g., lint, schema.d.ts sync check, etc.)
• My PR's scope is as isolated as possible; it only solves 1 specific problem
• I have received a Greptile Confidence Score of at least 4/5 before requesting a maintainer review (Greptile reviews automatically once the PR is opened; only comment @greptileai to re-request a review after pushing changes)

Delays in PR merge?

If you're seeing a delay in your PR being merged, ping the LiteLLM Team on Slack (#pr-review).

Screenshots / Proof of Fix

Shared setup: litellm/proxy/dev_config.yaml (master key sk-1234, gpt-5.5 backed by a real OpenAI key), one Postgres for both runs. The After proxy runs on :4373, the Before proxy (staging tip 3fadcd7155) on :4374. The same key is used on both sides, created and driven on the After proxy first

curl -s -X POST http://localhost:4373/key/generate -H "Authorization: Bearer sk-1234" -H 'Content-Type: application/json' \
  -d '{"key_alias":"pr37044-window-qa","models":["gpt-5.5"],"budget_limits":[{"budget_duration":"1h","max_budget":2.0},{"budget_duration":"1d","max_budget":20.0}]}'
# => {"key":"sk-ziYZm4U4ErrktAbIvenbvQ", ...}

curl -s -D - -o /dev/null http://localhost:4373/v1/chat/completions -H "Authorization: Bearer sk-ziYZm4U4ErrktAbIvenbvQ" -H 'Content-Type: application/json' \
  -d '{"model":"gpt-5.5","messages":[{"role":"user","content":"Say hi in three words"}]}' | grep -i "^HTTP/\|x-litellm-response-cost:"
# HTTP/1.1 200 OK
# x-litellm-response-cost: 0.000295

Before (3fadcd7)

1. curl -s "http://localhost:4374/key/info?key=sk-ziYZm4U4ErrktAbIvenbvQ" -H "Authorization: Bearer sk-1234" | jq '.info | {budget_limits, budget_limits_usage}'

   {
     "budget_limits": [
       { "reset_at": "2026-09-01T05:00:00+00:00", "max_budget": 2.0, "budget_duration": "1h" },
       { "reset_at": "2026-09-02T00:00:00+00:00", "max_budget": 20.0, "budget_duration": "1d" }
     ],
     "budget_limits_usage": null
   }

2. curl -s -X POST http://localhost:4374/v2/key/info -H "Authorization: Bearer sk-1234" -H 'Content-Type: application/json' -d '{"keys":["sk-ziYZm4U4ErrktAbIvenbvQ"]}' | jq '.info[0] | {budget_limits, budget_limits_usage}'

   {
     "budget_limits": [
       { "reset_at": "2026-09-01T05:00:00+00:00", "max_budget": 2.0, "budget_duration": "1h" },
       { "reset_at": "2026-09-02T00:00:00+00:00", "max_budget": 20.0, "budget_duration": "1d" }
     ],
     "budget_limits_usage": null
   }

After (760b864)

1. curl -s "http://localhost:4373/key/info?key=sk-ziYZm4U4ErrktAbIvenbvQ" -H "Authorization: Bearer sk-1234" | jq '.info | {budget_limits, budget_limits_usage}' (before any traffic)

   {
     "budget_limits": [
       { "reset_at": "2026-09-01T05:00:00+00:00", "max_budget": 2.0, "budget_duration": "1h" },
       { "reset_at": "2026-09-02T00:00:00+00:00", "max_budget": 20.0, "budget_duration": "1d" }
     ],
     "budget_limits_usage": {
       "1h": { "current_spend": 0.0 },
       "1d": { "current_spend": 0.0 }
     }
   }

2. Same /key/info call as step 1, about 15 seconds after the chat completion above

   {
     "budget_limits": [
       { "reset_at": "2026-09-01T05:00:00+00:00", "max_budget": 2.0, "budget_duration": "1h" },
       { "reset_at": "2026-09-02T00:00:00+00:00", "max_budget": 20.0, "budget_duration": "1d" }
     ],
     "budget_limits_usage": {
       "1h": { "current_spend": 0.0003 },
       "1d": { "current_spend": 0.0003 }
     }
   }

3. curl -s -X POST http://localhost:4373/v2/key/info -H "Authorization: Bearer sk-1234" -H 'Content-Type: application/json' -d '{"keys":["sk-ziYZm4U4ErrktAbIvenbvQ"]}' | jq '.info[0] | {budget_limits, budget_limits_usage}'

   {
     "budget_limits": [
       { "reset_at": "2026-09-01T05:00:00+00:00", "max_budget": 2.0, "budget_duration": "1h" },
       { "reset_at": "2026-09-02T00:00:00+00:00", "max_budget": 20.0, "budget_duration": "1d" }
     ],
     "budget_limits_usage": {
       "1h": { "current_spend": 0.0003 },
       "1d": { "current_spend": 0.0003 }
     }
   }

4. The window spend rows the read is backed by, once the writer flushed (psql "$DATABASE_URL" -c 'select entity_type, window_duration, window_start, spend from "LiteLLM_BudgetWindowSpend" where entity_id = <sha256 of the key> order by window_duration')

    entity_type | window_duration |    window_start     |  spend
   -------------+-----------------+---------------------+----------
    key         | 1d              | 2026-09-01 00:00:00 | 0.000295
    key         | 1h              | 2026-09-01 04:00:00 | 0.000295
   

5. Proof the read is the table, not a spend-log aggregate: poison the 1h row, wait 6s for the floor cache, then re-read (psql "$DATABASE_URL" -c 'update "LiteLLM_BudgetWindowSpend" set spend = 999 where window_duration = '"'"'1h'"'"' and entity_id = <sha256 of the key>', then the same /key/info call as step 1)

   {
     "budget_limits": [
       { "reset_at": "2026-09-01T05:00:00+00:00", "max_budget": 2.0, "budget_duration": "1h" },
       { "reset_at": "2026-09-02T00:00:00+00:00", "max_budget": 20.0, "budget_duration": "1d" }
     ],
     "budget_limits_usage": {
       "1h": { "current_spend": 999.0 },
       "1d": { "current_spend": 0.0003 }
     }
   }

Type

🆕 New Feature

Caveats (if any)

Medium

• /v2/key/info now does one counter read per window per key, so large batches of windowed keys cost more than before

Low

• The Admin UI does not display budget_limits_usage yet; only the API response carries it

Final Attestation

• The tests check the right things, including the edge cases, and regressions in the respective real-world customer use-cases are not possible after this PR

[greptile-apps]

Greptile Summary

The PR adds current budget-window spend information to the single-key and batched key-information APIs while preserving the stored budget_limits shape.

• Builds usage entries from the budget enforcement counters.
• Adds tests for single-key, batched, empty, JSON-backed, and model-backed budget-window configurations.
• Updates the generated dashboard API schema documentation.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
litellm/proxy/management_endpoints/key_management_endpoints.py	Adds immutable budget-window usage mappings and attaches them to both key-information endpoint responses.
tests/test_litellm/proxy/management_endpoints/test_key_management_endpoints.py	Adds focused unit coverage for budget-window usage retrieval and supported stored input shapes.
ui/litellm-dashboard/src/lib/http/schema.d.ts	Documents the additional key-information response fields in the generated API declarations.

_{Reviews (6): Last reviewed commit: "refactor(key): trim budget_limits_usage ..." | Re-trigger Greptile}

[codecov]

Codecov Report

❌ Patch coverage is 90.00000% with 3 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...y/management_endpoints/key_management_endpoints.py	90.00%	3 Missing ⚠️

📢 Thoughts on this report? Let us know!

[codspeed]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing Thijmen:key-budget-window-usage (760b864) with litellm_internal_staging (d132040)}

[veria-ai]

PR overview

All previously flagged issues have been addressed. No open security concerns remain on this pull request.

Security review

No open security issues remain on this pull request.

Fixed/addressed: 1 · PR risk: 0/10

[Thijmen]

@greptile-apps

[Thijmen]

@greptile-apps

[ryan-crabbe-berri]

I dont think this change needs to be here

[ryan-crabbe-berri]

Thanks for this. I'm taking it over to rebase onto staging, where I refactored the way we do spend tracking for budget windows. Prev version did a pretty expensive query on the spend logs table

[ryan-crabbe-berri]

this is a pretty big breaking behavior change, will revert because i refactored the budget windows spend tracking

[ryan-crabbe-berri]

@greptile re review

[ryan-crabbe-berri]

@greptile re review

[ryan-crabbe-berri]

@greptile re review

[ryan-crabbe-berri]

Thanks!