feat(usage): search team keys beyond the top-N in the Team usage view

litellm/proxy/_types.py

@@ -307,6 +307,7 @@ class KeyManagementRoutes(str, enum.Enum):
     # team usage routes
     TEAM_DAILY_ACTIVITY = "/team/daily/activity"
     TEAM_DAILY_ACTIVITY_AGGREGATED = "/team/daily/activity/aggregated"
+    TEAM_DAILY_ACTIVITY_AGGREGATED_SEARCH = "/team/daily/activity/aggregated/search"
 
     # team spend-log viewing
     SPEND_LOGS = "/spend/logs"
@@ -673,6 +674,7 @@ class LiteLLMRoutes(enum.Enum):
         KeyManagementRoutes.TEAM_KEY_BULK_UPDATE.value,
         KeyManagementRoutes.TEAM_DAILY_ACTIVITY.value,
         KeyManagementRoutes.TEAM_DAILY_ACTIVITY_AGGREGATED.value,
+        KeyManagementRoutes.TEAM_DAILY_ACTIVITY_AGGREGATED_SEARCH.value,
         KeyManagementRoutes.SPEND_LOGS.value,
         KeyManagementRoutes.SPEND_LOGS_V2.value,
         KeyManagementRoutes.KEY_RESET_SPEND.value,
@@ -699,6 +701,7 @@ class LiteLLMRoutes(enum.Enum):
             "/user/list",
             "/user/daily/activity",
             "/user/daily/activity/aggregated",
+            "/user/daily/activity/aggregated/search",
             # team
             "/team/new",
             "/team/update",
@@ -716,6 +719,7 @@ class LiteLLMRoutes(enum.Enum):
             "/team/permissions_bulk_update",
             "/team/daily/activity",
             "/team/daily/activity/aggregated",
+            "/team/daily/activity/aggregated/search",
             "/team/spend/by_user",
             # gateway request counts (SGR); deployment-wide, admin-only
             "/gateway/daily/activity",
@@ -886,6 +890,7 @@ class LiteLLMRoutes(enum.Enum):
         "/team/permissions_update",
         "/team/daily/activity",
         "/team/daily/activity/aggregated",
+        "/team/daily/activity/aggregated/search",
         "/team/spend/by_user",
         "/team/{team_id}/members/me",
         # POST/GET the team's logging callbacks, and DELETE one of them. Every
@@ -901,6 +906,7 @@ class LiteLLMRoutes(enum.Enum):
         "/model/delete",
         "/user/daily/activity",
         "/user/daily/activity/aggregated",
+        "/user/daily/activity/aggregated/search",
         # Endpoint restricts results to organizations the caller is ORG_ADMIN
         # of; a caller who administers none gets an empty result set.
         "/organization/daily/activity",
@@ -984,6 +990,7 @@ class LiteLLMRoutes(enum.Enum):
             "/user/daily/activity",
             "/team/daily/activity",
             "/team/daily/activity/aggregated",
+            "/team/daily/activity/aggregated/search",
             "/tag/daily/activity",
             "/tag/list",
             "/audit",

litellm/proxy/management_endpoints/internal_user_endpoints.py

@@ -28,6 +28,7 @@
 import litellm
 from litellm._logging import verbose_proxy_logger
 from litellm._uuid import uuid
+from litellm.constants import USAGE_TOP_API_KEYS_LIMIT
 from litellm.llms.custom_httpx.http_handler import AsyncHTTPHandler
 from litellm.proxy._types import *
 from litellm.proxy.auth.auth_checks import (
@@ -87,11 +88,13 @@
     VerificationTokenRepository,
 )
 from litellm.types.proxy.management_endpoints.common_daily_activity import (
+    DailySpendMetadata,
     SpendAnalyticsPaginatedResponse,
 )
 from litellm.types.proxy.management_endpoints.internal_user_endpoints import (
     BulkUpdateUserRequest,
     BulkUpdateUserResponse,
+    KeyActivitySearchWhere,
     UserListResponse,
     UserSearchWhere,
     UserUpdateResult,
@@ -2991,6 +2994,27 @@ async def get_user_daily_activity(
         )
 
 
+def _resolve_user_daily_activity_entity_id(
+    user_api_key_dict: UserAPIKeyAuth,
+    user_id: str | None,
+) -> str | None:
+    is_admin: Final = _user_has_admin_view(user_api_key_dict)
+
+    if is_admin:
+        return user_id
+
+    caller_user_id: Final = require_caller_user_id_for_non_admin(user_api_key_dict)
+    effective_user_id: Final = user_id if user_id is not None else caller_user_id
+    if effective_user_id != caller_user_id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail={  # mutable-ok: FastAPI detail payload shape
+                "error": "Non-admin users can only view their own spend data."
+            },
+        )
+    return effective_user_id
+
+
 @router.get(
     "/user/daily/activity/aggregated",
     tags=["Budget & Spend Tracking", "Internal User management"],
@@ -3057,20 +3081,7 @@ async def get_user_daily_activity_aggregated(
         )
 
     try:
-        is_admin: Final = _user_has_admin_view(user_api_key_dict)
-
-        if is_admin:
-            entity_id = user_id  # None means global view, otherwise filter by user
-        else:
-            caller_user_id: Final = require_caller_user_id_for_non_admin(user_api_key_dict)
-            if user_id is None:
-                user_id = caller_user_id
-            if user_id != caller_user_id:
-                raise HTTPException(
-                    status_code=status.HTTP_403_FORBIDDEN,
-                    detail={"error": "Non-admin users can only view their own spend data."},
-                )
-            entity_id = user_id
+        entity_id: Final = _resolve_user_daily_activity_entity_id(user_api_key_dict, user_id)
 
         return await get_daily_activity_aggregated(
             prisma_client=prisma_client,
@@ -3094,3 +3105,117 @@ async def get_user_daily_activity_aggregated(
             status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
             detail={"error": f"Failed to fetch analytics: {e}"},
         )
+
+
+@router.get(
+    "/user/daily/activity/aggregated/search",
+    tags=["Budget & Spend Tracking", "Internal User management"],  # mutable-ok: FastAPI route tags shape
+    dependencies=[Depends(user_api_key_auth)],  # mutable-ok: FastAPI route dependencies shape
+    response_model=SpendAnalyticsPaginatedResponse,
+)
+@management_endpoint_wrapper
+async def search_user_daily_activity_keys(
+    search: str = fastapi.Query(
+        ...,
+        min_length=1,
+        description="Matches keys whose hash equals the value, or whose key alias or user ID contains it (case-insensitive)",
+    ),
+    start_date: str | None = fastapi.Query(
+        default=None,
+        description="Start date in YYYY-MM-DD format",
+    ),
+    end_date: str | None = fastapi.Query(
+        default=None,
+        description="End date in YYYY-MM-DD format",
+    ),
+    user_id: str | None = fastapi.Query(
+        default=None,
+        description="Filter by specific user ID. Admins can filter by any user or omit for global view. Non-admins must provide their own user_id.",
+    ),
+    timezone: int | None = fastapi.Query(
+        default=None,
+        description="Timezone offset in minutes from UTC (e.g., 480 for PST). "
+        "Matches JavaScript's Date.getTimezoneOffset() convention.",
+    ),
+    include_current_utc_day: bool = fastapi.Query(
+        default=False,
+        description="When the range ends on the caller's current local day, extend it to "
+        "today's UTC bucket so spend written after the caller's local midnight (in UTC "
+        "terms) is included. Requires the timezone parameter. Historical ranges are "
+        "never extended.",
+    ),
+    user_api_key_dict: UserAPIKeyAuth = Depends(user_api_key_auth),  # noqa: B008  # FastAPI dependency injection
+) -> SpendAnalyticsPaginatedResponse:
+    """
+    Search verification tokens by exact token hash or by a case-insensitive substring of
+    the key alias or owning user ID, then return the aggregated daily activity for the
+    matches. Lets the Usage page surface keys that fell outside the top-spend subset
+    the aggregated endpoint loads.
+    """
+    from litellm.proxy.proxy_server import prisma_client
+
+    if prisma_client is None:
+        raise HTTPException(
+            status_code=500,
+            detail={  # mutable-ok: FastAPI detail payload shape
+                "error": CommonProxyErrors.db_not_connected_error.value
+            },
+        )
+
+    if start_date is None or end_date is None:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail={"error": "Please provide start_date and end_date"},  # mutable-ok: FastAPI detail payload shape
+        )
+
+    try:
+        entity_id: Final = _resolve_user_daily_activity_entity_id(user_api_key_dict, user_id)
+
+        search_or: Final = (
+            {"token": search},  # mutable-ok: prisma serializes where clauses, keep plain dicts
+            {"key_alias": {"contains": search, "mode": "insensitive"}},  # mutable-ok: prisma where clause leaf
+            {"user_id": {"contains": search, "mode": "insensitive"}},  # mutable-ok: prisma where clause leaf
+        )
+        where: Final[KeyActivitySearchWhere] = (
+            {"OR": search_or}  # mutable-ok: prisma where clause root
+            if entity_id is None
+            else {"user_id": entity_id, "OR": search_or}  # mutable-ok: prisma where clause root
+        )
+        matched_keys: Final = await VerificationTokenRepository(prisma_client).table.find_many(
+            where=where,
+            take=USAGE_TOP_API_KEYS_LIMIT,
+            order={"spend": "desc"},  # mutable-ok: prisma serializes order, keep it a plain dict
+        )
+        tokens: Final = [key.token for key in matched_keys]  # mutable-ok: api_key filter union expects a list
+
+        if not tokens:
+            return SpendAnalyticsPaginatedResponse(
+                results=[],  # mutable-ok: response model field shape
+                metadata=DailySpendMetadata(
+                    api_key_limit=USAGE_TOP_API_KEYS_LIMIT,
+                    total_api_keys=0,
+                ),
+            )
+
+        return await get_daily_activity_aggregated(
+            prisma_client=prisma_client,
+            table_name="litellm_dailyuserspend",
+            entity_id_field="user_id",
+            entity_id=entity_id,
+            entity_metadata_field=None,
+            start_date=start_date,
+            end_date=end_date,
+            model=None,
+            api_key=tokens,
+            timezone_offset_minutes=timezone,
+            include_current_utc_day=include_current_utc_day,
+        )
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        verbose_proxy_logger.exception("/user/daily/activity/aggregated/search: Exception occured - %s", e)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail={"error": f"Failed to fetch analytics: {e}"},  # mutable-ok: FastAPI detail payload shape
+        )

litellm/proxy/management_endpoints/team_endpoints.py

@@ -40,6 +40,7 @@
 import litellm
 from litellm._logging import verbose_proxy_logger
 from litellm._uuid import uuid
+from litellm.constants import USAGE_TOP_API_KEYS_LIMIT
 from litellm.integrations.prometheus import PrometheusLogger
 from litellm.litellm_core_utils.safe_json_dumps import safe_dumps
 from litellm.proxy._types import (
@@ -195,6 +196,7 @@
 from litellm.router import Router
 from litellm.types.proxy.auth.auth_checks import UserNotFoundError
 from litellm.types.proxy.management_endpoints.common_daily_activity import (
+    DailySpendMetadata,
     SpendAnalyticsPaginatedResponse,
 )
 from litellm.types.proxy.management_endpoints.team_endpoints import (
@@ -203,7 +205,9 @@
     BulkUpdateTeamMemberPermissionsRequest,
     BulkUpdateTeamMemberPermissionsResponse,
     GetTeamMemberPermissionsResponse,
+    TeamIdSearchFilter,
     TeamIdSearchMatch,
+    TeamKeyActivitySearchWhere,
     TeamListItem,
     TeamListResponse,
     TeamMemberAddResult,
@@ -6793,6 +6797,111 @@ async def get_team_daily_activity_aggregated(
     )
 
 
+def _team_key_search_where(*, search: str, scope: _TeamDailyActivityScope) -> TeamKeyActivitySearchWhere:
+    """Caller scoping lives inside the same Prisma where as the search term so `take`
+    never trims visible matches in favour of keys the caller is not allowed to see."""
+    search_or: Final = (
+        {"token": search},  # mutable-ok: prisma where clause leaf
+        {"key_alias": {"contains": search, "mode": "insensitive"}},  # mutable-ok: prisma where clause leaf
+        {"user_id": {"contains": search, "mode": "insensitive"}},  # mutable-ok: prisma where clause leaf
+    )
+    own_keys: Final = tuple(scope.api_key_filter) if isinstance(scope.api_key_filter, list) else None
+    team_filter: Final[TeamIdSearchFilter | None] = (
+        {  # mutable-ok: prisma where clause leaf
+            "in": tuple(scope.team_ids),
+            "notIn": tuple(scope.exclude_team_ids),
+        }
+        if scope.team_ids is not None and scope.exclude_team_ids is not None
+        else {"in": tuple(scope.team_ids)}  # mutable-ok: prisma where clause leaf
+        if scope.team_ids is not None
+        else {"notIn": tuple(scope.exclude_team_ids)}  # mutable-ok: prisma where clause leaf
+        if scope.exclude_team_ids is not None
+        else None
+    )
+    if team_filter is None and own_keys is None:
+        return {"OR": search_or}  # mutable-ok: prisma where clause root
+    if team_filter is None and own_keys is not None:
+        return {"token": {"in": own_keys}, "OR": search_or}  # mutable-ok: prisma where clause root
+    if team_filter is not None and own_keys is None:
+        return {"team_id": team_filter, "OR": search_or}  # mutable-ok: prisma where clause root
+    assert team_filter is not None and own_keys is not None
+    return {  # mutable-ok: prisma where clause root
+        "team_id": team_filter,
+        "token": {"in": own_keys},  # mutable-ok: prisma where clause leaf
+        "OR": search_or,
+    }
+
+
+@router.get(
+    "/team/daily/activity/aggregated/search",
+    response_model=SpendAnalyticsPaginatedResponse,
+    tags=["team management"],  # mutable-ok: FastAPI route tags shape
+)
+async def search_team_daily_activity_keys(
+    user_api_key_dict: Annotated[UserAPIKeyAuth, Depends(user_api_key_auth)],
+    search: str = fastapi.Query(
+        ...,
+        min_length=1,
+        description="Exact token hash, or a case-insensitive substring of the key alias or owning user id",
+    ),
+    team_ids: str | None = None,
+    start_date: str | None = None,
+    end_date: str | None = None,
+    exclude_team_ids: str | None = None,
+    timezone: int | None = None,
+) -> SpendAnalyticsPaginatedResponse:
+    """Aggregated daily team activity for the keys matching `search`, across every key the caller may
+    see rather than only the top USAGE_TOP_API_KEYS_LIMIT keys by spend."""
+    from litellm.proxy.proxy_server import (
+        prisma_client,
+        proxy_logging_obj,
+        user_api_key_cache,
+    )
+
+    if prisma_client is None:
+        raise _daily_activity_error(status_code=500, message=CommonProxyErrors.db_not_connected_error.value)
+
+    range_error: Final = _aggregated_date_range_error(start_date, end_date)
+    if range_error is not None:
+        raise _daily_activity_error(status_code=400, message=range_error)
+
+    scope: Final = await _resolve_team_daily_activity_scope(
+        team_ids=team_ids,
+        exclude_team_ids=exclude_team_ids,
+        api_key=None,
+        user_api_key_dict=user_api_key_dict,
+        prisma_client=prisma_client,
+        user_api_key_cache=user_api_key_cache,
+        proxy_logging_obj=proxy_logging_obj,
+    )
+    matched_keys: Final = await _tokens_db(prisma_client).find_many(
+        where=_team_key_search_where(search=search, scope=scope),
+        take=USAGE_TOP_API_KEYS_LIMIT,
+        order={"spend": "desc"},  # mutable-ok: prisma serializes order, keep it a plain dict
+    )
+    tokens: Final = [key.token for key in matched_keys]  # mutable-ok: get_daily_activity_aggregated takes list[str]
+    if not tokens:
+        return SpendAnalyticsPaginatedResponse(
+            results=[],  # mutable-ok: response model field shape
+            metadata=DailySpendMetadata(api_key_limit=USAGE_TOP_API_KEYS_LIMIT, total_api_keys=0),
+        )
+
+    return await get_daily_activity_aggregated(
+        prisma_client=prisma_client,
+        table_name="litellm_dailyteamspend",
+        entity_id_field="team_id",
+        entity_id=scope.team_ids,
+        entity_metadata_field=scope.team_alias_metadata,
+        start_date=start_date,
+        end_date=end_date,
+        model=None,
+        api_key=tokens,
+        exclude_entity_ids=scope.exclude_team_ids,
+        timezone_offset_minutes=timezone,
+        include_entity_breakdown=True,
+    )
+
+
 def _team_user_spend_sql(*, team_count: int, restrict_to_user: bool) -> str:
     team_placeholders: Final = ", ".join(f"${i}" for i in range(3, 3 + team_count))
     user_clause: Final = f' AND sl."user" = ${3 + team_count}' if restrict_to_user else ""