From 92e55b3b2262c40e41178435453edf3802819229 Mon Sep 17 00:00:00 2001
From: yassin <yassin@berri.ai>
Date: Tue, 15 Sep 2026 21:17:00 +0000
Subject: [PATCH 01/13] perf(proxy): split aggregated usage query into key-free
 rollups and bounded top-N keys

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/constants.py                          |   4 +
 .../common_daily_activity.py                  | 241 +++++++-----
 .../common_daily_activity.py                  |   5 +
 .../test_common_daily_activity.py             | 355 +++++++++++++++---
 ui/litellm-dashboard/src/lib/http/schema.d.ts |   5 +
 5 files changed, 479 insertions(+), 131 deletions(-)

diff --git a/litellm/constants.py b/litellm/constants.py
index ba5ec73d435..36bc16a0ae3 100644
--- a/litellm/constants.py
+++ b/litellm/constants.py
@@ -2027,6 +2027,10 @@ MCP_SPEND_LOG_MODEL_PREFIX: Final[str] = "MCP: "
 PTU_SENTINEL_API_KEY: Final[str] = "__ptu_flat_cost__"
 PTU_ROLLUP_JOB_ID: Final[str] = "ptu_flat_cost_rollup_job"
 PTU_ROLLUP_LOCK_TTL_SECONDS: Final[int] = 900
+# Per-api_key rollups on the aggregated usage endpoint cover only the top N keys
+# by spend so the result set stops growing with key count. Totals and the
+# model/provider/endpoint rollups still cover every key.
+USAGE_TOP_API_KEYS_LIMIT: Final[int] = 100
 # Furthest back the catch-up pass looks for unpriced PTU days when a deployment
 # declares no ptu_effective_from, bounding the scan for an open-ended window.
 PTU_ROLLUP_MAX_BACKFILL_DAYS: Final[int] = 90
diff --git a/litellm/proxy/management_endpoints/common_daily_activity.py b/litellm/proxy/management_endpoints/common_daily_activity.py
index 44ed0017e42..4aafd416263 100644
--- a/litellm/proxy/management_endpoints/common_daily_activity.py
+++ b/litellm/proxy/management_endpoints/common_daily_activity.py
@@ -9,7 +9,7 @@ from fastapi import HTTPException, status
 from typing_extensions import ReadOnly, TypedDict
 
 from litellm._logging import verbose_proxy_logger
-from litellm.constants import PTU_SENTINEL_API_KEY
+from litellm.constants import PTU_SENTINEL_API_KEY, USAGE_TOP_API_KEYS_LIMIT
 from litellm.proxy._types import CommonProxyErrors
 from litellm.proxy.spend_tracking.key_metadata_recovery import (
     attach_user_emails,
@@ -169,6 +169,32 @@ class _EntityRollupRow(_GroupingSetsRow):
     api_key_rolled: int
 
 
+class _AggregatedQueryKwargs(TypedDict):
+    """Filter arguments shared by the three aggregated SQL builders."""
+
+    table_name: ReadOnly[str]
+    entity_id_field: ReadOnly[str]
+    entity_id: ReadOnly[str | list[str] | None]
+    start_date: ReadOnly[str]
+    end_date: ReadOnly[str]
+    model: ReadOnly[str | None]
+    api_key: ReadOnly[str | list[str] | None]
+    exclude_entity_ids: ReadOnly[list[str] | None]
+    timezone_offset_minutes: ReadOnly[int | None]
+    include_current_utc_day: ReadOnly[bool]
+
+
+_SqlQuery = tuple[str, list[str]]
+
+
+async def _query_raw_optional(
+    prisma_client: PrismaClient, query: _SqlQuery | None
+) -> list[dict[str, object]] | None:  # mutable-ok: prisma query_raw return shape
+    if query is None:
+        return None
+    return await prisma_client.db.query_raw(query[0], *query[1])
+
+
 def _reported_flat_cost(record: DailySpendRecord | _GroupingSetsRow) -> float:
     """Flat cost a daily row reports, which is zero unless PTU cost attribution is enabled.
 
@@ -689,6 +715,27 @@ def _ptu_flat_cost_select(table_name: str) -> str:
     return "0::float AS ptu_flat_cost"
 
 
+def _rollup_metric_select(table_name: str) -> str:
+    return f"""
+            SUM(spend)::float AS spend,
+            {_ptu_flat_cost_select(table_name)},
+            SUM(prompt_tokens)::bigint AS prompt_tokens,
+            SUM(completion_tokens)::bigint AS completion_tokens,
+            SUM(cache_read_input_tokens)::bigint AS cache_read_input_tokens,
+            SUM(cache_creation_input_tokens)::bigint AS cache_creation_input_tokens,
+            SUM(compression_saved_tokens)::bigint AS compression_saved_tokens,
+            SUM(compression_savings_spend)::float AS compression_savings_spend,
+            SUM(prompt_caching_savings_spend)::float AS prompt_caching_savings_spend,
+            SUM(gateway_injected_caching_savings_spend)::float AS gateway_injected_caching_savings_spend,
+            SUM(autorouter_savings_spend)::float AS autorouter_savings_spend,
+            SUM(api_requests)::bigint AS api_requests,
+            SUM(successful_requests)::bigint AS successful_requests,
+            SUM(failed_requests)::bigint AS failed_requests"""
+
+
+_MODEL_GROUP_EXPR: Final = "COALESCE(NULLIF(model_group, ''), model)"
+
+
 def _build_aggregated_sql_query(
     *,
     table_name: str,
@@ -702,12 +749,16 @@ def _build_aggregated_sql_query(
     timezone_offset_minutes: int | None = None,
     include_current_utc_day: bool = False,
 ) -> tuple[str, list[str]]:  # mutable-ok: SQL text plus its ordered $N params
-    """Build a parameterized SQL GROUP BY query for aggregated daily activity.
+    """Build the key-free GROUPING SETS query for aggregated daily activity.
 
-    Groups by (date, api_key, model, model_group, custom_llm_provider,
-    mcp_namespaced_tool_name, endpoint) with SUMs on all metric columns.
-    The entity_id column is intentionally omitted from GROUP BY to collapse
-    rows across entities — this is where the biggest row reduction comes from.
+    Emits the grand total, per-date totals and the per-(date, model), model_group,
+    provider, mcp tool and endpoint rollups. api_key is never a grouping column here,
+    so the row count is bounded by dates x distinct models/providers/endpoints and
+    does not grow with the number of keys. Per-key rollups come from
+    _build_top_api_keys_sql_query. Both queries emit the same 7-bit group_level
+    bitmask (date, api_key, model, model_group, provider, mcp, endpoint); this one
+    hard-codes the api_key bit to "rolled up" so the dispatcher can consume the two
+    result sets as one stream.
 
     Returns:
         Tuple of (sql_query, params_list) ready for prisma_client.db.query_raw().
@@ -730,14 +781,6 @@ def _build_aggregated_sql_query(
         exclude_entity_ids=exclude_entity_ids,
     )
 
-    # Postgres computes every rollup level the response needs — per-date
-    # totals, per-(date, model), per-(date, model, api_key), per-provider,
-    # etc. — in a single pass via GROUPING SETS. The GROUPING() bitmask
-    # encodes which level a row belongs to so Python can dispatch rows
-    # straight into their buckets without re-summing. The leaf grouping
-    # is omitted on purpose: nothing in the response shape needs it once
-    # all the rollups are present.
-    #
     # TODO: drop the successful_requests/failed_requests aggregates (and the
     # total_successful_requests metadata they feed) once the admin UI reads SGR
     # only from LiteLLM_DailyGatewayRequests. The remaining spend, token and
@@ -745,44 +788,25 @@ def _build_aggregated_sql_query(
     sql_query: Final = f"""
         SELECT
             date,
-            api_key,
+            NULL::text AS api_key,
             model,
-            COALESCE(NULLIF(model_group, ''), model) AS model_group,
+            {_MODEL_GROUP_EXPR} AS model_group,
             custom_llm_provider,
             mcp_namespaced_tool_name,
             endpoint,
-            GROUPING(date, api_key, model, COALESCE(NULLIF(model_group, ''), model),
-                     custom_llm_provider, mcp_namespaced_tool_name,
-                     endpoint) AS group_level,
-            SUM(spend)::float AS spend,
-            {_ptu_flat_cost_select(table_name)},
-            SUM(prompt_tokens)::bigint AS prompt_tokens,
-            SUM(completion_tokens)::bigint AS completion_tokens,
-            SUM(cache_read_input_tokens)::bigint AS cache_read_input_tokens,
-            SUM(cache_creation_input_tokens)::bigint AS cache_creation_input_tokens,
-            SUM(compression_saved_tokens)::bigint AS compression_saved_tokens,
-            SUM(compression_savings_spend)::float AS compression_savings_spend,
-            SUM(prompt_caching_savings_spend)::float AS prompt_caching_savings_spend,
-            SUM(gateway_injected_caching_savings_spend)::float AS gateway_injected_caching_savings_spend,
-            SUM(autorouter_savings_spend)::float AS autorouter_savings_spend,
-            SUM(api_requests)::bigint AS api_requests,
-            SUM(successful_requests)::bigint AS successful_requests,
-            SUM(failed_requests)::bigint AS failed_requests
+            (GROUPING(date) << 6) | {_API_KEY_ROLLED_UP_BIT}
+                | GROUPING(model, {_MODEL_GROUP_EXPR},
+                           custom_llm_provider, mcp_namespaced_tool_name,
+                           endpoint) AS group_level,{_rollup_metric_select(table_name)}
         FROM "{pg_table}"
         WHERE {where_clause}
         GROUP BY GROUPING SETS (
             (date),
-            (date, api_key),
             (date, model),
-            (date, model, api_key),
-            (date, COALESCE(NULLIF(model_group, ''), model)),
-            (date, COALESCE(NULLIF(model_group, ''), model), api_key),
+            (date, {_MODEL_GROUP_EXPR}),
             (date, custom_llm_provider),
-            (date, custom_llm_provider, api_key),
             (date, mcp_namespaced_tool_name),
-            (date, mcp_namespaced_tool_name, api_key),
             (date, endpoint),
-            (date, endpoint, api_key),
             ()
         )
     """
@@ -790,6 +814,80 @@ def _build_aggregated_sql_query(
     return sql_query, sql_params
 
 
+def _build_top_api_keys_sql_query(
+    *,
+    table_name: str,
+    entity_id_field: str,
+    entity_id: str | list[str] | None,  # mutable-ok: filter union shared with the paginated path
+    start_date: str,
+    end_date: str,
+    model: str | None,
+    api_key: str | list[str] | None,  # mutable-ok: filter union shared with the paginated path
+    exclude_entity_ids: list[str] | None = None,  # mutable-ok: filter union shared with the paginated path
+    timezone_offset_minutes: int | None = None,
+    include_current_utc_day: bool = False,
+) -> tuple[str, list[str]]:  # mutable-ok: SQL text plus its ordered $N params
+    """Per-key companion to _build_aggregated_sql_query.
+
+    Ranks keys by spend over the same WHERE clause, keeps the top
+    USAGE_TOP_API_KEYS_LIMIT (ties broken by api_key so the set is stable across
+    refreshes) and emits the six (date, <dimension>, api_key) rollups for those keys
+    only. The PTU flat-cost sentinel never ranks, so it cannot occupy a visible slot.
+    """
+    pg_table: Final = _PRISMA_TO_PG_TABLE.get(table_name)
+    if pg_table is None:
+        raise ValueError(f"Unknown table name: {table_name}")
+
+    adjusted_start, adjusted_end = _adjust_dates_for_timezone(
+        start_date, end_date, timezone_offset_minutes, include_current_utc_day
+    )
+
+    where_clause, where_params = _build_aggregated_where_clause(
+        entity_id_field=entity_id_field,
+        entity_id=entity_id,
+        adjusted_start=adjusted_start,
+        adjusted_end=adjusted_end,
+        model=model,
+        api_key=api_key,
+        exclude_entity_ids=exclude_entity_ids,
+    )
+    sentinel_param: Final = f"${len(where_params) + 1}"
+
+    sql_query: Final = f"""
+        WITH top_api_keys AS (
+            SELECT api_key
+            FROM "{pg_table}"
+            WHERE {where_clause} AND api_key <> {sentinel_param}
+            GROUP BY api_key
+            ORDER BY SUM(spend) DESC, api_key
+            LIMIT {USAGE_TOP_API_KEYS_LIMIT}
+        )
+        SELECT
+            date,
+            api_key,
+            model,
+            {_MODEL_GROUP_EXPR} AS model_group,
+            custom_llm_provider,
+            mcp_namespaced_tool_name,
+            endpoint,
+            GROUPING(date, api_key, model, {_MODEL_GROUP_EXPR},
+                     custom_llm_provider, mcp_namespaced_tool_name,
+                     endpoint) AS group_level,{_rollup_metric_select(table_name)}
+        FROM "{pg_table}"
+        WHERE {where_clause} AND api_key IN (SELECT api_key FROM top_api_keys)
+        GROUP BY GROUPING SETS (
+            (date, api_key),
+            (date, model, api_key),
+            (date, {_MODEL_GROUP_EXPR}, api_key),
+            (date, custom_llm_provider, api_key),
+            (date, mcp_namespaced_tool_name, api_key),
+            (date, endpoint, api_key)
+        )
+    """
+
+    return sql_query, [*where_params, PTU_SENTINEL_API_KEY]
+
+
 def _build_entity_rollup_sql_query(
     *,
     table_name: str,
@@ -832,21 +930,7 @@ def _build_entity_rollup_sql_query(
             "{entity_id_field}" AS entity_id,
             date,
             api_key,
-            GROUPING(api_key) AS api_key_rolled,
-            SUM(spend)::float AS spend,
-            {_ptu_flat_cost_select(table_name)},
-            SUM(prompt_tokens)::bigint AS prompt_tokens,
-            SUM(completion_tokens)::bigint AS completion_tokens,
-            SUM(cache_read_input_tokens)::bigint AS cache_read_input_tokens,
-            SUM(cache_creation_input_tokens)::bigint AS cache_creation_input_tokens,
-            SUM(compression_saved_tokens)::bigint AS compression_saved_tokens,
-            SUM(compression_savings_spend)::float AS compression_savings_spend,
-            SUM(prompt_caching_savings_spend)::float AS prompt_caching_savings_spend,
-            SUM(gateway_injected_caching_savings_spend)::float AS gateway_injected_caching_savings_spend,
-            SUM(autorouter_savings_spend)::float AS autorouter_savings_spend,
-            SUM(api_requests)::bigint AS api_requests,
-            SUM(successful_requests)::bigint AS successful_requests,
-            SUM(failed_requests)::bigint AS failed_requests
+            GROUPING(api_key) AS api_key_rolled,{_rollup_metric_select(table_name)}
         FROM "{pg_table}"
         WHERE {where_clause}
         GROUP BY GROUPING SETS (
@@ -948,6 +1032,7 @@ async def _aggregate_spend_records(
 # current grouping set's key), 0 when the column is part of the key.
 _GROUP_GRAND_TOTAL: Final = 127  # 0b1111111 — all rolled up
 _GROUP_DATE: Final = 63  # 0b0111111 — only date kept
+_API_KEY_ROLLED_UP_BIT: Final = 32  # 0b0100000 — api_key position in the 7-bit mask
 _GROUP_DATE_API_KEY: Final = 31  # 0b0011111
 _GROUP_DATE_MODEL: Final = 47  # 0b0101111
 _GROUP_DATE_MODEL_API_KEY: Final = 15  # 0b0001111
@@ -1311,9 +1396,11 @@ async def get_daily_activity_aggregated(
 ) -> SpendAnalyticsPaginatedResponse:
     """Aggregated variant that returns the full result set (no pagination).
 
-    Uses SQL GROUP BY to aggregate rows in the database rather than fetching
-    all individual rows into Python. This collapses rows across entities
-    (users/teams/orgs), reducing ~150k rows to ~2-3k grouped rows.
+    Runs two GROUPING SETS queries in parallel: a key-free one for totals and the
+    model/provider/mcp/endpoint rollups (row count independent of key cardinality)
+    and a bounded one for the per-key rollups of the top USAGE_TOP_API_KEYS_LIMIT
+    keys by spend. breakdown.api_keys and every api_key_breakdown therefore list at
+    most that many keys, while the totals and the key-free rollups cover every key.
 
     include_entity_breakdown runs a small companion rollup query and folds
     `breakdown.entities` onto the response, as entity-scoped views like Team Usage need.
@@ -1333,7 +1420,7 @@ async def get_daily_activity_aggregated(
         )
 
     try:
-        sql_query, sql_params = _build_aggregated_sql_query(
+        query_kwargs: Final = _AggregatedQueryKwargs(
             table_name=table_name,
             entity_id_field=entity_id_field,
             entity_id=entity_id,
@@ -1345,36 +1432,17 @@ async def get_daily_activity_aggregated(
             timezone_offset_minutes=timezone_offset_minutes,
             include_current_utc_day=include_current_utc_day,
         )
+        key_free_sql, key_free_params = _build_aggregated_sql_query(**query_kwargs)
+        top_keys_sql, top_keys_params = _build_top_api_keys_sql_query(**query_kwargs)
+        entity_query: Final = _build_entity_rollup_sql_query(**query_kwargs) if include_entity_breakdown else None
 
-        entity_query: Final = (
-            _build_entity_rollup_sql_query(
-                table_name=table_name,
-                entity_id_field=entity_id_field,
-                entity_id=entity_id,
-                start_date=start_date,
-                end_date=end_date,
-                model=model,
-                api_key=api_key,
-                exclude_entity_ids=exclude_entity_ids,
-                timezone_offset_minutes=timezone_offset_minutes,
-                include_current_utc_day=include_current_utc_day,
-            )
-            if include_entity_breakdown
-            else None
+        raw_key_free_rows, raw_top_key_rows, raw_entity_rows = await asyncio.gather(
+            prisma_client.db.query_raw(key_free_sql, *key_free_params),
+            prisma_client.db.query_raw(top_keys_sql, *top_keys_params),
+            _query_raw_optional(prisma_client, entity_query),
         )
 
-        # Execute the GROUPING SETS query (one row per rollup level), alongside
-        # the per-entity companion rollup when the caller wants entities.
-        raw_rows, raw_entity_rows = (
-            await asyncio.gather(
-                prisma_client.db.query_raw(sql_query, *sql_params),
-                prisma_client.db.query_raw(entity_query[0], *entity_query[1]),
-            )
-            if entity_query is not None
-            else (await prisma_client.db.query_raw(sql_query, *sql_params), None)
-        )
-
-        records: Final = [_GroupingSetsRow(**row) for row in (raw_rows or [])]
+        records: Final = [_GroupingSetsRow(**row) for row in (*(raw_key_free_rows or ()), *(raw_top_key_rows or ()))]
 
         # The grouping-sets dispatcher places each row directly in its bucket
         # using the row's GROUPING() bitmask. No Python-side summing needed.
@@ -1426,6 +1494,7 @@ async def get_daily_activity_aggregated(
                 page=1,
                 total_pages=1,
                 has_more=False,
+                api_key_limit=USAGE_TOP_API_KEYS_LIMIT,
             ),
         )
 
diff --git a/litellm/types/proxy/management_endpoints/common_daily_activity.py b/litellm/types/proxy/management_endpoints/common_daily_activity.py
index 090e5c42376..f58d40dfa9c 100644
--- a/litellm/types/proxy/management_endpoints/common_daily_activity.py
+++ b/litellm/types/proxy/management_endpoints/common_daily_activity.py
@@ -96,6 +96,11 @@ class DailySpendMetadata(BaseModel):
     page: int = Field(default=1)
     total_pages: int = Field(default=1)
     has_more: bool = Field(default=False)
+    api_key_limit: int | None = Field(
+        default=None,
+        description="When set, api_keys and every api_key_breakdown list at most this many keys, "
+        "ranked by spend. Totals and the model, provider, mcp and endpoint rollups still cover every key.",
+    )
 
 
 class SpendAnalyticsPaginatedResponse(BaseModel):
diff --git a/tests/test_litellm/proxy/management_endpoints/test_common_daily_activity.py b/tests/test_litellm/proxy/management_endpoints/test_common_daily_activity.py
index 71896a18f48..dec98a1da27 100644
--- a/tests/test_litellm/proxy/management_endpoints/test_common_daily_activity.py
+++ b/tests/test_litellm/proxy/management_endpoints/test_common_daily_activity.py
@@ -1,17 +1,24 @@
+import re
+from collections.abc import Sequence
 from datetime import datetime, timedelta, timezone
 from types import SimpleNamespace
 from typing import Final
 from unittest.mock import AsyncMock, MagicMock
 
+import psycopg
 import pytest
+from psycopg.rows import dict_row
+from pytest_postgresql import factories
 
 from litellm.proxy.spend_tracking.ptu_feature_flag import PTU_COST_ATTRIBUTION_ENV_VAR
 
 
+from litellm.constants import PTU_SENTINEL_API_KEY, USAGE_TOP_API_KEYS_LIMIT
 from litellm.proxy.management_endpoints.common_daily_activity import (
     _adjust_dates_for_timezone,
     _build_aggregated_sql_query,
     _build_entity_rollup_sql_query,
+    _build_top_api_keys_sql_query,
     _is_user_agent_tag,
     _record_to_spend_metrics,
     get_api_key_metadata,
@@ -159,7 +166,7 @@ async def test_get_daily_activity_aggregated_with_endpoint_breakdown():
         "autorouter_savings_spend": 0.0,
         "failed_requests": 0,
     }
-    mock_rows = [
+    key_free_rows = [
         # (date, endpoint) — rolls up across api_keys and models
         {
             **base,
@@ -185,31 +192,6 @@ async def test_get_daily_activity_aggregated_with_endpoint_breakdown():
             "api_requests": 1,
             "successful_requests": 1,
         },
-        # (date, endpoint, api_key) — populates the per-key sub-bucket
-        {
-            **base,
-            "date": "2024-01-01",
-            "endpoint": "/v1/chat/completions",
-            "api_key": "key-1",
-            "group_level": 30,
-            "spend": 15.0,
-            "prompt_tokens": 150,
-            "completion_tokens": 75,
-            "api_requests": 2,
-            "successful_requests": 2,
-        },
-        {
-            **base,
-            "date": "2024-01-01",
-            "endpoint": "/v1/embeddings",
-            "api_key": "key-2",
-            "group_level": 30,
-            "spend": 3.0,
-            "prompt_tokens": 30,
-            "completion_tokens": 0,
-            "api_requests": 1,
-            "successful_requests": 1,
-        },
         # (date) — per-date totals
         {
             **base,
@@ -237,8 +219,35 @@ async def test_get_daily_activity_aggregated_with_endpoint_breakdown():
             "successful_requests": 3,
         },
     ]
+    top_key_rows = [
+        # (date, endpoint, api_key) — populates the per-key sub-bucket
+        {
+            **base,
+            "date": "2024-01-01",
+            "endpoint": "/v1/chat/completions",
+            "api_key": "key-1",
+            "group_level": 30,
+            "spend": 15.0,
+            "prompt_tokens": 150,
+            "completion_tokens": 75,
+            "api_requests": 2,
+            "successful_requests": 2,
+        },
+        {
+            **base,
+            "date": "2024-01-01",
+            "endpoint": "/v1/embeddings",
+            "api_key": "key-2",
+            "group_level": 30,
+            "spend": 3.0,
+            "prompt_tokens": 30,
+            "completion_tokens": 0,
+            "api_requests": 1,
+            "successful_requests": 1,
+        },
+    ]
 
-    mock_prisma.db.query_raw = AsyncMock(return_value=mock_rows)
+    mock_prisma.db.query_raw = AsyncMock(side_effect=[key_free_rows, top_key_rows])
     mock_prisma.db.litellm_verificationtoken = MagicMock()
     mock_prisma.db.litellm_verificationtoken.find_many = AsyncMock(return_value=[])
 
@@ -284,8 +293,11 @@ async def test_get_daily_activity_aggregated_with_endpoint_breakdown():
     assert "key-2" in embeddings_endpoint.api_key_breakdown
     assert embeddings_endpoint.api_key_breakdown["key-2"].metrics.spend == 3.0
 
-    # Verify query_raw was called (not find_many)
-    mock_prisma.db.query_raw.assert_called_once()
+    # One key-free rollup query plus one bounded per-key query, no find_many
+    assert mock_prisma.db.query_raw.call_count == 2
+    key_free_sql, top_keys_sql = (call.args[0] for call in mock_prisma.db.query_raw.call_args_list)
+    assert "top_api_keys" not in key_free_sql
+    assert "WITH top_api_keys AS" in top_keys_sql
 
 
 @pytest.mark.asyncio
@@ -812,7 +824,7 @@ async def test_aggregated_activity_preserves_metadata_for_deleted_keys():
         "autorouter_savings_spend": 0.0,
         "failed_requests": 0,
     }
-    mock_rows = [
+    key_free_rows = [
         {
             **base,
             "date": "2024-01-01",
@@ -825,6 +837,8 @@ async def test_aggregated_activity_preserves_metadata_for_deleted_keys():
             "api_requests": 1,
             "successful_requests": 1,
         },
+    ]
+    top_key_rows = [
         {
             **base,
             "date": "2024-01-01",
@@ -839,7 +853,7 @@ async def test_aggregated_activity_preserves_metadata_for_deleted_keys():
         },
     ]
 
-    mock_prisma.db.query_raw = AsyncMock(return_value=mock_rows)
+    mock_prisma.db.query_raw = AsyncMock(side_effect=[key_free_rows, top_key_rows])
 
     # Active table returns nothing for this key
     mock_prisma.db.litellm_verificationtoken = MagicMock()
@@ -1240,17 +1254,61 @@ class TestBuildAggregatedSqlQuery:
         normalized = " ".join(sql.split())
         fallback = "COALESCE(NULLIF(model_group, ''), model)"
         assert f"{fallback} AS model_group" in normalized
-        assert (
-            f"GROUPING(date, api_key, model, {fallback}, "
-            "custom_llm_provider, mcp_namespaced_tool_name, endpoint) AS group_level" in normalized
-        )
-        assert f"(date, {fallback}), (date, {fallback}, api_key)," in normalized
+        assert f"GROUPING(model, {fallback}, custom_llm_provider, mcp_namespaced_tool_name, endpoint)" in normalized
+        assert f"(date, {fallback})," in normalized
         assert "(date, model_group)" not in normalized
         assert "COALESCE(model_group, model)" not in normalized
 
+    def test_key_free_query_never_groups_by_api_key(self):
+        """The main rollup query must not emit one row per key, that is what blew up
+        the query engine at 3k+ keys. Every grouping set stays key-free and api_key
+        is projected as a NULL literal so the dispatcher's row shape is unchanged."""
+        sql, _ = _build_aggregated_sql_query(
+            table_name="litellm_dailyuserspend",
+            entity_id_field="user_id",
+            entity_id=None,
+            start_date="2026-07-01",
+            end_date="2026-07-01",
+            model=None,
+            api_key=None,
+        )
+
+        normalized = " ".join(sql.split())
+        grouping_block = normalized.split("GROUP BY GROUPING SETS (", 1)[1]
+        assert "api_key" not in grouping_block
+        assert "NULL::text AS api_key" in normalized
+
+    def test_top_api_keys_query_ranks_keys_deterministically_and_shares_filters(self):
+        sql, params = _build_top_api_keys_sql_query(
+            table_name="litellm_dailyuserspend",
+            entity_id_field="user_id",
+            entity_id="user-1",
+            start_date="2026-05-29",
+            end_date="2026-06-02",
+            model="bedrock/global.anthropic.claude-opus-4-8",
+            api_key="sk-test",
+            timezone_offset_minutes=-330,
+        )
+
+        normalized = " ".join(sql.split())
+        assert f"ORDER BY SUM(spend) DESC, api_key LIMIT {USAGE_TOP_API_KEYS_LIMIT}" in normalized
+        assert "api_key IN (SELECT api_key FROM top_api_keys)" in normalized
+        assert "api_key <> $6" in normalized
+        grouping_block = normalized.split("GROUP BY GROUPING SETS (", 1)[1]
+        assert grouping_block.count(", api_key)") == 6
+        assert grouping_block.count("(date") == 6
+        assert params == [
+            "2026-05-29",
+            "2026-06-02",
+            "user-1",
+            "bedrock/global.anthropic.claude-opus-4-8",
+            "sk-test",
+            PTU_SENTINEL_API_KEY,
+        ]
+
 
 class TestAggregatedEmptyEntityFilter:
-    _BUILDERS: Final = (_build_aggregated_sql_query, _build_entity_rollup_sql_query)
+    _BUILDERS: Final = (_build_aggregated_sql_query, _build_top_api_keys_sql_query, _build_entity_rollup_sql_query)
 
     @pytest.mark.parametrize("build", _BUILDERS)
     def test_empty_entity_list_emits_no_degenerate_in_clause(self, build):
@@ -1267,7 +1325,8 @@ class TestAggregatedEmptyEntityFilter:
         normalized = " ".join(sql.split())
         assert "IN ()" not in normalized
         assert '"team_id" IN' not in normalized
-        assert params == ["2026-08-01", "2026-08-19"]
+        sentinel_params = [PTU_SENTINEL_API_KEY] if build is _build_top_api_keys_sql_query else []
+        assert params == ["2026-08-01", "2026-08-19", *sentinel_params]
 
     @pytest.mark.parametrize("build", _BUILDERS)
     def test_empty_entity_list_matches_nothing_rather_than_everything(self, build):
@@ -1298,7 +1357,8 @@ class TestAggregatedEmptyEntityFilter:
         normalized = " ".join(sql.split())
         assert '"team_id" IN ($3, $4)' in normalized
         assert "FALSE" not in normalized
-        assert params == ["2026-08-01", "2026-08-19", "team-alpha", "team-beta"]
+        sentinel_params = [PTU_SENTINEL_API_KEY] if build is _build_top_api_keys_sql_query else []
+        assert params == ["2026-08-01", "2026-08-19", "team-alpha", "team-beta", *sentinel_params]
 
 
 @pytest.mark.asyncio
@@ -1313,7 +1373,7 @@ async def test_get_daily_activity_aggregated_empty_result_set():
     mock_prisma = MagicMock()
     mock_prisma.db = MagicMock()
 
-    mock_rows = [
+    key_free_rows = [
         {
             "date": None,
             "api_key": None,
@@ -1338,7 +1398,7 @@ async def test_get_daily_activity_aggregated_empty_result_set():
             "failed_requests": None,
         }
     ]
-    mock_prisma.db.query_raw = AsyncMock(return_value=mock_rows)
+    mock_prisma.db.query_raw = AsyncMock(side_effect=[key_free_rows, []])
 
     result = await get_daily_activity_aggregated(
         prisma_client=mock_prisma,
@@ -1365,6 +1425,211 @@ async def test_get_daily_activity_aggregated_empty_result_set():
     assert result.metadata.total_compression_saved_tokens == 0
 
 
+_aggregated_postgresql_proc: Final = factories.postgresql_proc()
+_aggregated_postgresql: Final = factories.postgresql("_aggregated_postgresql_proc")
+
+_DAILY_USER_SPEND_DDL: Final = """
+    CREATE TABLE "LiteLLM_DailyUserSpend" (
+        id TEXT PRIMARY KEY,
+        user_id TEXT,
+        date TEXT NOT NULL,
+        api_key TEXT NOT NULL,
+        model TEXT,
+        model_group TEXT,
+        custom_llm_provider TEXT,
+        mcp_namespaced_tool_name TEXT,
+        endpoint TEXT,
+        prompt_tokens BIGINT DEFAULT 0,
+        completion_tokens BIGINT DEFAULT 0,
+        cache_read_input_tokens BIGINT DEFAULT 0,
+        cache_creation_input_tokens BIGINT DEFAULT 0,
+        compression_saved_tokens BIGINT DEFAULT 0,
+        compression_savings_spend DOUBLE PRECISION DEFAULT 0,
+        prompt_caching_savings_spend DOUBLE PRECISION DEFAULT 0,
+        gateway_injected_caching_savings_spend DOUBLE PRECISION DEFAULT 0,
+        autorouter_savings_spend DOUBLE PRECISION DEFAULT 0,
+        spend DOUBLE PRECISION DEFAULT 0,
+        api_requests BIGINT DEFAULT 0,
+        successful_requests BIGINT DEFAULT 0,
+        failed_requests BIGINT DEFAULT 0
+    )
+"""
+
+
+def _seed_daily_user_spend(conn: psycopg.Connection, rows: Sequence[tuple[object, ...]]) -> None:
+    with conn.cursor() as cur:
+        cur.execute(_DAILY_USER_SPEND_DDL)
+        cur.executemany(
+            """
+            INSERT INTO "LiteLLM_DailyUserSpend"
+                (id, user_id, date, api_key, model, model_group, custom_llm_provider,
+                 endpoint, prompt_tokens, spend, api_requests, successful_requests)
+            VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s)
+            """,
+            rows,
+        )
+    conn.commit()
+
+
+def _psycopg_query_raw(conn: psycopg.Connection, row_counts: list[int]):
+    """Run the proxy's $N-parameterized SQL through psycopg, recording each result size."""
+
+    async def query_raw(sql: str, *params: str) -> list[dict[str, object]]:
+        converted: Final = re.sub(r"\$(\d+)", r"%(p\1)s", sql)
+        with conn.cursor(row_factory=dict_row) as cur:
+            cur.execute(
+                converted,  # pyright: ignore[reportArgumentType]  # psycopg stubs want a literal-typed query
+                {f"p{i}": v for i, v in enumerate(params, start=1)},
+            )
+            rows: Final = cur.fetchall()
+        row_counts.append(len(rows))
+        return rows
+
+    return query_raw
+
+
+@pytest.mark.asyncio
+async def test_get_daily_activity_aggregated_bounds_api_key_rollups(
+    _aggregated_postgresql: psycopg.Connection,
+):
+    """Run both GROUPING SETS queries against real Postgres with more keys than the cap.
+
+    key-004 and key-005 tie on spend exactly at the USAGE_TOP_API_KEYS_LIMIT
+    cutoff; the api_key tiebreaker must keep key-004 and drop key-005. The PTU
+    sentinel outspends every key but must not take a slot. Excluded keys and the
+    sentinel still count toward the totals and the model rollup, which come from
+    the key-free query.
+    """
+    n_keys: Final = USAGE_TOP_API_KEYS_LIMIT + 5
+    key_rows: Final = [
+        (
+            f"row-{i:03d}",
+            f"user-{i:03d}",
+            "2026-06-01",
+            f"key-{i:03d}",
+            "gpt-5",
+            "",
+            "openai",
+            "/v1/chat/completions",
+            10,
+            6.0 if i == 4 else float(i + 1),
+            1,
+            1,
+        )
+        for i in range(n_keys)
+    ]
+    sentinel_row: Final = (
+        "row-ptu",
+        None,
+        "2026-06-01",
+        PTU_SENTINEL_API_KEY,
+        "gpt-5",
+        "",
+        "azure",
+        None,
+        0,
+        1000.0,
+        0,
+        0,
+    )
+    _seed_daily_user_spend(_aggregated_postgresql, [*key_rows, sentinel_row])
+    key_spend: Final = sum(6.0 if i == 4 else float(i + 1) for i in range(n_keys))
+
+    row_counts: Final[list[int]] = []  # mutable-ok: out-param for the query_raw shim
+    mock_prisma = MagicMock()
+    mock_prisma.db = MagicMock()
+    mock_prisma.db.query_raw = _psycopg_query_raw(_aggregated_postgresql, row_counts)
+    mock_prisma.db.litellm_verificationtoken.find_many = AsyncMock(return_value=[])
+    mock_prisma.db.litellm_deletedverificationtoken.find_many = AsyncMock(return_value=[])
+
+    result = await get_daily_activity_aggregated(
+        prisma_client=mock_prisma,
+        table_name="litellm_dailyuserspend",
+        entity_id_field="user_id",
+        entity_id=None,
+        entity_metadata_field=None,
+        start_date="2026-06-01",
+        end_date="2026-06-01",
+        model=None,
+        api_key=None,
+    )
+
+    # Key-free query: (), (date), (date, model), (date, model_group), two providers,
+    # one mcp NULL bucket, endpoint plus its NULL bucket = 9 rows regardless of key count.
+    # Top-key query: six per-key grouping sets, each capped at the limit.
+    assert row_counts == [9, 6 * USAGE_TOP_API_KEYS_LIMIT]
+
+    assert result.metadata.total_spend == pytest.approx(key_spend + 1000.0)
+    assert result.metadata.total_api_requests == n_keys
+    assert result.metadata.api_key_limit == USAGE_TOP_API_KEYS_LIMIT
+
+    expected_top: Final = {f"key-{i:03d}" for i in range(6, n_keys)} | {"key-004"}
+    day: Final = result.results[0]
+    assert day.metrics.spend == pytest.approx(key_spend + 1000.0)
+    assert set(day.breakdown.api_keys) == expected_top
+    assert day.breakdown.api_keys["key-004"].metrics.spend == 6.0
+    assert "key-005" not in day.breakdown.api_keys
+    assert PTU_SENTINEL_API_KEY not in day.breakdown.api_keys
+
+    assert day.breakdown.models["gpt-5"].metrics.spend == pytest.approx(key_spend + 1000.0)
+    assert set(day.breakdown.models["gpt-5"].api_key_breakdown) == expected_top
+    assert day.breakdown.providers["openai"].metrics.spend == pytest.approx(key_spend)
+    assert set(day.breakdown.providers["openai"].api_key_breakdown) == expected_top
+    assert day.breakdown.endpoints["/v1/chat/completions"].metrics.api_requests == n_keys
+
+
+@pytest.mark.asyncio
+async def test_get_daily_activity_aggregated_explicit_api_key_filter_scopes_both_queries(
+    _aggregated_postgresql: psycopg.Connection,
+):
+    """An explicit api_key filter must scope the key-free totals and the per-key
+    rollups to that key alone, so the two result sets never disagree."""
+    rows: Final = [
+        (
+            f"row-{i}",
+            f"user-{i}",
+            "2026-06-01",
+            f"key-{i}",
+            "gpt-5",
+            "",
+            "openai",
+            "/v1/chat/completions",
+            10,
+            float(i + 1),
+            1,
+            1,
+        )
+        for i in range(3)
+    ]
+    _seed_daily_user_spend(_aggregated_postgresql, rows)
+
+    row_counts: Final[list[int]] = []  # mutable-ok: out-param for the query_raw shim
+    mock_prisma = MagicMock()
+    mock_prisma.db = MagicMock()
+    mock_prisma.db.query_raw = _psycopg_query_raw(_aggregated_postgresql, row_counts)
+    mock_prisma.db.litellm_verificationtoken.find_many = AsyncMock(return_value=[])
+    mock_prisma.db.litellm_deletedverificationtoken.find_many = AsyncMock(return_value=[])
+
+    result = await get_daily_activity_aggregated(
+        prisma_client=mock_prisma,
+        table_name="litellm_dailyuserspend",
+        entity_id_field="user_id",
+        entity_id=None,
+        entity_metadata_field=None,
+        start_date="2026-06-01",
+        end_date="2026-06-01",
+        model=None,
+        api_key="key-1",
+    )
+
+    assert result.metadata.total_spend == 2.0
+    day: Final = result.results[0]
+    assert set(day.breakdown.api_keys) == {"key-1"}
+    assert day.breakdown.api_keys["key-1"].metrics.spend == 2.0
+    assert day.breakdown.models["gpt-5"].metrics.spend == 2.0
+    assert set(day.breakdown.models["gpt-5"].api_key_breakdown) == {"key-1"}
+
+
 def _no_spend_record():
     """A rollup row for a key with no spend, where SUM() returns NULL (None)."""
     return SimpleNamespace(
@@ -2128,8 +2393,8 @@ async def test_get_daily_activity_aggregated_with_entity_breakdown():
         {**base, "date": None, "group_level": 127, "spend": 18.0},
         {**base, "date": "2024-01-01", "group_level": 63, "spend": 18.0},
         {**base, "date": "2024-01-01", "model": "gpt-4o", "group_level": 47, "spend": 18.0},
-        {**base, "date": "2024-01-01", "api_key": "key-1", "group_level": 31, "spend": 12.0},
     ]
+    top_key_rows = [{**base, "date": "2024-01-01", "api_key": "key-1", "group_level": 31, "spend": 12.0}]
     entity_base = {
         key: value
         for key, value in base.items()
@@ -2156,7 +2421,7 @@ async def test_get_daily_activity_aggregated_with_entity_breakdown():
         },
     ]
 
-    mock_prisma.db.query_raw = AsyncMock(side_effect=[main_rows, entity_rows])
+    mock_prisma.db.query_raw = AsyncMock(side_effect=[main_rows, top_key_rows, entity_rows])
     mock_prisma.db.litellm_verificationtoken = MagicMock()
     mock_prisma.db.litellm_verificationtoken.find_many = AsyncMock(return_value=[])
 
@@ -2173,9 +2438,9 @@ async def test_get_daily_activity_aggregated_with_entity_breakdown():
         include_entity_breakdown=True,
     )
 
-    assert mock_prisma.db.query_raw.call_count == 2
+    assert mock_prisma.db.query_raw.call_count == 3
     main_sql = mock_prisma.db.query_raw.call_args_list[0][0][0]
-    entity_sql = mock_prisma.db.query_raw.call_args_list[1][0][0]
+    entity_sql = mock_prisma.db.query_raw.call_args_list[2][0][0]
     assert "entity_id" not in main_sql
     assert '"team_id" AS entity_id' in entity_sql
     assert '(date, "team_id"),' in entity_sql
diff --git a/ui/litellm-dashboard/src/lib/http/schema.d.ts b/ui/litellm-dashboard/src/lib/http/schema.d.ts
index 4c16a8613eb..f9b234e0298 100644
--- a/ui/litellm-dashboard/src/lib/http/schema.d.ts
+++ b/ui/litellm-dashboard/src/lib/http/schema.d.ts
@@ -27430,6 +27430,11 @@ export interface components {
         };
         /** DailySpendMetadata */
         DailySpendMetadata: {
+            /**
+             * Api Key Limit
+             * @description When set, api_keys and every api_key_breakdown list at most this many keys, ranked by spend. Totals and the model, provider, mcp and endpoint rollups still cover every key.
+             */
+            api_key_limit?: number | null;
             /**
              * Has More
              * @default false

From a0311dddf773c9558b4da9732a4a15c9646e9336 Mon Sep 17 00:00:00 2001
From: yassin <yassin@berri.ai>
Date: Tue, 15 Sep 2026 21:28:09 +0000
Subject: [PATCH 02/13] chore(proxy): regenerate lazy OpenAPI snapshot for
 api_key_limit

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

diff --git a/litellm/proxy/_lazy_openapi_snapshot.json b/litellm/proxy/_lazy_openapi_snapshot.json
index f3b579d22c7..a3f525f0773 100644
--- a/litellm/proxy/_lazy_openapi_snapshot.json
+++ b/litellm/proxy/_lazy_openapi_snapshot.json
@@ -3050,6 +3050,18 @@
         },
         "DailySpendMetadata": {
           "properties": {
+            "api_key_limit": {
+              "anyOf": [
+                {
+                  "type": "integer"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "When set, api_keys and every api_key_breakdown list at most this many keys, ranked by spend. Totals and the model, provider, mcp and endpoint rollups still cover every key.",
+              "title": "Api Key Limit"
+            },
             "has_more": {
               "default": false,
               "title": "Has More",

From f94a40f841c3dcf4498d4cb7acef7b482cf91dc5 Mon Sep 17 00:00:00 2001
From: yassin <yassin@berri.ai>
Date: Tue, 15 Sep 2026 21:52:37 +0000
Subject: [PATCH 03/13] perf(proxy): serve key-free rollups and top-N keys from
 one UNION ALL statement

Both arms now run in a single query_raw call so totals and per-key
breakdowns come from the same snapshot. USAGE_TOP_API_KEYS_LIMIT can be
raised via env for deployments that need every key in the response.

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/constants.py                          |   5 +-
 .../common_daily_activity.py                  | 134 ++++++------------
 .../test_common_daily_activity.py             |  98 ++++++-------
 3 files changed, 87 insertions(+), 150 deletions(-)

diff --git a/litellm/constants.py b/litellm/constants.py
index 36bc16a0ae3..565c6433c6e 100644
--- a/litellm/constants.py
+++ b/litellm/constants.py
@@ -2027,10 +2027,7 @@ MCP_SPEND_LOG_MODEL_PREFIX: Final[str] = "MCP: "
 PTU_SENTINEL_API_KEY: Final[str] = "__ptu_flat_cost__"
 PTU_ROLLUP_JOB_ID: Final[str] = "ptu_flat_cost_rollup_job"
 PTU_ROLLUP_LOCK_TTL_SECONDS: Final[int] = 900
-# Per-api_key rollups on the aggregated usage endpoint cover only the top N keys
-# by spend so the result set stops growing with key count. Totals and the
-# model/provider/endpoint rollups still cover every key.
-USAGE_TOP_API_KEYS_LIMIT: Final[int] = 100
+USAGE_TOP_API_KEYS_LIMIT: Final[int] = int(os.getenv("USAGE_TOP_API_KEYS_LIMIT", "100"))
 # Furthest back the catch-up pass looks for unpriced PTU days when a deployment
 # declares no ptu_effective_from, bounding the scan for an open-ended window.
 PTU_ROLLUP_MAX_BACKFILL_DAYS: Final[int] = 90
diff --git a/litellm/proxy/management_endpoints/common_daily_activity.py b/litellm/proxy/management_endpoints/common_daily_activity.py
index 4aafd416263..95a89460d90 100644
--- a/litellm/proxy/management_endpoints/common_daily_activity.py
+++ b/litellm/proxy/management_endpoints/common_daily_activity.py
@@ -170,8 +170,6 @@ class _EntityRollupRow(_GroupingSetsRow):
 
 
 class _AggregatedQueryKwargs(TypedDict):
-    """Filter arguments shared by the three aggregated SQL builders."""
-
     table_name: ReadOnly[str]
     entity_id_field: ReadOnly[str]
     entity_id: ReadOnly[str | list[str] | None]
@@ -749,16 +747,14 @@ def _build_aggregated_sql_query(
     timezone_offset_minutes: int | None = None,
     include_current_utc_day: bool = False,
 ) -> tuple[str, list[str]]:  # mutable-ok: SQL text plus its ordered $N params
-    """Build the key-free GROUPING SETS query for aggregated daily activity.
+    """Build the GROUPING SETS query for aggregated daily activity.
 
-    Emits the grand total, per-date totals and the per-(date, model), model_group,
-    provider, mcp tool and endpoint rollups. api_key is never a grouping column here,
-    so the row count is bounded by dates x distinct models/providers/endpoints and
-    does not grow with the number of keys. Per-key rollups come from
-    _build_top_api_keys_sql_query. Both queries emit the same 7-bit group_level
-    bitmask (date, api_key, model, model_group, provider, mcp, endpoint); this one
-    hard-codes the api_key bit to "rolled up" so the dispatcher can consume the two
-    result sets as one stream.
+    One statement, two UNION ALL arms over the same WHERE clause. The first arm is
+    key-free: grand total, per-date totals and the (date, model / model_group /
+    provider / mcp / endpoint) rollups, so its row count never grows with the number
+    of keys. The second arm emits the (date, <dimension>, api_key) rollups for the
+    USAGE_TOP_API_KEYS_LIMIT highest-spend keys only. Both arms share the 7-bit
+    group_level bitmask (date, api_key, model, model_group, provider, mcp, endpoint).
 
     Returns:
         Tuple of (sql_query, params_list) ready for prisma_client.db.query_raw().
@@ -771,77 +767,6 @@ def _build_aggregated_sql_query(
         start_date, end_date, timezone_offset_minutes, include_current_utc_day
     )
 
-    where_clause, sql_params = _build_aggregated_where_clause(
-        entity_id_field=entity_id_field,
-        entity_id=entity_id,
-        adjusted_start=adjusted_start,
-        adjusted_end=adjusted_end,
-        model=model,
-        api_key=api_key,
-        exclude_entity_ids=exclude_entity_ids,
-    )
-
-    # TODO: drop the successful_requests/failed_requests aggregates (and the
-    # total_successful_requests metadata they feed) once the admin UI reads SGR
-    # only from LiteLLM_DailyGatewayRequests. The remaining spend, token and
-    # api_requests rollups are still served from here.
-    sql_query: Final = f"""
-        SELECT
-            date,
-            NULL::text AS api_key,
-            model,
-            {_MODEL_GROUP_EXPR} AS model_group,
-            custom_llm_provider,
-            mcp_namespaced_tool_name,
-            endpoint,
-            (GROUPING(date) << 6) | {_API_KEY_ROLLED_UP_BIT}
-                | GROUPING(model, {_MODEL_GROUP_EXPR},
-                           custom_llm_provider, mcp_namespaced_tool_name,
-                           endpoint) AS group_level,{_rollup_metric_select(table_name)}
-        FROM "{pg_table}"
-        WHERE {where_clause}
-        GROUP BY GROUPING SETS (
-            (date),
-            (date, model),
-            (date, {_MODEL_GROUP_EXPR}),
-            (date, custom_llm_provider),
-            (date, mcp_namespaced_tool_name),
-            (date, endpoint),
-            ()
-        )
-    """
-
-    return sql_query, sql_params
-
-
-def _build_top_api_keys_sql_query(
-    *,
-    table_name: str,
-    entity_id_field: str,
-    entity_id: str | list[str] | None,  # mutable-ok: filter union shared with the paginated path
-    start_date: str,
-    end_date: str,
-    model: str | None,
-    api_key: str | list[str] | None,  # mutable-ok: filter union shared with the paginated path
-    exclude_entity_ids: list[str] | None = None,  # mutable-ok: filter union shared with the paginated path
-    timezone_offset_minutes: int | None = None,
-    include_current_utc_day: bool = False,
-) -> tuple[str, list[str]]:  # mutable-ok: SQL text plus its ordered $N params
-    """Per-key companion to _build_aggregated_sql_query.
-
-    Ranks keys by spend over the same WHERE clause, keeps the top
-    USAGE_TOP_API_KEYS_LIMIT (ties broken by api_key so the set is stable across
-    refreshes) and emits the six (date, <dimension>, api_key) rollups for those keys
-    only. The PTU flat-cost sentinel never ranks, so it cannot occupy a visible slot.
-    """
-    pg_table: Final = _PRISMA_TO_PG_TABLE.get(table_name)
-    if pg_table is None:
-        raise ValueError(f"Unknown table name: {table_name}")
-
-    adjusted_start, adjusted_end = _adjust_dates_for_timezone(
-        start_date, end_date, timezone_offset_minutes, include_current_utc_day
-    )
-
     where_clause, where_params = _build_aggregated_where_clause(
         entity_id_field=entity_id_field,
         entity_id=entity_id,
@@ -852,9 +777,38 @@ def _build_top_api_keys_sql_query(
         exclude_entity_ids=exclude_entity_ids,
     )
     sentinel_param: Final = f"${len(where_params) + 1}"
+    metric_select: Final = _rollup_metric_select(table_name)
 
+    # TODO: drop the successful_requests/failed_requests aggregates (and the
+    # total_successful_requests metadata they feed) once the admin UI reads SGR
+    # only from LiteLLM_DailyGatewayRequests. The remaining spend, token and
+    # api_requests rollups are still served from here.
     sql_query: Final = f"""
-        WITH top_api_keys AS (
+        (SELECT
+            date,
+            NULL::text AS api_key,
+            model,
+            {_MODEL_GROUP_EXPR} AS model_group,
+            custom_llm_provider,
+            mcp_namespaced_tool_name,
+            endpoint,
+            (GROUPING(date) << 6) | {_API_KEY_ROLLED_UP_BIT}
+                | GROUPING(model, {_MODEL_GROUP_EXPR},
+                           custom_llm_provider, mcp_namespaced_tool_name,
+                           endpoint) AS group_level,{metric_select}
+        FROM "{pg_table}"
+        WHERE {where_clause}
+        GROUP BY GROUPING SETS (
+            (date),
+            (date, model),
+            (date, {_MODEL_GROUP_EXPR}),
+            (date, custom_llm_provider),
+            (date, mcp_namespaced_tool_name),
+            (date, endpoint),
+            ()
+        ))
+        UNION ALL
+        (WITH top_api_keys AS (
             SELECT api_key
             FROM "{pg_table}"
             WHERE {where_clause} AND api_key <> {sentinel_param}
@@ -872,7 +826,7 @@ def _build_top_api_keys_sql_query(
             endpoint,
             GROUPING(date, api_key, model, {_MODEL_GROUP_EXPR},
                      custom_llm_provider, mcp_namespaced_tool_name,
-                     endpoint) AS group_level,{_rollup_metric_select(table_name)}
+                     endpoint) AS group_level,{metric_select}
         FROM "{pg_table}"
         WHERE {where_clause} AND api_key IN (SELECT api_key FROM top_api_keys)
         GROUP BY GROUPING SETS (
@@ -882,7 +836,7 @@ def _build_top_api_keys_sql_query(
             (date, custom_llm_provider, api_key),
             (date, mcp_namespaced_tool_name, api_key),
             (date, endpoint, api_key)
-        )
+        ))
     """
 
     return sql_query, [*where_params, PTU_SENTINEL_API_KEY]
@@ -1432,17 +1386,15 @@ async def get_daily_activity_aggregated(
             timezone_offset_minutes=timezone_offset_minutes,
             include_current_utc_day=include_current_utc_day,
         )
-        key_free_sql, key_free_params = _build_aggregated_sql_query(**query_kwargs)
-        top_keys_sql, top_keys_params = _build_top_api_keys_sql_query(**query_kwargs)
+        sql_query, sql_params = _build_aggregated_sql_query(**query_kwargs)
         entity_query: Final = _build_entity_rollup_sql_query(**query_kwargs) if include_entity_breakdown else None
 
-        raw_key_free_rows, raw_top_key_rows, raw_entity_rows = await asyncio.gather(
-            prisma_client.db.query_raw(key_free_sql, *key_free_params),
-            prisma_client.db.query_raw(top_keys_sql, *top_keys_params),
+        raw_rows, raw_entity_rows = await asyncio.gather(
+            prisma_client.db.query_raw(sql_query, *sql_params),
             _query_raw_optional(prisma_client, entity_query),
         )
 
-        records: Final = [_GroupingSetsRow(**row) for row in (*(raw_key_free_rows or ()), *(raw_top_key_rows or ()))]
+        records: Final = [_GroupingSetsRow(**row) for row in (raw_rows or ())]
 
         # The grouping-sets dispatcher places each row directly in its bucket
         # using the row's GROUPING() bitmask. No Python-side summing needed.
diff --git a/tests/test_litellm/proxy/management_endpoints/test_common_daily_activity.py b/tests/test_litellm/proxy/management_endpoints/test_common_daily_activity.py
index dec98a1da27..5ff3f89343b 100644
--- a/tests/test_litellm/proxy/management_endpoints/test_common_daily_activity.py
+++ b/tests/test_litellm/proxy/management_endpoints/test_common_daily_activity.py
@@ -18,7 +18,6 @@ from litellm.proxy.management_endpoints.common_daily_activity import (
     _adjust_dates_for_timezone,
     _build_aggregated_sql_query,
     _build_entity_rollup_sql_query,
-    _build_top_api_keys_sql_query,
     _is_user_agent_tag,
     _record_to_spend_metrics,
     get_api_key_metadata,
@@ -166,7 +165,7 @@ async def test_get_daily_activity_aggregated_with_endpoint_breakdown():
         "autorouter_savings_spend": 0.0,
         "failed_requests": 0,
     }
-    key_free_rows = [
+    mock_rows = [
         # (date, endpoint) — rolls up across api_keys and models
         {
             **base,
@@ -218,8 +217,6 @@ async def test_get_daily_activity_aggregated_with_endpoint_breakdown():
             "api_requests": 3,
             "successful_requests": 3,
         },
-    ]
-    top_key_rows = [
         # (date, endpoint, api_key) — populates the per-key sub-bucket
         {
             **base,
@@ -247,7 +244,7 @@ async def test_get_daily_activity_aggregated_with_endpoint_breakdown():
         },
     ]
 
-    mock_prisma.db.query_raw = AsyncMock(side_effect=[key_free_rows, top_key_rows])
+    mock_prisma.db.query_raw = AsyncMock(return_value=mock_rows)
     mock_prisma.db.litellm_verificationtoken = MagicMock()
     mock_prisma.db.litellm_verificationtoken.find_many = AsyncMock(return_value=[])
 
@@ -293,11 +290,8 @@ async def test_get_daily_activity_aggregated_with_endpoint_breakdown():
     assert "key-2" in embeddings_endpoint.api_key_breakdown
     assert embeddings_endpoint.api_key_breakdown["key-2"].metrics.spend == 3.0
 
-    # One key-free rollup query plus one bounded per-key query, no find_many
-    assert mock_prisma.db.query_raw.call_count == 2
-    key_free_sql, top_keys_sql = (call.args[0] for call in mock_prisma.db.query_raw.call_args_list)
-    assert "top_api_keys" not in key_free_sql
-    assert "WITH top_api_keys AS" in top_keys_sql
+    # Verify query_raw was called (not find_many)
+    mock_prisma.db.query_raw.assert_called_once()
 
 
 @pytest.mark.asyncio
@@ -484,9 +478,7 @@ async def test_get_api_key_metadata_recovers_double_hashed_key_via_reverse_hash(
         return_value=[SimpleNamespace(user_id="alice", user_email="alice@example.com")]
     )
     mock_prisma.db.query_raw = AsyncMock(
-        return_value=[
-            {"digest": double_hashed, "key_alias": "batch-worker", "team_id": "team-1", "user_id": "alice"}
-        ]
+        return_value=[{"digest": double_hashed, "key_alias": "batch-worker", "team_id": "team-1", "user_id": "alice"}]
     )
 
     result = await get_api_key_metadata(
@@ -824,7 +816,7 @@ async def test_aggregated_activity_preserves_metadata_for_deleted_keys():
         "autorouter_savings_spend": 0.0,
         "failed_requests": 0,
     }
-    key_free_rows = [
+    mock_rows = [
         {
             **base,
             "date": "2024-01-01",
@@ -837,8 +829,6 @@ async def test_aggregated_activity_preserves_metadata_for_deleted_keys():
             "api_requests": 1,
             "successful_requests": 1,
         },
-    ]
-    top_key_rows = [
         {
             **base,
             "date": "2024-01-01",
@@ -853,7 +843,7 @@ async def test_aggregated_activity_preserves_metadata_for_deleted_keys():
         },
     ]
 
-    mock_prisma.db.query_raw = AsyncMock(side_effect=[key_free_rows, top_key_rows])
+    mock_prisma.db.query_raw = AsyncMock(return_value=mock_rows)
 
     # Active table returns nothing for this key
     mock_prisma.db.litellm_verificationtoken = MagicMock()
@@ -1226,6 +1216,7 @@ class TestBuildAggregatedSqlQuery:
             "user-1",
             "bedrock/global.anthropic.claude-opus-4-8",
             "sk-test",
+            PTU_SENTINEL_API_KEY,
         ]
         assert "model = $4" in sql
         assert "api_key = $5" in sql
@@ -1259,9 +1250,9 @@ class TestBuildAggregatedSqlQuery:
         assert "(date, model_group)" not in normalized
         assert "COALESCE(model_group, model)" not in normalized
 
-    def test_key_free_query_never_groups_by_api_key(self):
-        """The main rollup query must not emit one row per key, that is what blew up
-        the query engine at 3k+ keys. Every grouping set stays key-free and api_key
+    def test_totals_arm_never_groups_by_api_key(self):
+        """The totals arm must not emit one row per key, that is what blew up the
+        query engine at 3k+ keys. Every grouping set there stays key-free and api_key
         is projected as a NULL literal so the dispatcher's row shape is unchanged."""
         sql, _ = _build_aggregated_sql_query(
             table_name="litellm_dailyuserspend",
@@ -1273,13 +1264,15 @@ class TestBuildAggregatedSqlQuery:
             api_key=None,
         )
 
-        normalized = " ".join(sql.split())
-        grouping_block = normalized.split("GROUP BY GROUPING SETS (", 1)[1]
+        totals_arm, _ = " ".join(sql.split()).split("UNION ALL")
+        grouping_block = totals_arm.split("GROUP BY GROUPING SETS (", 1)[1]
         assert "api_key" not in grouping_block
-        assert "NULL::text AS api_key" in normalized
+        assert "NULL::text AS api_key" in totals_arm
 
-    def test_top_api_keys_query_ranks_keys_deterministically_and_shares_filters(self):
-        sql, params = _build_top_api_keys_sql_query(
+    def test_per_key_arm_ranks_keys_deterministically_and_shares_filters(self):
+        """Both arms sit in one statement so totals and per-key rows come from the
+        same snapshot, and the per-key arm reuses the caller's filter params."""
+        sql, params = _build_aggregated_sql_query(
             table_name="litellm_dailyuserspend",
             entity_id_field="user_id",
             entity_id="user-1",
@@ -1290,25 +1283,20 @@ class TestBuildAggregatedSqlQuery:
             timezone_offset_minutes=-330,
         )
 
-        normalized = " ".join(sql.split())
-        assert f"ORDER BY SUM(spend) DESC, api_key LIMIT {USAGE_TOP_API_KEYS_LIMIT}" in normalized
-        assert "api_key IN (SELECT api_key FROM top_api_keys)" in normalized
-        assert "api_key <> $6" in normalized
-        grouping_block = normalized.split("GROUP BY GROUPING SETS (", 1)[1]
+        totals_arm, per_key_arm = " ".join(sql.split()).split("UNION ALL")
+        assert "top_api_keys" not in totals_arm
+        assert f"ORDER BY SUM(spend) DESC, api_key LIMIT {USAGE_TOP_API_KEYS_LIMIT}" in per_key_arm
+        assert "api_key IN (SELECT api_key FROM top_api_keys)" in per_key_arm
+        assert "api_key <> $6" in per_key_arm
+        assert per_key_arm.count("model = $4 AND api_key = $5") == 2
+        grouping_block = per_key_arm.split("GROUP BY GROUPING SETS (", 1)[1]
         assert grouping_block.count(", api_key)") == 6
         assert grouping_block.count("(date") == 6
-        assert params == [
-            "2026-05-29",
-            "2026-06-02",
-            "user-1",
-            "bedrock/global.anthropic.claude-opus-4-8",
-            "sk-test",
-            PTU_SENTINEL_API_KEY,
-        ]
+        assert params[-1] == PTU_SENTINEL_API_KEY
 
 
 class TestAggregatedEmptyEntityFilter:
-    _BUILDERS: Final = (_build_aggregated_sql_query, _build_top_api_keys_sql_query, _build_entity_rollup_sql_query)
+    _BUILDERS: Final = (_build_aggregated_sql_query, _build_entity_rollup_sql_query)
 
     @pytest.mark.parametrize("build", _BUILDERS)
     def test_empty_entity_list_emits_no_degenerate_in_clause(self, build):
@@ -1325,7 +1313,7 @@ class TestAggregatedEmptyEntityFilter:
         normalized = " ".join(sql.split())
         assert "IN ()" not in normalized
         assert '"team_id" IN' not in normalized
-        sentinel_params = [PTU_SENTINEL_API_KEY] if build is _build_top_api_keys_sql_query else []
+        sentinel_params = [PTU_SENTINEL_API_KEY] if build is _build_aggregated_sql_query else []
         assert params == ["2026-08-01", "2026-08-19", *sentinel_params]
 
     @pytest.mark.parametrize("build", _BUILDERS)
@@ -1357,7 +1345,7 @@ class TestAggregatedEmptyEntityFilter:
         normalized = " ".join(sql.split())
         assert '"team_id" IN ($3, $4)' in normalized
         assert "FALSE" not in normalized
-        sentinel_params = [PTU_SENTINEL_API_KEY] if build is _build_top_api_keys_sql_query else []
+        sentinel_params = [PTU_SENTINEL_API_KEY] if build is _build_aggregated_sql_query else []
         assert params == ["2026-08-01", "2026-08-19", "team-alpha", "team-beta", *sentinel_params]
 
 
@@ -1373,7 +1361,7 @@ async def test_get_daily_activity_aggregated_empty_result_set():
     mock_prisma = MagicMock()
     mock_prisma.db = MagicMock()
 
-    key_free_rows = [
+    mock_rows = [
         {
             "date": None,
             "api_key": None,
@@ -1398,7 +1386,7 @@ async def test_get_daily_activity_aggregated_empty_result_set():
             "failed_requests": None,
         }
     ]
-    mock_prisma.db.query_raw = AsyncMock(side_effect=[key_free_rows, []])
+    mock_prisma.db.query_raw = AsyncMock(return_value=mock_rows)
 
     result = await get_daily_activity_aggregated(
         prisma_client=mock_prisma,
@@ -1492,13 +1480,13 @@ def _psycopg_query_raw(conn: psycopg.Connection, row_counts: list[int]):
 async def test_get_daily_activity_aggregated_bounds_api_key_rollups(
     _aggregated_postgresql: psycopg.Connection,
 ):
-    """Run both GROUPING SETS queries against real Postgres with more keys than the cap.
+    """Run the GROUPING SETS statement against real Postgres with more keys than the cap.
 
     key-004 and key-005 tie on spend exactly at the USAGE_TOP_API_KEYS_LIMIT
     cutoff; the api_key tiebreaker must keep key-004 and drop key-005. The PTU
     sentinel outspends every key but must not take a slot. Excluded keys and the
     sentinel still count toward the totals and the model rollup, which come from
-    the key-free query.
+    the key-free arm.
     """
     n_keys: Final = USAGE_TOP_API_KEYS_LIMIT + 5
     key_rows: Final = [
@@ -1554,10 +1542,10 @@ async def test_get_daily_activity_aggregated_bounds_api_key_rollups(
         api_key=None,
     )
 
-    # Key-free query: (), (date), (date, model), (date, model_group), two providers,
+    # Key-free arm: (), (date), (date, model), (date, model_group), two providers,
     # one mcp NULL bucket, endpoint plus its NULL bucket = 9 rows regardless of key count.
-    # Top-key query: six per-key grouping sets, each capped at the limit.
-    assert row_counts == [9, 6 * USAGE_TOP_API_KEYS_LIMIT]
+    # Per-key arm: six per-key grouping sets, each capped at the limit.
+    assert row_counts == [9 + 6 * USAGE_TOP_API_KEYS_LIMIT]
 
     assert result.metadata.total_spend == pytest.approx(key_spend + 1000.0)
     assert result.metadata.total_api_requests == n_keys
@@ -1579,11 +1567,11 @@ async def test_get_daily_activity_aggregated_bounds_api_key_rollups(
 
 
 @pytest.mark.asyncio
-async def test_get_daily_activity_aggregated_explicit_api_key_filter_scopes_both_queries(
+async def test_get_daily_activity_aggregated_explicit_api_key_filter_scopes_both_arms(
     _aggregated_postgresql: psycopg.Connection,
 ):
     """An explicit api_key filter must scope the key-free totals and the per-key
-    rollups to that key alone, so the two result sets never disagree."""
+    rollups to that key alone, so the two arms never disagree."""
     rows: Final = [
         (
             f"row-{i}",
@@ -2358,7 +2346,7 @@ def test_entity_rollup_sql_query_and_api_key_list_filter():
         api_key=[],
     )
     assert "FALSE" in empty_sql
-    assert empty_params == ["2024-01-01", "2024-01-31"]
+    assert empty_params == ["2024-01-01", "2024-01-31", PTU_SENTINEL_API_KEY]
 
 
 @pytest.mark.asyncio
@@ -2393,8 +2381,8 @@ async def test_get_daily_activity_aggregated_with_entity_breakdown():
         {**base, "date": None, "group_level": 127, "spend": 18.0},
         {**base, "date": "2024-01-01", "group_level": 63, "spend": 18.0},
         {**base, "date": "2024-01-01", "model": "gpt-4o", "group_level": 47, "spend": 18.0},
+        {**base, "date": "2024-01-01", "api_key": "key-1", "group_level": 31, "spend": 12.0},
     ]
-    top_key_rows = [{**base, "date": "2024-01-01", "api_key": "key-1", "group_level": 31, "spend": 12.0}]
     entity_base = {
         key: value
         for key, value in base.items()
@@ -2421,7 +2409,7 @@ async def test_get_daily_activity_aggregated_with_entity_breakdown():
         },
     ]
 
-    mock_prisma.db.query_raw = AsyncMock(side_effect=[main_rows, top_key_rows, entity_rows])
+    mock_prisma.db.query_raw = AsyncMock(side_effect=[main_rows, entity_rows])
     mock_prisma.db.litellm_verificationtoken = MagicMock()
     mock_prisma.db.litellm_verificationtoken.find_many = AsyncMock(return_value=[])
 
@@ -2438,9 +2426,9 @@ async def test_get_daily_activity_aggregated_with_entity_breakdown():
         include_entity_breakdown=True,
     )
 
-    assert mock_prisma.db.query_raw.call_count == 3
+    assert mock_prisma.db.query_raw.call_count == 2
     main_sql = mock_prisma.db.query_raw.call_args_list[0][0][0]
-    entity_sql = mock_prisma.db.query_raw.call_args_list[2][0][0]
+    entity_sql = mock_prisma.db.query_raw.call_args_list[1][0][0]
     assert "entity_id" not in main_sql
     assert '"team_id" AS entity_id' in entity_sql
     assert '(date, "team_id"),' in entity_sql

From c3e937b84544902b2de41a2748def7803b8f3368 Mon Sep 17 00:00:00 2001
From: yassin <yassin@berri.ai>
Date: Tue, 15 Sep 2026 22:11:20 +0000
Subject: [PATCH 04/13] docs(proxy): describe the single UNION ALL aggregate
 statement in the endpoint docstring

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

diff --git a/litellm/proxy/management_endpoints/common_daily_activity.py b/litellm/proxy/management_endpoints/common_daily_activity.py
index 95a89460d90..8a3ba196ab2 100644
--- a/litellm/proxy/management_endpoints/common_daily_activity.py
+++ b/litellm/proxy/management_endpoints/common_daily_activity.py
@@ -1350,11 +1350,12 @@ async def get_daily_activity_aggregated(
 ) -> SpendAnalyticsPaginatedResponse:
     """Aggregated variant that returns the full result set (no pagination).
 
-    Runs two GROUPING SETS queries in parallel: a key-free one for totals and the
-    model/provider/mcp/endpoint rollups (row count independent of key cardinality)
-    and a bounded one for the per-key rollups of the top USAGE_TOP_API_KEYS_LIMIT
-    keys by spend. breakdown.api_keys and every api_key_breakdown therefore list at
-    most that many keys, while the totals and the key-free rollups cover every key.
+    Runs one GROUPING SETS statement with two UNION ALL arms: a key-free one for totals
+    and the model/provider/mcp/endpoint rollups (row count independent of key
+    cardinality) and a bounded one for the per-key rollups of the top
+    USAGE_TOP_API_KEYS_LIMIT keys by spend. breakdown.api_keys and every
+    api_key_breakdown therefore list at most that many keys, while the totals and the
+    key-free rollups cover every key.
 
     include_entity_breakdown runs a small companion rollup query and folds
     `breakdown.entities` onto the response, as entity-scoped views like Team Usage need.

From cfd83548b30cf0afdf9a5c9f77a573582dfa7256 Mon Sep 17 00:00:00 2001
From: yassin <yassin@berri.ai>
Date: Wed, 16 Sep 2026 09:04:37 +0000
Subject: [PATCH 05/13] refactor(proxy): drop narrating docstrings from the
 aggregated usage query path

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

diff --git a/litellm/proxy/management_endpoints/common_daily_activity.py b/litellm/proxy/management_endpoints/common_daily_activity.py
index cb81d57ac77..5f63f639a11 100644
--- a/litellm/proxy/management_endpoints/common_daily_activity.py
+++ b/litellm/proxy/management_endpoints/common_daily_activity.py
@@ -761,13 +761,6 @@ def _build_aggregated_sql_query(
 ) -> tuple[str, list[str]]:  # mutable-ok: SQL text plus its ordered $N params
     """Build the GROUPING SETS query for aggregated daily activity.
 
-    One statement, two UNION ALL arms over the same WHERE clause. The first arm is
-    key-free: grand total, per-date totals and the (date, model / model_group /
-    provider / mcp / endpoint) rollups, so its row count never grows with the number
-    of keys. The second arm emits the (date, <dimension>, api_key) rollups for the
-    USAGE_TOP_API_KEYS_LIMIT highest-spend keys only. Both arms share the 7-bit
-    group_level bitmask (date, api_key, model, model_group, provider, mcp, endpoint).
-
     Returns:
         Tuple of (sql_query, params_list) ready for prisma_client.db.query_raw().
     """
@@ -1366,13 +1359,6 @@ async def get_daily_activity_aggregated(
 ) -> SpendAnalyticsPaginatedResponse:
     """Aggregated variant that returns the full result set (no pagination).
 
-    Runs one GROUPING SETS statement with two UNION ALL arms: a key-free one for totals
-    and the model/provider/mcp/endpoint rollups (row count independent of key
-    cardinality) and a bounded one for the per-key rollups of the top
-    USAGE_TOP_API_KEYS_LIMIT keys by spend. breakdown.api_keys and every
-    api_key_breakdown therefore list at most that many keys, while the totals and the
-    key-free rollups cover every key.
-
     include_entity_breakdown runs a small companion rollup query and folds
     `breakdown.entities` onto the response, as entity-scoped views like Team Usage need.
 

From f863e746123bea7a6d0d1c730e68db35d8936854 Mon Sep 17 00:00:00 2001
From: yassin <yassin@berri.ai>
Date: Wed, 16 Sep 2026 09:22:20 +0000
Subject: [PATCH 06/13] test(proxy): assert aggregated usage behavior against
 Postgres instead of SQL text

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

diff --git a/tests/test_litellm/proxy/management_endpoints/test_common_daily_activity.py b/tests/test_litellm/proxy/management_endpoints/test_common_daily_activity.py
index 471cabbbb59..e1a4d0d02a8 100644
--- a/tests/test_litellm/proxy/management_endpoints/test_common_daily_activity.py
+++ b/tests/test_litellm/proxy/management_endpoints/test_common_daily_activity.py
@@ -1239,79 +1239,6 @@ class TestBuildAggregatedSqlQuery:
         assert "model = $4" in sql
         assert "api_key = $5" in sql
 
-    def test_model_group_rollups_fall_back_to_model_name(self):
-        """Aggregated model_groups rollups must fall back to model for group-less rows.
-
-        The (date, model_group) grouping level cannot recover the model column
-        after the fact (it is rolled up), so the fallback has to happen in SQL;
-        without it, group-less rows silently vanish from the model_groups
-        breakdown that the usage UI now renders by default. Group-less rows are
-        stored as empty strings, not NULL (spend_tracking_utils defaults
-        model_group to ""), so a plain COALESCE is not enough: the fallback must
-        be NULLIF-wrapped to catch both
-        """
-        sql, _ = _build_aggregated_sql_query(
-            table_name="litellm_dailyuserspend",
-            entity_id_field="user_id",
-            entity_id=None,
-            start_date="2026-07-01",
-            end_date="2026-07-01",
-            model=None,
-            api_key=None,
-        )
-
-        normalized = " ".join(sql.split())
-        fallback = "COALESCE(NULLIF(model_group, ''), model)"
-        assert f"{fallback} AS model_group" in normalized
-        assert f"GROUPING(model, {fallback}, custom_llm_provider, mcp_namespaced_tool_name, endpoint)" in normalized
-        assert f"(date, {fallback})," in normalized
-        assert "(date, model_group)" not in normalized
-        assert "COALESCE(model_group, model)" not in normalized
-
-    def test_totals_arm_never_groups_by_api_key(self):
-        """The totals arm must not emit one row per key, that is what blew up the
-        query engine at 3k+ keys. Every grouping set there stays key-free and api_key
-        is projected as a NULL literal so the dispatcher's row shape is unchanged."""
-        sql, _ = _build_aggregated_sql_query(
-            table_name="litellm_dailyuserspend",
-            entity_id_field="user_id",
-            entity_id=None,
-            start_date="2026-07-01",
-            end_date="2026-07-01",
-            model=None,
-            api_key=None,
-        )
-
-        totals_arm, _ = " ".join(sql.split()).split("UNION ALL")
-        grouping_block = totals_arm.split("GROUP BY GROUPING SETS (", 1)[1]
-        assert "api_key" not in grouping_block
-        assert "NULL::text AS api_key" in totals_arm
-
-    def test_per_key_arm_ranks_keys_deterministically_and_shares_filters(self):
-        """Both arms sit in one statement so totals and per-key rows come from the
-        same snapshot, and the per-key arm reuses the caller's filter params."""
-        sql, params = _build_aggregated_sql_query(
-            table_name="litellm_dailyuserspend",
-            entity_id_field="user_id",
-            entity_id="user-1",
-            start_date="2026-05-29",
-            end_date="2026-06-02",
-            model="bedrock/global.anthropic.claude-opus-4-8",
-            api_key="sk-test",
-            timezone_offset_minutes=-330,
-        )
-
-        totals_arm, per_key_arm = " ".join(sql.split()).split("UNION ALL")
-        assert "top_api_keys" not in totals_arm
-        assert f"ORDER BY SUM(spend) DESC, api_key LIMIT {USAGE_TOP_API_KEYS_LIMIT}" in per_key_arm
-        assert "api_key IN (SELECT api_key FROM top_api_keys)" in per_key_arm
-        assert "api_key <> $6" in per_key_arm
-        assert per_key_arm.count("model = $4 AND api_key = $5") == 2
-        grouping_block = per_key_arm.split("GROUP BY GROUPING SETS (", 1)[1]
-        assert grouping_block.count(", api_key)") == 6
-        assert grouping_block.count("(date") == 6
-        assert params[-1] == PTU_SENTINEL_API_KEY
-
 
 class TestAggregatedEmptyEntityFilter:
     _BUILDERS: Final = (_build_aggregated_sql_query, _build_entity_rollup_sql_query)
@@ -1640,6 +1567,47 @@ async def test_get_daily_activity_aggregated_explicit_api_key_filter_scopes_both
     assert set(day.breakdown.models["gpt-5"].api_key_breakdown) == {"key-1"}
 
 
+@pytest.mark.asyncio
+async def test_get_daily_activity_aggregated_model_group_rollups_fall_back_to_model_name(
+    _aggregated_postgresql: psycopg.Connection,
+):
+    """Rows stored with an empty or NULL model_group must land in the model_groups
+    breakdown under their model name instead of vanishing from the usage UI."""
+    rows: Final = [
+        ("row-0", "user-0", "2026-06-01", "key-0", "gpt-5", "gpt-5-eu", "openai", "/v1/chat/completions", 10, 7.0, 1, 1),
+        ("row-1", "user-1", "2026-06-01", "key-1", "gpt-5", "", "openai", "/v1/chat/completions", 10, 3.0, 1, 1),
+        ("row-2", "user-2", "2026-06-01", "key-2", "claude-x", None, "anthropic", "/v1/messages", 10, 2.0, 1, 1),
+    ]
+    _seed_daily_user_spend(_aggregated_postgresql, rows)
+
+    mock_prisma = MagicMock()
+    mock_prisma.db = MagicMock()
+    mock_prisma.db.query_raw = _psycopg_query_raw(_aggregated_postgresql, [])
+    mock_prisma.db.litellm_verificationtoken.find_many = AsyncMock(return_value=[])
+    mock_prisma.db.litellm_deletedverificationtoken.find_many = AsyncMock(return_value=[])
+
+    result = await get_daily_activity_aggregated(
+        prisma_client=mock_prisma,
+        table_name="litellm_dailyuserspend",
+        entity_id_field="user_id",
+        entity_id=None,
+        entity_metadata_field=None,
+        start_date="2026-06-01",
+        end_date="2026-06-01",
+        model=None,
+        api_key=None,
+    )
+
+    breakdown: Final = result.results[0].breakdown
+    assert set(breakdown.model_groups) == {"gpt-5-eu", "gpt-5", "claude-x"}
+    assert breakdown.model_groups["gpt-5-eu"].metrics.spend == 7.0
+    assert breakdown.model_groups["gpt-5"].metrics.spend == 3.0
+    assert breakdown.model_groups["claude-x"].metrics.spend == 2.0
+    assert set(breakdown.model_groups["gpt-5"].api_key_breakdown) == {"key-1"}
+    assert set(breakdown.models) == {"gpt-5", "claude-x"}
+    assert breakdown.models["gpt-5"].metrics.spend == 10.0
+
+
 def _no_spend_record():
     """A rollup row for a key with no spend, where SUM() returns NULL (None)."""
     return SimpleNamespace(

From 61b3611b8c6667c8eae5dadc6036a6d95e897d04 Mon Sep 17 00:00:00 2001
From: yassin <yassin@berri.ai>
Date: Wed, 16 Sep 2026 09:22:20 +0000
Subject: [PATCH 07/13] fix(ui): block the global usage export when the
 aggregated key cap is reached

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../components/EntityUsage/EntityUsage.tsx    |  2 +-
 .../_components/components/UsagePageView.tsx  |  3 +-
 .../exportBlockedReason.test.ts               | 37 ++++++++++++++++++-
 .../EntityUsageExport/exportBlockedReason.ts  | 18 ++++++++-
 4 files changed, 56 insertions(+), 4 deletions(-)

diff --git a/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/EntityUsage/EntityUsage.tsx b/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/EntityUsage/EntityUsage.tsx
index 6687bd4df03..27a4163dff7 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/EntityUsage/EntityUsage.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/EntityUsage/EntityUsage.tsx
@@ -664,7 +664,7 @@ const EntityUsage: React.FC<EntityUsageProps> = ({
     { key: "endpoints", label: "Endpoint Activity", content: <EndpointUsage userSpendData={spendData} /> },
   ];
 
-  const spendFetchState = { coversRange, cancelled, failed };
+  const spendFetchState = { coversRange, cancelled, failed, apiKeyLimitReached: undefined };
 
   return (
     <div style={{ width: "100%" }} className="relative">
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/UsagePageView.tsx b/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/UsagePageView.tsx
index 691c5dc839a..48322477fb4 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/UsagePageView.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/UsagePageView.tsx
@@ -30,7 +30,7 @@ import { ActivityMetrics, processActivityData } from "@/components/activity_metr
 import CloudZeroExportModal from "@/components/cloudzero_export_modal";
 import UserDropdown from "@/components/common_components/UserDropdown";
 import EntityUsageExportModal from "@/components/EntityUsageExport";
-import { getExportBlockedReason } from "@/components/EntityUsageExport/exportBlockedReason";
+import { getApiKeyLimitReached, getExportBlockedReason } from "@/components/EntityUsageExport/exportBlockedReason";
 import KeyActivityPanel from "@/components/UsagePage/components/KeyActivityPanel";
 import { Team } from "@/components/key_team_helpers/key_list";
 import {
@@ -256,6 +256,7 @@ const UsagePage: React.FC<UsagePageProps> = ({ teams, organizations }) => {
     coversRange: activeAggregated !== null || paginatedResult.coversRange,
     cancelled: paginatedResult.cancelled,
     failed: paginatedResult.failed,
+    apiKeyLimitReached: getApiKeyLimitReached(userSpendData.results, userSpendData.metadata?.api_key_limit),
   };
   const exportBlockedReason = getExportBlockedReason(spendFetchState);
 
diff --git a/ui/litellm-dashboard/src/components/EntityUsageExport/exportBlockedReason.test.ts b/ui/litellm-dashboard/src/components/EntityUsageExport/exportBlockedReason.test.ts
index e39b01a5dea..86783e2e4a0 100644
--- a/ui/litellm-dashboard/src/components/EntityUsageExport/exportBlockedReason.test.ts
+++ b/ui/litellm-dashboard/src/components/EntityUsageExport/exportBlockedReason.test.ts
@@ -1,14 +1,24 @@
 import { describe, expect, it } from "vitest";
 
-import { getExportBlockedReason, type UsageFetchState } from "./exportBlockedReason";
+import type { DailyData } from "@/components/UsagePage/types";
+
+import { getApiKeyLimitReached, getExportBlockedReason, type UsageFetchState } from "./exportBlockedReason";
 
 const state = (overrides: Partial<UsageFetchState> = {}): UsageFetchState => ({
   coversRange: true,
   cancelled: false,
   failed: false,
+  apiKeyLimitReached: undefined,
   ...overrides,
 });
 
+const dayWithKeys = (date: string, ...keys: string[]): DailyData =>
+  ({
+    date,
+    metrics: {},
+    breakdown: { api_keys: Object.fromEntries(keys.map((k) => [k, { metrics: {}, metadata: {} }])) },
+  }) as unknown as DailyData;
+
 describe("getExportBlockedReason", () => {
   it("lets the export through once the data on screen covers the range", () => {
     expect(getExportBlockedReason(state())).toBeUndefined();
@@ -31,4 +41,29 @@ describe("getExportBlockedReason", () => {
     expect(reason).toMatch(/failed to load/i);
     expect(reason).not.toMatch(/stopped/i);
   });
+
+  it("blocks when the aggregated endpoint hit its key cap, since a per-team CSV would miss keys", () => {
+    const reason = getExportBlockedReason(state({ apiKeyLimitReached: 100 }));
+
+    expect(reason).toMatch(/100 highest-spend keys/);
+    expect(reason).toMatch(/USAGE_TOP_API_KEYS_LIMIT/);
+  });
+});
+
+describe("getApiKeyLimitReached", () => {
+  it("reports the cap once the distinct keys across every day reach it", () => {
+    const results = [dayWithKeys("2026-06-01", "key-1", "key-2"), dayWithKeys("2026-06-02", "key-2", "key-3")];
+
+    expect(getApiKeyLimitReached(results, 3)).toBe(3);
+  });
+
+  it("stays quiet while fewer keys than the cap came back, which means every key is on screen", () => {
+    const results = [dayWithKeys("2026-06-01", "key-1", "key-2"), dayWithKeys("2026-06-02", "key-2")];
+
+    expect(getApiKeyLimitReached(results, 3)).toBeUndefined();
+  });
+
+  it("stays quiet when the response carries no cap, as the paginated fallback does", () => {
+    expect(getApiKeyLimitReached([dayWithKeys("2026-06-01", "key-1")], undefined)).toBeUndefined();
+  });
 });
diff --git a/ui/litellm-dashboard/src/components/EntityUsageExport/exportBlockedReason.ts b/ui/litellm-dashboard/src/components/EntityUsageExport/exportBlockedReason.ts
index 71408ba8f3f..ca756090351 100644
--- a/ui/litellm-dashboard/src/components/EntityUsageExport/exportBlockedReason.ts
+++ b/ui/litellm-dashboard/src/components/EntityUsageExport/exportBlockedReason.ts
@@ -1,13 +1,29 @@
+import type { DailyData } from "@/components/UsagePage/types";
+
 export interface UsageFetchState {
   coversRange: boolean;
   cancelled: boolean;
   failed: boolean;
+  apiKeyLimitReached: number | undefined;
 }
 
-export const getExportBlockedReason = ({ coversRange, cancelled, failed }: UsageFetchState): string | undefined => {
+export const getApiKeyLimitReached = (results: DailyData[], apiKeyLimit: unknown): number | undefined => {
+  if (typeof apiKeyLimit !== "number") return undefined;
+  const keys = new Set(results.flatMap((day) => Object.keys(day.breakdown.api_keys ?? {})));
+  return keys.size >= apiKeyLimit ? apiKeyLimit : undefined;
+};
+
+export const getExportBlockedReason = ({
+  coversRange,
+  cancelled,
+  failed,
+  apiKeyLimitReached,
+}: UsageFetchState): string | undefined => {
   if (failed) return "Some spend data failed to load, so an export would under-report. Reload the page to try again.";
   if (cancelled)
     return "Loading was stopped before the whole range arrived, so an export would under-report. Reload the page to load it all.";
   if (!coversRange) return "Spend data is still loading, so an export would under-report. Wait for it to finish.";
+  if (apiKeyLimitReached !== undefined)
+    return `Only the ${apiKeyLimitReached} highest-spend keys were loaded, so a per-team export would under-report. Raise USAGE_TOP_API_KEYS_LIMIT on the proxy to load more keys.`;
   return undefined;
 };

From aec36a2bac12222a681f6552103b6899657abc04 Mon Sep 17 00:00:00 2001
From: yassin <yassin@berri.ai>
Date: Wed, 16 Sep 2026 09:36:13 +0000
Subject: [PATCH 08/13] style(proxy): drop em dash from api_key bit comment

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/proxy/management_endpoints/common_daily_activity.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/litellm/proxy/management_endpoints/common_daily_activity.py b/litellm/proxy/management_endpoints/common_daily_activity.py
index 5f63f639a11..93e6e60c77c 100644
--- a/litellm/proxy/management_endpoints/common_daily_activity.py
+++ b/litellm/proxy/management_endpoints/common_daily_activity.py
@@ -991,7 +991,7 @@ async def _aggregate_spend_records(
 # current grouping set's key), 0 when the column is part of the key.
 _GROUP_GRAND_TOTAL: Final = 127  # 0b1111111 — all rolled up
 _GROUP_DATE: Final = 63  # 0b0111111 — only date kept
-_API_KEY_ROLLED_UP_BIT: Final = 32  # 0b0100000 — api_key position in the 7-bit mask
+_API_KEY_ROLLED_UP_BIT: Final = 32  # 0b0100000
 _GROUP_DATE_API_KEY: Final = 31  # 0b0011111
 _GROUP_DATE_MODEL: Final = 47  # 0b0101111
 _GROUP_DATE_MODEL_API_KEY: Final = 15  # 0b0001111

From 87894f2e7f343a75cc6d4f0977deceb0d564dde9 Mon Sep 17 00:00:00 2001
From: yassin <yassin@berri.ai>
Date: Wed, 16 Sep 2026 10:02:11 +0000
Subject: [PATCH 09/13] fix(proxy): report total_api_keys so exact-limit key
 sets are not treated as truncated

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/proxy/_lazy_openapi_snapshot.json     | 12 ++++
 .../common_daily_activity.py                  | 15 ++--
 .../common_daily_activity.py                  |  5 ++
 .../test_common_daily_activity.py             | 68 +++++++++++++++++--
 .../components/EntityUsage/EntityUsage.tsx    |  2 +-
 .../_components/components/UsagePageView.tsx  |  7 +-
 .../exportBlockedReason.test.ts               | 37 ++++------
 .../EntityUsageExport/exportBlockedReason.ts  | 20 +++---
 ui/litellm-dashboard/src/lib/http/schema.d.ts |  5 ++
 9 files changed, 126 insertions(+), 45 deletions(-)

diff --git a/litellm/proxy/_lazy_openapi_snapshot.json b/litellm/proxy/_lazy_openapi_snapshot.json
index 5ff35747779..fb82a540761 100644
--- a/litellm/proxy/_lazy_openapi_snapshot.json
+++ b/litellm/proxy/_lazy_openapi_snapshot.json
@@ -3072,6 +3072,18 @@
               "title": "Page",
               "type": "integer"
             },
+            "total_api_keys": {
+              "anyOf": [
+                {
+                  "type": "integer"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Distinct API keys matching the filters. When this exceeds api_key_limit, the per-key lists are truncated to the highest-spend keys.",
+              "title": "Total Api Keys"
+            },
             "total_api_requests": {
               "default": 0,
               "title": "Total Api Requests",
diff --git a/litellm/proxy/management_endpoints/common_daily_activity.py b/litellm/proxy/management_endpoints/common_daily_activity.py
index 93e6e60c77c..a36b6052981 100644
--- a/litellm/proxy/management_endpoints/common_daily_activity.py
+++ b/litellm/proxy/management_endpoints/common_daily_activity.py
@@ -155,6 +155,7 @@ class _GroupingSetsRow(SimpleNamespace):
     mcp_namespaced_tool_name: str | None
     endpoint: str | None
     group_level: int
+    distinct_api_keys: int | None
     spend: float | None
     prompt_tokens: int | None
     completion_tokens: int | None
@@ -800,7 +801,8 @@ def _build_aggregated_sql_query(
             (GROUPING(date) << 6) | {_API_KEY_ROLLED_UP_BIT}
                 | GROUPING(model, {_MODEL_GROUP_EXPR},
                            custom_llm_provider, mcp_namespaced_tool_name,
-                           endpoint) AS group_level,{metric_select}
+                           endpoint) AS group_level,
+            NULL::bigint AS distinct_api_keys,{metric_select}
         FROM "{pg_table}"
         WHERE {where_clause}
         GROUP BY GROUPING SETS (
@@ -814,7 +816,7 @@ def _build_aggregated_sql_query(
         ))
         UNION ALL
         (WITH top_api_keys AS (
-            SELECT api_key
+            SELECT api_key, COUNT(*) OVER () AS distinct_api_keys
             FROM "{pg_table}"
             WHERE {where_clause} AND api_key <> {sentinel_param}
             GROUP BY api_key
@@ -831,9 +833,10 @@ def _build_aggregated_sql_query(
             endpoint,
             GROUPING(date, api_key, model, {_MODEL_GROUP_EXPR},
                      custom_llm_provider, mcp_namespaced_tool_name,
-                     endpoint) AS group_level,{metric_select}
-        FROM "{pg_table}"
-        WHERE {where_clause} AND api_key IN (SELECT api_key FROM top_api_keys)
+                     endpoint) AS group_level,
+            MAX(top_api_keys.distinct_api_keys) AS distinct_api_keys,{metric_select}
+        FROM "{pg_table}" JOIN top_api_keys USING (api_key)
+        WHERE {where_clause}
         GROUP BY GROUPING SETS (
             (date, api_key),
             (date, model, api_key),
@@ -1398,6 +1401,7 @@ async def get_daily_activity_aggregated(
         )
 
         records: Final = [_GroupingSetsRow(**row) for row in (raw_rows or ())]
+        total_api_keys: Final = next((r.distinct_api_keys for r in records if r.distinct_api_keys is not None), 0)
 
         # The grouping-sets dispatcher places each row directly in its bucket
         # using the row's GROUPING() bitmask. No Python-side summing needed.
@@ -1452,6 +1456,7 @@ async def get_daily_activity_aggregated(
                 total_pages=1,
                 has_more=False,
                 api_key_limit=USAGE_TOP_API_KEYS_LIMIT,
+                total_api_keys=total_api_keys,
             ),
         )
 
diff --git a/litellm/types/proxy/management_endpoints/common_daily_activity.py b/litellm/types/proxy/management_endpoints/common_daily_activity.py
index 2893eb30b3c..5d42b1230a0 100644
--- a/litellm/types/proxy/management_endpoints/common_daily_activity.py
+++ b/litellm/types/proxy/management_endpoints/common_daily_activity.py
@@ -105,6 +105,11 @@ class DailySpendMetadata(BaseModel):
         description="When set, api_keys and every api_key_breakdown list at most this many keys, "
         "ranked by spend. Totals and the model, provider, mcp and endpoint rollups still cover every key.",
     )
+    total_api_keys: int | None = Field(
+        default=None,
+        description="Distinct API keys matching the filters. When this exceeds api_key_limit, the per-key "
+        "lists are truncated to the highest-spend keys.",
+    )
 
 
 class SpendAnalyticsPaginatedResponse(BaseModel):
diff --git a/tests/test_litellm/proxy/management_endpoints/test_common_daily_activity.py b/tests/test_litellm/proxy/management_endpoints/test_common_daily_activity.py
index e1a4d0d02a8..e7f8bcc7e4f 100644
--- a/tests/test_litellm/proxy/management_endpoints/test_common_daily_activity.py
+++ b/tests/test_litellm/proxy/management_endpoints/test_common_daily_activity.py
@@ -175,6 +175,7 @@ async def test_get_daily_activity_aggregated_with_endpoint_breakdown():
             "endpoint": "/v1/chat/completions",
             "api_key": None,
             "group_level": 62,
+            "distinct_api_keys": None,
             "spend": 15.0,
             "prompt_tokens": 150,
             "completion_tokens": 75,
@@ -187,6 +188,7 @@ async def test_get_daily_activity_aggregated_with_endpoint_breakdown():
             "endpoint": "/v1/embeddings",
             "api_key": None,
             "group_level": 62,
+            "distinct_api_keys": None,
             "spend": 3.0,
             "prompt_tokens": 30,
             "completion_tokens": 0,
@@ -200,6 +202,7 @@ async def test_get_daily_activity_aggregated_with_endpoint_breakdown():
             "endpoint": None,
             "api_key": None,
             "group_level": 63,
+            "distinct_api_keys": None,
             "spend": 18.0,
             "prompt_tokens": 180,
             "completion_tokens": 75,
@@ -213,6 +216,7 @@ async def test_get_daily_activity_aggregated_with_endpoint_breakdown():
             "endpoint": None,
             "api_key": None,
             "group_level": 127,
+            "distinct_api_keys": None,
             "spend": 18.0,
             "prompt_tokens": 180,
             "completion_tokens": 75,
@@ -226,6 +230,7 @@ async def test_get_daily_activity_aggregated_with_endpoint_breakdown():
             "endpoint": "/v1/chat/completions",
             "api_key": "key-1",
             "group_level": 30,
+            "distinct_api_keys": 2,
             "spend": 15.0,
             "prompt_tokens": 150,
             "completion_tokens": 75,
@@ -238,6 +243,7 @@ async def test_get_daily_activity_aggregated_with_endpoint_breakdown():
             "endpoint": "/v1/embeddings",
             "api_key": "key-2",
             "group_level": 30,
+            "distinct_api_keys": 2,
             "spend": 3.0,
             "prompt_tokens": 30,
             "completion_tokens": 0,
@@ -839,6 +845,7 @@ async def test_aggregated_activity_preserves_metadata_for_deleted_keys():
             "endpoint": "/v1/chat/completions",
             "api_key": None,
             "group_level": 62,
+            "distinct_api_keys": None,
             "spend": 10.0,
             "prompt_tokens": 100,
             "completion_tokens": 50,
@@ -851,6 +858,7 @@ async def test_aggregated_activity_preserves_metadata_for_deleted_keys():
             "endpoint": "/v1/chat/completions",
             "api_key": "deleted-key-hash",
             "group_level": 30,
+            "distinct_api_keys": 1,
             "spend": 10.0,
             "prompt_tokens": 100,
             "completion_tokens": 50,
@@ -1316,6 +1324,7 @@ async def test_get_daily_activity_aggregated_empty_result_set():
             "mcp_namespaced_tool_name": None,
             "endpoint": None,
             "group_level": 127,
+            "distinct_api_keys": None,
             "spend": None,
             "prompt_tokens": None,
             "completion_tokens": None,
@@ -1499,6 +1508,7 @@ async def test_get_daily_activity_aggregated_bounds_api_key_rollups(
     assert result.metadata.total_spend == pytest.approx(key_spend + 1000.0)
     assert result.metadata.total_api_requests == n_keys
     assert result.metadata.api_key_limit == USAGE_TOP_API_KEYS_LIMIT
+    assert result.metadata.total_api_keys == n_keys
 
     expected_top: Final = {f"key-{i:03d}" for i in range(6, n_keys)} | {"key-004"}
     day: Final = result.results[0]
@@ -1560,6 +1570,7 @@ async def test_get_daily_activity_aggregated_explicit_api_key_filter_scopes_both
     )
 
     assert result.metadata.total_spend == 2.0
+    assert result.metadata.total_api_keys == 1
     day: Final = result.results[0]
     assert set(day.breakdown.api_keys) == {"key-1"}
     assert day.breakdown.api_keys["key-1"].metrics.spend == 2.0
@@ -1567,6 +1578,55 @@ async def test_get_daily_activity_aggregated_explicit_api_key_filter_scopes_both
     assert set(day.breakdown.models["gpt-5"].api_key_breakdown) == {"key-1"}
 
 
+@pytest.mark.asyncio
+async def test_get_daily_activity_aggregated_reports_exact_limit_key_count_as_complete(
+    _aggregated_postgresql: psycopg.Connection,
+):
+    """With exactly USAGE_TOP_API_KEYS_LIMIT keys nothing is dropped, and the
+    response must say so: total_api_keys equals the limit rather than exceeding it."""
+    rows: Final = [
+        (
+            f"row-{i:03d}",
+            f"user-{i:03d}",
+            "2026-06-01",
+            f"key-{i:03d}",
+            "gpt-5",
+            "",
+            "openai",
+            "/v1/chat/completions",
+            10,
+            float(i + 1),
+            1,
+            1,
+        )
+        for i in range(USAGE_TOP_API_KEYS_LIMIT)
+    ]
+    _seed_daily_user_spend(_aggregated_postgresql, rows)
+
+    row_counts: Final[list[int]] = []  # mutable-ok: out-param for the query_raw shim
+    mock_prisma = MagicMock()
+    mock_prisma.db = MagicMock()
+    mock_prisma.db.query_raw = _psycopg_query_raw(_aggregated_postgresql, row_counts)
+    mock_prisma.db.litellm_verificationtoken.find_many = AsyncMock(return_value=[])
+    mock_prisma.db.litellm_deletedverificationtoken.find_many = AsyncMock(return_value=[])
+
+    result = await get_daily_activity_aggregated(
+        prisma_client=mock_prisma,
+        table_name="litellm_dailyuserspend",
+        entity_id_field="user_id",
+        entity_id=None,
+        entity_metadata_field=None,
+        start_date="2026-06-01",
+        end_date="2026-06-01",
+        model=None,
+        api_key=None,
+    )
+
+    assert result.metadata.total_api_keys == USAGE_TOP_API_KEYS_LIMIT
+    assert result.metadata.api_key_limit == USAGE_TOP_API_KEYS_LIMIT
+    assert len(result.results[0].breakdown.api_keys) == USAGE_TOP_API_KEYS_LIMIT
+
+
 @pytest.mark.asyncio
 async def test_get_daily_activity_aggregated_model_group_rollups_fall_back_to_model_name(
     _aggregated_postgresql: psycopg.Connection,
@@ -2427,10 +2487,10 @@ async def test_get_daily_activity_aggregated_with_entity_breakdown():
         "successful_requests": 0,
     }
     main_rows = [
-        {**base, "date": None, "group_level": 127, "spend": 18.0},
-        {**base, "date": "2024-01-01", "group_level": 63, "spend": 18.0},
-        {**base, "date": "2024-01-01", "model": "gpt-4o", "group_level": 47, "spend": 18.0},
-        {**base, "date": "2024-01-01", "api_key": "key-1", "group_level": 31, "spend": 12.0},
+        {**base, "date": None, "group_level": 127, "distinct_api_keys": None, "spend": 18.0},
+        {**base, "date": "2024-01-01", "group_level": 63, "distinct_api_keys": None, "spend": 18.0},
+        {**base, "date": "2024-01-01", "model": "gpt-4o", "group_level": 47, "distinct_api_keys": None, "spend": 18.0},
+        {**base, "date": "2024-01-01", "api_key": "key-1", "group_level": 31, "distinct_api_keys": 1, "spend": 12.0},
     ]
     entity_base = {
         key: value
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/EntityUsage/EntityUsage.tsx b/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/EntityUsage/EntityUsage.tsx
index 27a4163dff7..001fee4b7bc 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/EntityUsage/EntityUsage.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/EntityUsage/EntityUsage.tsx
@@ -664,7 +664,7 @@ const EntityUsage: React.FC<EntityUsageProps> = ({
     { key: "endpoints", label: "Endpoint Activity", content: <EndpointUsage userSpendData={spendData} /> },
   ];
 
-  const spendFetchState = { coversRange, cancelled, failed, apiKeyLimitReached: undefined };
+  const spendFetchState = { coversRange, cancelled, failed, apiKeyTruncation: undefined };
 
   return (
     <div style={{ width: "100%" }} className="relative">
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/UsagePageView.tsx b/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/UsagePageView.tsx
index 48322477fb4..3a97e54edfc 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/UsagePageView.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/UsagePageView.tsx
@@ -30,7 +30,7 @@ import { ActivityMetrics, processActivityData } from "@/components/activity_metr
 import CloudZeroExportModal from "@/components/cloudzero_export_modal";
 import UserDropdown from "@/components/common_components/UserDropdown";
 import EntityUsageExportModal from "@/components/EntityUsageExport";
-import { getApiKeyLimitReached, getExportBlockedReason } from "@/components/EntityUsageExport/exportBlockedReason";
+import { getApiKeyTruncation, getExportBlockedReason } from "@/components/EntityUsageExport/exportBlockedReason";
 import KeyActivityPanel from "@/components/UsagePage/components/KeyActivityPanel";
 import { Team } from "@/components/key_team_helpers/key_list";
 import {
@@ -256,7 +256,10 @@ const UsagePage: React.FC<UsagePageProps> = ({ teams, organizations }) => {
     coversRange: activeAggregated !== null || paginatedResult.coversRange,
     cancelled: paginatedResult.cancelled,
     failed: paginatedResult.failed,
-    apiKeyLimitReached: getApiKeyLimitReached(userSpendData.results, userSpendData.metadata?.api_key_limit),
+    apiKeyTruncation: getApiKeyTruncation(
+      userSpendData.metadata?.api_key_limit,
+      userSpendData.metadata?.total_api_keys,
+    ),
   };
   const exportBlockedReason = getExportBlockedReason(spendFetchState);
 
diff --git a/ui/litellm-dashboard/src/components/EntityUsageExport/exportBlockedReason.test.ts b/ui/litellm-dashboard/src/components/EntityUsageExport/exportBlockedReason.test.ts
index 86783e2e4a0..8491b31f5f9 100644
--- a/ui/litellm-dashboard/src/components/EntityUsageExport/exportBlockedReason.test.ts
+++ b/ui/litellm-dashboard/src/components/EntityUsageExport/exportBlockedReason.test.ts
@@ -1,24 +1,15 @@
 import { describe, expect, it } from "vitest";
 
-import type { DailyData } from "@/components/UsagePage/types";
-
-import { getApiKeyLimitReached, getExportBlockedReason, type UsageFetchState } from "./exportBlockedReason";
+import { getApiKeyTruncation, getExportBlockedReason, type UsageFetchState } from "./exportBlockedReason";
 
 const state = (overrides: Partial<UsageFetchState> = {}): UsageFetchState => ({
   coversRange: true,
   cancelled: false,
   failed: false,
-  apiKeyLimitReached: undefined,
+  apiKeyTruncation: undefined,
   ...overrides,
 });
 
-const dayWithKeys = (date: string, ...keys: string[]): DailyData =>
-  ({
-    date,
-    metrics: {},
-    breakdown: { api_keys: Object.fromEntries(keys.map((k) => [k, { metrics: {}, metadata: {} }])) },
-  }) as unknown as DailyData;
-
 describe("getExportBlockedReason", () => {
   it("lets the export through once the data on screen covers the range", () => {
     expect(getExportBlockedReason(state())).toBeUndefined();
@@ -42,28 +33,26 @@ describe("getExportBlockedReason", () => {
     expect(reason).not.toMatch(/stopped/i);
   });
 
-  it("blocks when the aggregated endpoint hit its key cap, since a per-team CSV would miss keys", () => {
-    const reason = getExportBlockedReason(state({ apiKeyLimitReached: 100 }));
+  it("blocks when the aggregated endpoint dropped keys, since a per-team CSV would miss them", () => {
+    const reason = getExportBlockedReason(state({ apiKeyTruncation: { limit: 100, total: 3000 } }));
 
-    expect(reason).toMatch(/100 highest-spend keys/);
+    expect(reason).toMatch(/100 highest-spend keys of 3000/);
     expect(reason).toMatch(/USAGE_TOP_API_KEYS_LIMIT/);
   });
 });
 
-describe("getApiKeyLimitReached", () => {
-  it("reports the cap once the distinct keys across every day reach it", () => {
-    const results = [dayWithKeys("2026-06-01", "key-1", "key-2"), dayWithKeys("2026-06-02", "key-2", "key-3")];
-
-    expect(getApiKeyLimitReached(results, 3)).toBe(3);
+describe("getApiKeyTruncation", () => {
+  it("reports truncation once the proxy saw more keys than it returned", () => {
+    expect(getApiKeyTruncation(100, 101)).toEqual({ limit: 100, total: 101 });
   });
 
-  it("stays quiet while fewer keys than the cap came back, which means every key is on screen", () => {
-    const results = [dayWithKeys("2026-06-01", "key-1", "key-2"), dayWithKeys("2026-06-02", "key-2")];
-
-    expect(getApiKeyLimitReached(results, 3)).toBeUndefined();
+  it("stays quiet when exactly the cap exists, since every key is on screen", () => {
+    expect(getApiKeyTruncation(100, 100)).toBeUndefined();
+    expect(getApiKeyTruncation(100, 7)).toBeUndefined();
   });
 
   it("stays quiet when the response carries no cap, as the paginated fallback does", () => {
-    expect(getApiKeyLimitReached([dayWithKeys("2026-06-01", "key-1")], undefined)).toBeUndefined();
+    expect(getApiKeyTruncation(undefined, undefined)).toBeUndefined();
+    expect(getApiKeyTruncation(100, null)).toBeUndefined();
   });
 });
diff --git a/ui/litellm-dashboard/src/components/EntityUsageExport/exportBlockedReason.ts b/ui/litellm-dashboard/src/components/EntityUsageExport/exportBlockedReason.ts
index ca756090351..6c5a5f83231 100644
--- a/ui/litellm-dashboard/src/components/EntityUsageExport/exportBlockedReason.ts
+++ b/ui/litellm-dashboard/src/components/EntityUsageExport/exportBlockedReason.ts
@@ -1,29 +1,31 @@
-import type { DailyData } from "@/components/UsagePage/types";
+export interface ApiKeyTruncation {
+  limit: number;
+  total: number;
+}
 
 export interface UsageFetchState {
   coversRange: boolean;
   cancelled: boolean;
   failed: boolean;
-  apiKeyLimitReached: number | undefined;
+  apiKeyTruncation: ApiKeyTruncation | undefined;
 }
 
-export const getApiKeyLimitReached = (results: DailyData[], apiKeyLimit: unknown): number | undefined => {
-  if (typeof apiKeyLimit !== "number") return undefined;
-  const keys = new Set(results.flatMap((day) => Object.keys(day.breakdown.api_keys ?? {})));
-  return keys.size >= apiKeyLimit ? apiKeyLimit : undefined;
+export const getApiKeyTruncation = (apiKeyLimit: unknown, totalApiKeys: unknown): ApiKeyTruncation | undefined => {
+  if (typeof apiKeyLimit !== "number" || typeof totalApiKeys !== "number") return undefined;
+  return totalApiKeys > apiKeyLimit ? { limit: apiKeyLimit, total: totalApiKeys } : undefined;
 };
 
 export const getExportBlockedReason = ({
   coversRange,
   cancelled,
   failed,
-  apiKeyLimitReached,
+  apiKeyTruncation,
 }: UsageFetchState): string | undefined => {
   if (failed) return "Some spend data failed to load, so an export would under-report. Reload the page to try again.";
   if (cancelled)
     return "Loading was stopped before the whole range arrived, so an export would under-report. Reload the page to load it all.";
   if (!coversRange) return "Spend data is still loading, so an export would under-report. Wait for it to finish.";
-  if (apiKeyLimitReached !== undefined)
-    return `Only the ${apiKeyLimitReached} highest-spend keys were loaded, so a per-team export would under-report. Raise USAGE_TOP_API_KEYS_LIMIT on the proxy to load more keys.`;
+  if (apiKeyTruncation !== undefined)
+    return `Only the ${apiKeyTruncation.limit} highest-spend keys of ${apiKeyTruncation.total} were loaded, so a per-team export would under-report. Raise USAGE_TOP_API_KEYS_LIMIT on the proxy to load more keys.`;
   return undefined;
 };
diff --git a/ui/litellm-dashboard/src/lib/http/schema.d.ts b/ui/litellm-dashboard/src/lib/http/schema.d.ts
index c9e9c550afa..84656e7eee1 100644
--- a/ui/litellm-dashboard/src/lib/http/schema.d.ts
+++ b/ui/litellm-dashboard/src/lib/http/schema.d.ts
@@ -27503,6 +27503,11 @@ export interface components {
              * @default 1
              */
             page: number;
+            /**
+             * Total Api Keys
+             * @description Distinct API keys matching the filters. When this exceeds api_key_limit, the per-key lists are truncated to the highest-spend keys.
+             */
+            total_api_keys?: number | null;
             /**
              * Total Api Requests
              * @default 0

From 38c1139377279b061b808d12b9b0f8b22c05f339 Mon Sep 17 00:00:00 2001
From: yassin <yassin@berri.ai>
Date: Wed, 16 Sep 2026 10:13:05 +0000
Subject: [PATCH 10/13] feat(ui): note on the Key Activity tab when only the
 top-spend keys were loaded

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../usage/_components/components/UsagePageView.tsx |  2 +-
 .../UsagePage/components/KeyActivityPanel.test.tsx | 10 ++++++++++
 .../UsagePage/components/KeyActivityPanel.tsx      | 14 +++++++++++++-
 3 files changed, 24 insertions(+), 2 deletions(-)

diff --git a/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/UsagePageView.tsx b/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/UsagePageView.tsx
index 3a97e54edfc..a9ab0f17f40 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/UsagePageView.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/UsagePageView.tsx
@@ -908,7 +908,7 @@ const UsagePage: React.FC<UsagePageProps> = ({ teams, organizations }) => {
                   <ActivityMetrics modelMetrics={modelMetrics} />
                 </TabsContent>
                 <TabsContent value="keys" keepMounted>
-                  <KeyActivityPanel keyMetrics={keyMetrics} />
+                  <KeyActivityPanel keyMetrics={keyMetrics} apiKeyTruncation={spendFetchState.apiKeyTruncation} />
                 </TabsContent>
                 <TabsContent value="mcp" keepMounted>
                   <ActivityMetrics modelMetrics={mcpServerMetrics} />
diff --git a/ui/litellm-dashboard/src/components/UsagePage/components/KeyActivityPanel.test.tsx b/ui/litellm-dashboard/src/components/UsagePage/components/KeyActivityPanel.test.tsx
index 693ac20a360..830139143e9 100644
--- a/ui/litellm-dashboard/src/components/UsagePage/components/KeyActivityPanel.test.tsx
+++ b/ui/litellm-dashboard/src/components/UsagePage/components/KeyActivityPanel.test.tsx
@@ -68,4 +68,14 @@ describe("KeyActivityPanel", () => {
     expect(screen.getByLabelText("Search keys")).toHaveValue("");
     expect(screen.getByTestId("rendered-keys")).toHaveTextContent("hash-alicehash-bob");
   });
+
+  it("says how many keys the proxy left out when only the top spenders were loaded", () => {
+    render(<KeyActivityPanel keyMetrics={keyMetrics} apiKeyTruncation={{ limit: 2, total: 3000 }} />);
+    expect(screen.getByRole("note")).toHaveTextContent("Only the 2 highest-spend keys of 3,000 are loaded");
+  });
+
+  it("shows no truncation note when every key is loaded", () => {
+    render(<KeyActivityPanel keyMetrics={keyMetrics} />);
+    expect(screen.queryByRole("note")).not.toBeInTheDocument();
+  });
 });
diff --git a/ui/litellm-dashboard/src/components/UsagePage/components/KeyActivityPanel.tsx b/ui/litellm-dashboard/src/components/UsagePage/components/KeyActivityPanel.tsx
index 8287a04d0c7..8b2141f8528 100644
--- a/ui/litellm-dashboard/src/components/UsagePage/components/KeyActivityPanel.tsx
+++ b/ui/litellm-dashboard/src/components/UsagePage/components/KeyActivityPanel.tsx
@@ -2,6 +2,7 @@ import { Search, X } from "lucide-react";
 import React, { useMemo, useState } from "react";
 
 import { ActivityMetrics } from "@/components/activity_metrics";
+import type { ApiKeyTruncation } from "@/components/EntityUsageExport/exportBlockedReason";
 import { InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput } from "@/components/ui/input-group";
 
 import { filterKeyActivity } from "../keyActivityFilter";
@@ -10,9 +11,14 @@ import type { ModelActivityData } from "../types";
 interface KeyActivityPanelProps {
   keyMetrics: Record<string, ModelActivityData>;
   hidePromptCachingMetrics?: boolean;
+  apiKeyTruncation?: ApiKeyTruncation;
 }
 
-const KeyActivityPanel: React.FC<KeyActivityPanelProps> = ({ keyMetrics, hidePromptCachingMetrics = false }) => {
+const KeyActivityPanel: React.FC<KeyActivityPanelProps> = ({
+  keyMetrics,
+  hidePromptCachingMetrics = false,
+  apiKeyTruncation,
+}) => {
   const [query, setQuery] = useState("");
   const filtered = useMemo(() => filterKeyActivity(keyMetrics, query), [keyMetrics, query]);
   const totalKeys = Object.keys(keyMetrics).length;
@@ -43,6 +49,12 @@ const KeyActivityPanel: React.FC<KeyActivityPanelProps> = ({ keyMetrics, hidePro
         <span className="text-sm text-muted-foreground">
           Showing {shownKeys.toLocaleString()} of {totalKeys.toLocaleString()} keys
         </span>
+        {apiKeyTruncation !== undefined && (
+          <span className="text-sm text-muted-foreground" role="note">
+            Only the {apiKeyTruncation.limit.toLocaleString()} highest-spend keys of{" "}
+            {apiKeyTruncation.total.toLocaleString()} are loaded
+          </span>
+        )}
       </div>
       {isFiltering && totalKeys > 0 && shownKeys === 0 ? (
         <p className="rounded-lg border p-6 text-center text-sm text-muted-foreground">

From 09fa0833b43820c039f45027ce26663de5a5dc54 Mon Sep 17 00:00:00 2001
From: yassin <yassin@berri.ai>
Date: Wed, 16 Sep 2026 10:17:46 +0000
Subject: [PATCH 11/13] feat(ui): surface top-key truncation on the team usage
 view

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../components/EntityUsage/EntityUsage.test.tsx | 17 +++++++++++++++++
 .../components/EntityUsage/EntityUsage.tsx      | 15 ++++++++++++---
 2 files changed, 29 insertions(+), 3 deletions(-)

diff --git a/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/EntityUsage/EntityUsage.test.tsx b/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/EntityUsage/EntityUsage.test.tsx
index 2a6c2ede478..5846a63bc70 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/EntityUsage/EntityUsage.test.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/EntityUsage/EntityUsage.test.tsx
@@ -569,6 +569,23 @@ describe("EntityUsage", () => {
     expect(screen.getAllByText("Activity Metrics")[1]).toBeInTheDocument();
   });
 
+  it("tells the team view how many keys the proxy left out of the per-key lists", async () => {
+    mockTeamDailyActivityAggregatedCall.mockResolvedValue({
+      ...mockSpendData,
+      metadata: { ...mockSpendData.metadata, api_key_limit: 100, total_api_keys: 3000 },
+    });
+    render(<EntityUsage {...defaultProps} entityType="team" />);
+
+    await waitFor(() => {
+      expect(mockTeamDailyActivityAggregatedCall).toHaveBeenCalled();
+    });
+    act(() => {
+      fireEvent.click(screen.getByText("Key Activity"));
+    });
+
+    expect(await screen.findByRole("note")).toHaveTextContent("Only the 100 highest-spend keys of 3,000 are loaded");
+  });
+
   // An inactive tab panel is marked aria-selected="false" by one tab library and hidden by the
   // other, so treat either as "not on screen" and the assertion holds whichever one is rendering.
   const isShowing = (element: HTMLElement): boolean => {
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/EntityUsage/EntityUsage.tsx b/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/EntityUsage/EntityUsage.tsx
index 001fee4b7bc..27460b21108 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/EntityUsage/EntityUsage.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/EntityUsage/EntityUsage.tsx
@@ -25,7 +25,7 @@ import TeamMultiSelect from "@/components/common_components/team_multi_select";
 import UserDropdown from "@/components/common_components/UserDropdown";
 import { ActivityMetrics, processActivityData } from "@/components/activity_metrics";
 import { UsageExportHeader } from "@/components/EntityUsageExport";
-import { getExportBlockedReason } from "@/components/EntityUsageExport/exportBlockedReason";
+import { getApiKeyTruncation, getExportBlockedReason } from "@/components/EntityUsageExport/exportBlockedReason";
 import type { EntityType } from "@/components/EntityUsageExport/types";
 import {
   agentDailyActivityCall,
@@ -71,6 +71,8 @@ interface EntitySpendData {
     total_successful_requests: number;
     total_failed_requests: number;
     total_tokens: number;
+    api_key_limit?: number | null;
+    total_api_keys?: number | null;
   };
 }
 
@@ -160,6 +162,7 @@ const EntityUsage: React.FC<EntityUsageProps> = ({
   });
 
   const spendData = spendDataRaw as unknown as EntitySpendData;
+  const apiKeyTruncation = getApiKeyTruncation(spendData.metadata?.api_key_limit, spendData.metadata?.total_api_keys);
 
   const {
     data: agentSpendDataRaw,
@@ -659,12 +662,18 @@ const EntityUsage: React.FC<EntityUsageProps> = ({
     {
       key: "keys",
       label: "Key Activity",
-      content: <KeyActivityPanel keyMetrics={keyMetrics} hidePromptCachingMetrics={entityType === "agent"} />,
+      content: (
+        <KeyActivityPanel
+          keyMetrics={keyMetrics}
+          hidePromptCachingMetrics={entityType === "agent"}
+          apiKeyTruncation={apiKeyTruncation}
+        />
+      ),
     },
     { key: "endpoints", label: "Endpoint Activity", content: <EndpointUsage userSpendData={spendData} /> },
   ];
 
-  const spendFetchState = { coversRange, cancelled, failed, apiKeyTruncation: undefined };
+  const spendFetchState = { coversRange, cancelled, failed, apiKeyTruncation };
 
   return (
     <div style={{ width: "100%" }} className="relative">

From 303a9058cc9db4ef7251c8e7ecbb90a63e17c36e Mon Sep 17 00:00:00 2001
From: yassin <yassin@berri.ai>
Date: Wed, 16 Sep 2026 10:21:33 +0000
Subject: [PATCH 12/13] refactor(proxy): type entity rollup rows by their own
 projection

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

diff --git a/litellm/proxy/management_endpoints/common_daily_activity.py b/litellm/proxy/management_endpoints/common_daily_activity.py
index a36b6052981..a5e292b177d 100644
--- a/litellm/proxy/management_endpoints/common_daily_activity.py
+++ b/litellm/proxy/management_endpoints/common_daily_activity.py
@@ -146,16 +146,9 @@ class _AggregatedSpendData(TypedDict):
     totals: SpendMetrics
 
 
-class _GroupingSetsRow(SimpleNamespace):
+class _RollupMetricsRow(SimpleNamespace):
     date: str
     api_key: str | None
-    model: str | None
-    model_group: str | None
-    custom_llm_provider: str | None
-    mcp_namespaced_tool_name: str | None
-    endpoint: str | None
-    group_level: int
-    distinct_api_keys: int | None
     spend: float | None
     prompt_tokens: int | None
     completion_tokens: int | None
@@ -173,7 +166,17 @@ class _GroupingSetsRow(SimpleNamespace):
     timed_requests: int | None
 
 
-class _EntityRollupRow(_GroupingSetsRow):
+class _GroupingSetsRow(_RollupMetricsRow):
+    model: str | None
+    model_group: str | None
+    custom_llm_provider: str | None
+    mcp_namespaced_tool_name: str | None
+    endpoint: str | None
+    group_level: int
+    distinct_api_keys: int | None
+
+
+class _EntityRollupRow(_RollupMetricsRow):
     entity_id: str | None
     api_key_rolled: int
 
@@ -202,7 +205,7 @@ async def _query_raw_optional(
     return await prisma_client.db.query_raw(query[0], *query[1])
 
 
-def _reported_flat_cost(record: DailySpendRecord | _GroupingSetsRow) -> float:
+def _reported_flat_cost(record: DailySpendRecord | _RollupMetricsRow) -> float:
     """Flat cost a daily row reports, which is zero unless PTU cost attribution is enabled.
 
     Both read paths funnel through here: the paginated path reads the ``ptu_flat_cost``
@@ -1008,7 +1011,7 @@ _GROUP_DATE_ENDPOINT: Final = 62  # 0b0111110
 _GROUP_DATE_ENDPOINT_API_KEY: Final = 30  # 0b0011110
 
 
-def _record_to_spend_metrics(record: _GroupingSetsRow) -> SpendMetrics:
+def _record_to_spend_metrics(record: _RollupMetricsRow) -> SpendMetrics:
     """Build a SpendMetrics directly from one already-aggregated rollup row.
 
     SUM() over zero rows is SQL NULL, so rollup rows (notably the grand-total

From b74733d4e6971984d3af6e78c565ff37c47cffe2 Mon Sep 17 00:00:00 2001
From: yassin <yassin@berri.ai>
Date: Wed, 16 Sep 2026 10:53:04 +0000
Subject: [PATCH 13/13] feat(ui): note on the cache leakage card when only the
 top-spend keys were loaded

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../_components/CacheLeakageCard.test.tsx     | 24 +++++++++++++++++++
 .../_components/CacheLeakageCard.tsx          |  9 ++++++-
 .../useDailyActivityRange.test.tsx            | 17 ++++++++++++-
 .../_components/useDailyActivityRange.ts      |  3 +++
 4 files changed, 51 insertions(+), 2 deletions(-)

diff --git a/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/CacheLeakageCard.test.tsx b/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/CacheLeakageCard.test.tsx
index 54af13d8a90..8cb18344734 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/CacheLeakageCard.test.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/CacheLeakageCard.test.tsx
@@ -178,4 +178,28 @@ describe("CacheLeakageCard", () => {
       screen.queryByText("Data is still loading; rows and totals will update as the rest of the range arrives."),
     ).not.toBeInTheDocument();
   });
+
+  it("says which keys are missing from the key ranking when the proxy capped the per-key lists", () => {
+    const day = dayWithKeys("2026-07-12", {
+      "hash-leaky": key("leaky-key", { prompt_tokens: 10000, cache_read_input_tokens: 0 }),
+    });
+    renderWith([day], { apiKeyTruncation: { limit: 100, total: 3000 } });
+
+    expect(screen.getByRole("note")).toHaveTextContent(
+      "Only the 100 highest-spend keys of 3,000 are loaded, so a lower-spend key that leaks more is not listed here.",
+    );
+
+    fireEvent.click(screen.getByRole("tab", { name: "By model" }));
+
+    expect(screen.queryByRole("note")).not.toBeInTheDocument();
+  });
+
+  it("keeps the key ranking note off when every key was loaded", () => {
+    const day = dayWithKeys("2026-07-12", {
+      "hash-leaky": key("leaky-key", { prompt_tokens: 10000, cache_read_input_tokens: 0 }),
+    });
+    renderWith([day]);
+
+    expect(screen.queryByRole("note")).not.toBeInTheDocument();
+  });
 });
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/CacheLeakageCard.tsx b/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/CacheLeakageCard.tsx
index 3f27449ebe1..a0877b04648 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/CacheLeakageCard.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/CacheLeakageCard.tsx
@@ -81,7 +81,7 @@ const SortableHead = ({
 };
 
 const CacheLeakageCard: React.FC<CacheLeakageCardProps> = ({ activity }) => {
-  const { dateValue, onDateChange, results, loading, isFetchingMore } = activity;
+  const { dateValue, onDateChange, results, loading, isFetchingMore, apiKeyTruncation } = activity;
   const [dimension, setDimension] = useState<CacheLeakageDimension>("key");
   const [sort, setSort] = useState<SortState>({ column: "potentialSavings", dir: "desc" });
   const leakage = useMemo(() => computeCacheLeakage(results, dimension), [results, dimension]);
@@ -123,6 +123,13 @@ const CacheLeakageCard: React.FC<CacheLeakageCardProps> = ({ activity }) => {
           </Tabs>
         </CardHeader>
         <CardContent>
+          {dimension === "key" && apiKeyTruncation !== undefined && (
+            <p className="mb-2 text-sm text-muted-foreground" role="note">
+              Only the {apiKeyTruncation.limit.toLocaleString()} highest-spend keys of{" "}
+              {apiKeyTruncation.total.toLocaleString()} are loaded, so a lower-spend key that leaks more is not listed
+              here. Raise USAGE_TOP_API_KEYS_LIMIT on the proxy to load more keys.
+            </p>
+          )}
           {rows.length > 0 && isFetchingMore && (
             <p className="mb-2 text-sm text-muted-foreground">
               Data is still loading; rows and totals will update as the rest of the range arrives.
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/useDailyActivityRange.test.tsx b/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/useDailyActivityRange.test.tsx
index 00902aa9fdd..4059303d5a5 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/useDailyActivityRange.test.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/useDailyActivityRange.test.tsx
@@ -4,12 +4,13 @@ import { describe, expect, it, vi } from "vitest";
 const mockUsePaginatedDailyActivity = vi.fn();
 
 const mockCancel = vi.fn();
+let mockMetadata: Record<string, number> = {};
 
 vi.mock("@/app/(dashboard)/usage/_components/hooks/usePaginatedDailyActivity", () => ({
   usePaginatedDailyActivity: (args: unknown) => {
     mockUsePaginatedDailyActivity(args);
     return {
-      data: { results: [] },
+      data: { results: [], metadata: mockMetadata },
       loading: false,
       isFetchingMore: false,
       progress: { currentPage: 4, totalPages: 9 },
@@ -80,4 +81,18 @@ describe("useDailyActivityRange", () => {
 
     expect(mockUsePaginatedDailyActivity).toHaveBeenLastCalledWith(expect.objectContaining({ enabled: false }));
   });
+
+  it("reports how many keys the proxy left out of the per-key lists", () => {
+    mockMetadata = { api_key_limit: 100, total_api_keys: 3000 };
+    const { result } = renderHook(() => useDailyActivityRange("test-token", "u1", "proxy_admin"));
+
+    expect(result.current.apiKeyTruncation).toEqual({ limit: 100, total: 3000 });
+  });
+
+  it("reports no key truncation when every key fit under the proxy limit", () => {
+    mockMetadata = { api_key_limit: 100, total_api_keys: 100 };
+    const { result } = renderHook(() => useDailyActivityRange("test-token", "u1", "proxy_admin"));
+
+    expect(result.current.apiKeyTruncation).toBeUndefined();
+  });
 });
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/useDailyActivityRange.ts b/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/useDailyActivityRange.ts
index 9f793a68bf5..92dd24b8d6d 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/useDailyActivityRange.ts
+++ b/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/useDailyActivityRange.ts
@@ -1,6 +1,7 @@
 import { useMemo, useState } from "react";
 
 import { userDailyActivityAggregatedCall, userDailyActivityCall } from "@/components/networking";
+import { ApiKeyTruncation, getApiKeyTruncation } from "@/components/EntityUsageExport/exportBlockedReason";
 import { DailyData } from "@/components/UsagePage/types";
 import { spendScopeUserId } from "@/utils/roles";
 import { usePaginatedDailyActivity } from "@/app/(dashboard)/usage/_components/hooks/usePaginatedDailyActivity";
@@ -22,6 +23,7 @@ export interface DailyActivityRange {
   cancelled: boolean;
   failed: boolean;
   cancel: () => void;
+  apiKeyTruncation?: ApiKeyTruncation;
 }
 
 /**
@@ -78,6 +80,7 @@ export const useScopedDailyActivityRange = (
     cancelled,
     failed,
     cancel,
+    apiKeyTruncation: getApiKeyTruncation(data.metadata?.api_key_limit, data.metadata?.total_api_keys),
   };
 };