scriptoriumadmin/litellm
1
0
Fork 0
mirror of https://github.com/BerriAI/litellm.git synced 2026-09-06 08:16:43 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 79

Merge pull request #38883 from BerriAI/litellm_docs_user_spend_endpoint_semantics

Browse source 
docs(proxy): clarify spend semantics on /v2/user/info and /user/daily/activity
This commit is contained in:
Mateo Wang 2026-08-31 11:47:41 -07:00 • committed by GitHub
commit c09fa5b712
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 36 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

18
litellm/proxy/management_endpoints/internal_user_endpoints.py
View file

@ -1027,6 +1027,14 @@ async def user_info_v2(
This is the v2 replacement for /user/info, designed to avoid the "god endpoint" problem
where the old endpoint loaded all keys and teams into memory.
Note on `spend`: this is the user's running budget counter, which the budget reset job
resets whenever `budget_reset_at` elapses (see `budget_duration`): to zero by default,
or to the overage above `max_budget` when `budget_rollover` is enabled. It is NOT
lifetime or per-period historical spend. For historical spend over a date range, use
`/user/daily/activity` or `/user/daily/activity/aggregated`, which read daily spend
records that only ever accumulate and are never reset. The two values are expected to
diverge once a budget reset has occurred within the queried period.
Access control:
- Proxy admins can query any user
- Team admins can query users within their teams
@ -2726,6 +2734,11 @@ async def get_user_daily_activity(
Meant to optimize querying spend data for analytics for a user.
Reads daily spend records that only ever accumulate and are never affected by budget
resets. Their total can legitimately exceed the `spend` field returned by
`/v2/user/info`, which is a running budget counter that every budget reset sets back
to zero (or to the overage above `max_budget` when `budget_rollover` is enabled).
Returns:
(by date)
- spend
@ -2839,6 +2852,11 @@ async def get_user_daily_activity_aggregated(
"""
Aggregated analytics for a user's daily activity without pagination.
Returns the same response shape as the paginated endpoint with page metadata set to single-page.
Reads daily spend records that only ever accumulate and are never affected by budget
resets. Their total can legitimately exceed the `spend` field returned by
`/v2/user/info`, which is a running budget counter that every budget reset sets back
to zero (or to the overage above `max_budget` when `budget_rollover` is enabled).
"""
from litellm.proxy.proxy_server import prisma_client

18
ui/litellm-dashboard/src/lib/http/schema.d.ts generated vendored
View file

@ -16212,6 +16212,11 @@ export interface paths {
*
* Meant to optimize querying spend data for analytics for a user.
*
* Reads daily spend records that only ever accumulate and are never affected by budget
* resets. Their total can legitimately exceed the `spend` field returned by
* `/v2/user/info`, which is a running budget counter that every budget reset sets back
* to zero (or to the overage above `max_budget` when `budget_rollover` is enabled).
*
* Returns:
* (by date)
* - spend
@ -16243,6 +16248,11 @@ export interface paths {
* Get User Daily Activity Aggregated
* @description Aggregated analytics for a user's daily activity without pagination.
* Returns the same response shape as the paginated endpoint with page metadata set to single-page.
*
* Reads daily spend records that only ever accumulate and are never affected by budget
* resets. Their total can legitimately exceed the `spend` field returned by
* `/v2/user/info`, which is a running budget counter that every budget reset sets back
* to zero (or to the overage above `max_budget` when `budget_rollover` is enabled).
*/
get: operations["get_user_daily_activity_aggregated_user_daily_activity_aggregated_get"];
put?: never;
@ -21006,6 +21016,14 @@ export interface paths {
* This is the v2 replacement for /user/info, designed to avoid the "god endpoint" problem
* where the old endpoint loaded all keys and teams into memory.
*
* Note on `spend`: this is the user's running budget counter, which the budget reset job
* resets whenever `budget_reset_at` elapses (see `budget_duration`): to zero by default,
* or to the overage above `max_budget` when `budget_rollover` is enabled. It is NOT
* lifetime or per-period historical spend. For historical spend over a date range, use
* `/user/daily/activity` or `/user/daily/activity/aggregated`, which read daily spend
* records that only ever accumulate and are never reset. The two values are expected to
* diverge once a budget reset has occurred within the queried period.
*
* Access control:
* - Proxy admins can query any user
* - Team admins can query users within their teams