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 f320d8e0f97..54af13d8a90 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 @@ -71,6 +71,7 @@ const renderWith = (results: DailyData[], overrides: Partial isFetchingMore: false, progress: { currentPage: 1, totalPages: 1 }, cancelled: false, + failed: false, cancel: vi.fn(), ...overrides, }} diff --git a/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/CostOptimizationView.tsx b/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/CostOptimizationView.tsx index 8094fa2e8b6..25bd3de0382 100644 --- a/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/CostOptimizationView.tsx +++ b/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/CostOptimizationView.tsx @@ -87,6 +87,7 @@ const CostOptimizationView: React.FC = ({ accessToken diff --git a/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/PromptCachingTab.test.tsx b/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/PromptCachingTab.test.tsx index 2c602033171..66db347e70f 100644 --- a/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/PromptCachingTab.test.tsx +++ b/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/PromptCachingTab.test.tsx @@ -35,6 +35,7 @@ describe("PromptCachingTab", () => { isFetchingMore: false, progress: { currentPage: 1, totalPages: 1 }, cancelled: false, + failed: false, cancel: vi.fn(), }; render(); diff --git a/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/UsageTab.test.tsx b/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/UsageTab.test.tsx index f85a667a074..c62208aacc5 100644 --- a/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/UsageTab.test.tsx +++ b/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/UsageTab.test.tsx @@ -123,6 +123,7 @@ const renderWith = (results: DailyData[], options: RenderOptions = {}) => { isFetchingMore: false, progress: { currentPage: 1, totalPages: 1 }, cancelled: false, + failed: false, cancel: vi.fn(), }} />, 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 3435b57dbc8..9f793a68bf5 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 @@ -20,6 +20,7 @@ export interface DailyActivityRange { isFetchingMore: boolean; progress: { currentPage: number; totalPages: number }; cancelled: boolean; + failed: boolean; cancel: () => void; } @@ -64,7 +65,7 @@ export const useScopedDailyActivityRange = ( args: [accessToken, startTime, endTime, userId, true, apiKey], enabled: !!accessToken && !!startTime && !!endTime, }; - const { data, loading, isFetchingMore, progress, cancelled, cancel } = + const { data, loading, isFetchingMore, progress, cancelled, failed, cancel } = usePaginatedDailyActivity(activityQueryOptions); return { @@ -75,6 +76,7 @@ export const useScopedDailyActivityRange = ( isFetchingMore, progress, cancelled, + failed, cancel, }; }; 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 6c15b3c418d..debc5602277 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,6 +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 type { EntityType } from "@/components/EntityUsageExport/types"; import { agentDailyActivityCall, @@ -145,9 +146,11 @@ const EntityUsage: React.FC = ({ const { data: spendDataRaw, + loading, isFetchingMore, progress, cancelled, + failed, cancel, } = usePaginatedDailyActivity({ fetchFn, @@ -163,6 +166,7 @@ const EntityUsage: React.FC = ({ isFetchingMore: agentIsFetchingMore, progress: agentProgress, cancelled: agentCancelled, + failed: agentFailed, cancel: agentCancel, } = usePaginatedDailyActivity({ fetchFn: agentDailyActivityCall, @@ -660,11 +664,14 @@ const EntityUsage: React.FC = ({ { key: "endpoints", label: "Endpoint Activity", content: }, ]; + const spendFetchState = { loading, isFetchingMore, cancelled, failed }; + return (
@@ -672,6 +679,7 @@ const EntityUsage: React.FC = ({ = ({ onFiltersChange={setSelectedTags} filterOptions={getAllTags() || undefined} teams={teams || []} + exportBlockedReason={getExportBlockedReason(spendFetchState)} /> 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 de353948db9..31c9288c911 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,6 +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 KeyActivityPanel from "@/components/UsagePage/components/KeyActivityPanel"; import { Team } from "@/components/key_team_helpers/key_list"; import { @@ -249,6 +250,14 @@ const UsagePage: React.FC = ({ teams, organizations }) => { const loading = aggregatedLoading || paginatedResult.loading; + const spendFetchState = { + loading, + isFetchingMore: paginatedResult.isFetchingMore, + cancelled: paginatedResult.cancelled, + failed: paginatedResult.failed, + }; + const exportBlockedReason = getExportBlockedReason(spendFetchState); + // Clear isDateChanging when paginated data starts arriving useEffect(() => { if (aggregatedFailed && !paginatedResult.loading && paginatedResult.data.results.length > 0) { @@ -489,6 +498,7 @@ const UsagePage: React.FC = ({ teams, organizations }) => { @@ -525,10 +535,16 @@ const UsagePage: React.FC = ({ teams, organizations }) => { Ask AI - + + +
{/* Cost Panel */} diff --git a/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/hooks/usePaginatedDailyActivity.test.ts b/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/hooks/usePaginatedDailyActivity.test.ts index 0537f469920..5257e5fc8a6 100644 --- a/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/hooks/usePaginatedDailyActivity.test.ts +++ b/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/hooks/usePaginatedDailyActivity.test.ts @@ -156,3 +156,69 @@ describe("usePaginatedDailyActivity page accumulation", () => { expect(result.current.data.metadata.total_spend).toBe(5.5); }); }); + +describe("usePaginatedDailyActivity failure reporting", () => { + const firstPage = { results: [dayOf("2026-08-16", 2)], metadata: { total_pages: 3, page: 1, total_spend: 2 } }; + const start = new Date("2026-08-10"); + const end = new Date("2026-08-17"); + + it("reports a failed range so partial totals cannot pass as the whole range", async () => { + const consoleError = vi.spyOn(console, "error").mockImplementation(() => {}); + const fetchFn = vi.fn((_token: string, _start: Date, _end: Date, page: number) => + page === 1 ? Promise.resolve(firstPage) : Promise.reject(new Error("page 2 never came back")), + ); + + const { result } = renderHook(() => + usePaginatedDailyActivity({ fetchFn, args: ["tok", start, end, null], enabled: true }), + ); + + await waitFor(() => expect(result.current.failed).toBe(true), { timeout: 5000 }); + + expect(result.current.isFetchingMore).toBe(false); + expect(result.current.loading).toBe(false); + expect(result.current.data.metadata.total_spend).toBe(2); + consoleError.mockRestore(); + }); + + it("stays unfailed when every page arrives", async () => { + const pages = [ + firstPage, + { results: [dayOf("2026-08-15", 1)], metadata: { total_pages: 2, page: 2, total_spend: 1 } }, + ]; + const fetchFn = vi.fn((_token: string, _start: Date, _end: Date, page: number) => + Promise.resolve({ ...pages[page - 1], metadata: { ...pages[page - 1].metadata, total_pages: 2 } }), + ); + + const { result } = renderHook(() => + usePaginatedDailyActivity({ fetchFn, args: ["tok", start, end, null], enabled: true }), + ); + + await waitFor(() => expect(result.current.data.metadata.page).toBe(2), { timeout: 5000 }); + + expect(result.current.failed).toBe(false); + }); + + it("clears the failure when a new range is requested, so the banner cannot outlive it", async () => { + const consoleError = vi.spyOn(console, "error").mockImplementation(() => {}); + const fetchFn = vi.fn((...callArgs: unknown[]) => { + const [, , , page, filter] = callArgs as [string, Date, Date, number, string | null]; + if (filter !== "broken") + return Promise.resolve({ ...firstPage, metadata: { ...firstPage.metadata, total_pages: 1 } }); + if (page === 1) return Promise.resolve({ ...firstPage, metadata: { ...firstPage.metadata, total_pages: 2 } }); + return Promise.reject(new Error("page 2 never came back")); + }); + + const { result, rerender } = renderHook( + ({ filter }: { filter: string | null }) => + usePaginatedDailyActivity({ fetchFn, args: ["tok", start, end, filter], enabled: true }), + { initialProps: { filter: "broken" as string | null } }, + ); + + await waitFor(() => expect(result.current.failed).toBe(true), { timeout: 5000 }); + + rerender({ filter: "healthy" }); + + await waitFor(() => expect(result.current.failed).toBe(false), { timeout: 5000 }); + consoleError.mockRestore(); + }); +}); diff --git a/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/hooks/usePaginatedDailyActivity.ts b/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/hooks/usePaginatedDailyActivity.ts index e023feda2e3..aef0021cc3d 100644 --- a/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/hooks/usePaginatedDailyActivity.ts +++ b/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/hooks/usePaginatedDailyActivity.ts @@ -61,6 +61,8 @@ interface UsePaginatedDailyActivityReturn { isFetchingMore: boolean; progress: PaginationProgress; cancelled: boolean; + /** A page request threw, so `data` covers only part of the requested range. */ + failed: boolean; cancel: () => void; } @@ -200,6 +202,7 @@ export function usePaginatedDailyActivity({ totalPages: 0, }); const [cancelled, setCancelled] = useState(false); + const [failed, setFailed] = useState(false); const fetchIdRef = useRef(0); const cancelledRef = useRef(false); @@ -230,12 +233,14 @@ export function usePaginatedDailyActivity({ setIsFetchingMore(false); setProgress({ currentPage: 0, totalPages: 0 }); setCancelled(false); + setFailed(false); return; } const currentFetchId = ++fetchIdRef.current; cancelledRef.current = false; setCancelled(false); + setFailed(false); const isStale = () => fetchIdRef.current !== currentFetchId || cancelledRef.current; @@ -333,6 +338,7 @@ export function usePaginatedDailyActivity({ console.error("Error fetching daily activity:", error); setLoading(false); setIsFetchingMore(false); + setFailed(true); } } }; @@ -350,5 +356,5 @@ export function usePaginatedDailyActivity({ // eslint-disable-next-line react-hooks/exhaustive-deps }, [enabled, fetchFn, aggregatedFetchFn, argsKey]); - return { data, loading, isFetchingMore, progress, cancelled, cancel }; + return { data, loading, isFetchingMore, progress, cancelled, failed, cancel }; } diff --git a/ui/litellm-dashboard/src/components/EntityUsageExport/UsageExportHeader.test.tsx b/ui/litellm-dashboard/src/components/EntityUsageExport/UsageExportHeader.test.tsx index 52fc7605d90..460646dc39c 100644 --- a/ui/litellm-dashboard/src/components/EntityUsageExport/UsageExportHeader.test.tsx +++ b/ui/litellm-dashboard/src/components/EntityUsageExport/UsageExportHeader.test.tsx @@ -41,6 +41,27 @@ describe("UsageExportHeader", () => { expect(screen.getByTestId("export-modal")).toBeInTheDocument(); }); + it("blocks the export while the data on screen does not cover the range", async () => { + const user = userEvent.setup(); + renderWithProviders( + , + ); + + const exportButton = screen.getByRole("button", { name: /export data/i }); + expect(exportButton).toBeDisabled(); + await user.click(exportButton); + expect(screen.queryByTestId("export-modal")).not.toBeInTheDocument(); + }); + + it("explains why the export is blocked on hover", () => { + renderWithProviders(); + + expect(screen.getByTitle("Spend data is still loading")).toBeInTheDocument(); + }); + it("should close the export modal when onClose is called", async () => { const user = userEvent.setup(); renderWithProviders(); diff --git a/ui/litellm-dashboard/src/components/EntityUsageExport/UsageExportHeader.tsx b/ui/litellm-dashboard/src/components/EntityUsageExport/UsageExportHeader.tsx index f5bb56265ed..3c4c7f6f4ee 100644 --- a/ui/litellm-dashboard/src/components/EntityUsageExport/UsageExportHeader.tsx +++ b/ui/litellm-dashboard/src/components/EntityUsageExport/UsageExportHeader.tsx @@ -34,6 +34,8 @@ interface UsageExportHeaderProps { customTitle?: string; compactLayout?: boolean; teams?: Team[]; + /** Set to block the export and explain why; see getExportBlockedReason. */ + exportBlockedReason?: string; } const UsageExportHeader: React.FC = ({ @@ -50,6 +52,7 @@ const UsageExportHeader: React.FC = ({ customTitle, compactLayout = false, teams = [], + exportBlockedReason, }) => { const anchor = useComboboxAnchor(); const [isExportModalOpen, setIsExportModalOpen] = useState(false); @@ -121,10 +124,12 @@ const UsageExportHeader: React.FC = ({ )}
- + + +
diff --git a/ui/litellm-dashboard/src/components/EntityUsageExport/exportBlockedReason.test.ts b/ui/litellm-dashboard/src/components/EntityUsageExport/exportBlockedReason.test.ts new file mode 100644 index 00000000000..0b32aef52fa --- /dev/null +++ b/ui/litellm-dashboard/src/components/EntityUsageExport/exportBlockedReason.test.ts @@ -0,0 +1,39 @@ +import { describe, expect, it } from "vitest"; + +import { getExportBlockedReason, type UsageFetchState } from "./exportBlockedReason"; + +const state = (overrides: Partial = {}): UsageFetchState => ({ + loading: false, + isFetchingMore: false, + cancelled: false, + failed: false, + ...overrides, +}); + +describe("getExportBlockedReason", () => { + it("lets the export through once the range has fully loaded", () => { + expect(getExportBlockedReason(state())).toBeUndefined(); + }); + + it("blocks the first load, before any page has arrived", () => { + expect(getExportBlockedReason(state({ loading: true }))).toMatch(/still loading/i); + }); + + it("blocks while later pages are still arriving, which is when a CSV silently under-reports", () => { + expect(getExportBlockedReason(state({ isFetchingMore: true }))).toMatch(/still loading/i); + }); + + it("blocks after a stopped fetch and says a reload is what fixes it", () => { + const reason = getExportBlockedReason(state({ cancelled: true })); + + expect(reason).toMatch(/stopped/i); + expect(reason).toMatch(/reload/i); + }); + + it("blocks after a failed page and names the failure rather than the stop", () => { + const reason = getExportBlockedReason(state({ failed: true, cancelled: true })); + + expect(reason).toMatch(/failed to load/i); + expect(reason).not.toMatch(/stopped/i); + }); +}); diff --git a/ui/litellm-dashboard/src/components/EntityUsageExport/exportBlockedReason.ts b/ui/litellm-dashboard/src/components/EntityUsageExport/exportBlockedReason.ts new file mode 100644 index 00000000000..ebe67f1ccfe --- /dev/null +++ b/ui/litellm-dashboard/src/components/EntityUsageExport/exportBlockedReason.ts @@ -0,0 +1,21 @@ +export interface UsageFetchState { + loading: boolean; + isFetchingMore: boolean; + cancelled: boolean; + failed: boolean; +} + +/** Why exporting what is on screen would under-report, or undefined once it covers the whole range. */ +export const getExportBlockedReason = ({ + loading, + isFetchingMore, + cancelled, + failed, +}: 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 (loading || isFetchingMore) + return "Spend data is still loading, so an export would under-report. Wait for it to finish."; + return undefined; +}; diff --git a/ui/litellm-dashboard/src/components/shared/PaginationStatusAlerts.test.tsx b/ui/litellm-dashboard/src/components/shared/PaginationStatusAlerts.test.tsx index 5bd48b1aa4c..1eefc43ecb4 100644 --- a/ui/litellm-dashboard/src/components/shared/PaginationStatusAlerts.test.tsx +++ b/ui/litellm-dashboard/src/components/shared/PaginationStatusAlerts.test.tsx @@ -33,6 +33,37 @@ describe("PaginationStatusAlerts", () => { expect(screen.getByText("Showing partial spend data (7/42 pages loaded)")).toBeInTheDocument(); }); + it("calls out a failed page as an error so partial totals do not read as final", () => { + render( + , + ); + + expect( + screen.getByText(/Fetching spend data failed, so the totals below cover only part of the range \(7\/42 pages/), + ).toBeInTheDocument(); + }); + + it("shows only the failure when a stopped fetch also failed", () => { + render( + , + ); + + expect(screen.getByText(/Fetching spend data failed/)).toBeInTheDocument(); + expect(screen.queryByText(/Showing partial spend data/)).not.toBeInTheDocument(); + }); + it("names the subject it is fetching", () => { render( void; subject?: string; + failed?: boolean; } const PaginationStatusAlerts = ({ @@ -17,6 +18,7 @@ const PaginationStatusAlerts = ({ progress, cancel, subject = "spend data", + failed = false, }: PaginationStatusAlertsProps) => ( <> {isFetchingMore && ( @@ -38,7 +40,15 @@ const PaginationStatusAlerts = ({ )} - {cancelled && ( + {failed && ( + + + Fetching {subject} failed, so the totals below cover only part of the range ({progress.currentPage}/ + {progress.totalPages} pages loaded). Reload the page to try again. + + + )} + {cancelled && !failed && ( Showing partial {subject} ({progress.currentPage}/{progress.totalPages} pages loaded) diff --git a/ui/litellm-dashboard/src/components/templates/KeySavingsTab.integration.test.tsx b/ui/litellm-dashboard/src/components/templates/KeySavingsTab.integration.test.tsx index 385c3967d02..00cd1e47e10 100644 --- a/ui/litellm-dashboard/src/components/templates/KeySavingsTab.integration.test.tsx +++ b/ui/litellm-dashboard/src/components/templates/KeySavingsTab.integration.test.tsx @@ -40,6 +40,7 @@ const mockActivity = ( isFetchingMore: false, progress: { currentPage: 1, totalPages: 1 }, cancelled: false, + failed: false, cancel: vi.fn(), ...overrides, });