From 4fb1440747d704140beb558b54a21520aa3c57d3 Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Sun, 30 Aug 2026 07:40:56 +0000
Subject: [PATCH] docs(proxy): clarify spend semantics on /v2/user/info and
 /user/daily/activity

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../internal_user_endpoints.py                    | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/litellm/proxy/management_endpoints/internal_user_endpoints.py b/litellm/proxy/management_endpoints/internal_user_endpoints.py
index 9a98bdbb6b1..73e993b37a1 100644
--- a/litellm/proxy/management_endpoints/internal_user_endpoints.py
+++ b/litellm/proxy/management_endpoints/internal_user_endpoints.py
@@ -997,6 +997,13 @@ 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 is zeroed by the
+    budget reset job whenever `budget_reset_at` elapses (see `budget_duration`). 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 immutable daily
+    spend records that 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
@@ -2687,6 +2694,10 @@ async def get_user_daily_activity(
 
     Meant to optimize querying spend data for analytics for a user.
 
+    Reads immutable daily spend records, which are never affected by budget resets.
+    This can legitimately exceed the `spend` field returned by `/v2/user/info`, which
+    is a running budget counter zeroed on every budget reset.
+
     Returns:
     (by date)
     - spend
@@ -2800,6 +2811,10 @@ 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 immutable daily spend records, which are never affected by budget resets.
+    This can legitimately exceed the `spend` field returned by `/v2/user/info`, which
+    is a running budget counter zeroed on every budget reset.
     """
     from litellm.proxy.proxy_server import prisma_client