diff --git a/litellm/proxy/db/spend_counter_reseed.py b/litellm/proxy/db/spend_counter_reseed.py
index 95fef0e7820..00cb35866f8 100644
--- a/litellm/proxy/db/spend_counter_reseed.py
+++ b/litellm/proxy/db/spend_counter_reseed.py
@@ -51,6 +51,7 @@ from litellm.repositories.verification_token_repository import (
)
if TYPE_CHECKING:
+ from prisma.models import LiteLLM_BudgetWindowSpend
from prisma.types import LiteLLM_EndUserTableWhereUniqueInput
from litellm.proxy.utils import PrismaClient
@@ -78,6 +79,16 @@ def _as_utc(value: datetime) -> datetime:
return value if value.tzinfo is not None else value.replace(tzinfo=timezone.utc)
+def recorded_window_spend(
+ row: "LiteLLM_BudgetWindowSpend | None", entity_type: str, expected_window_start: datetime | None
+) -> float | None:
+ if expected_window_start is None:
+ return None
+ if row is None or _as_utc(row.window_start) < _as_utc(expected_window_start):
+ return 0.0 if entity_type.startswith("customer_") else None
+ return float(row.spend or 0.0)
+
+
_CUSTOMER_OVERRIDE_INCLUDE: Final = MappingProxyType({"budget": True, "budget_override": True})
_CUSTOMER_COUNTER: Final = re.compile(
r"spend:(customer_org|customer_team|customer_member):(.+):"
@@ -369,11 +380,7 @@ class SpendCounterReseed:
)
return None
- if row is None or _as_utc(row.window_start) < _as_utc(expected_window_start):
- # Customer windows are new maintained balances, with no historical
- # SpendLogs aggregate. A missing period starts at zero, a failed read above does not.
- return 0.0 if entity_type.startswith("customer_") else None
- return float(row.spend or 0.0)
+ return recorded_window_spend(row, entity_type, expected_window_start)
@staticmethod
async def window_from_db(
diff --git a/litellm/proxy/management_helpers/customer_budget_usage.py b/litellm/proxy/management_helpers/customer_budget_usage.py
new file mode 100644
index 00000000000..2802149f18c
--- /dev/null
+++ b/litellm/proxy/management_helpers/customer_budget_usage.py
@@ -0,0 +1,103 @@
+from collections.abc import Mapping, Sequence
+from datetime import datetime
+from itertools import chain
+from typing import TYPE_CHECKING, Final, TypeVar
+
+from litellm.proxy.common_utils.timezone_utils import BudgetResetSettings
+from litellm.repositories.chunked_in import find_many_in
+from litellm.repositories.prisma_protocols import TableActions
+from litellm.types.proxy.auth.customer_hierarchy import CustomerScopeKey
+from litellm.types.proxy.management_endpoints.customer_hierarchy import (
+ Budget,
+ CustomerBudgetUsage,
+ CustomerMember,
+ Organization,
+ Team,
+)
+
+if TYPE_CHECKING:
+ from prisma.models import LiteLLM_BudgetWindowSpend
+
+ from litellm.proxy.spend_tracking.budget_reservation import BudgetCounter
+
+Entity: Final = TypeVar("Entity", Organization, Team, CustomerMember)
+
+
+def _identity(entity: Organization | Team | CustomerMember) -> tuple[CustomerScopeKey, str, Budget | None]:
+ if isinstance(entity, Organization):
+ return "customer_org", entity.customer_org_id, entity.budget
+ if isinstance(entity, Team):
+ return "customer_team", entity.customer_team_id, entity.effective_budget
+ return "customer_member", entity.customer_member_id, entity.effective_budget
+
+
+def _scalar_usage(
+ entity: Organization | Team | CustomerMember, budget: Budget | None
+) -> tuple[CustomerBudgetUsage, ...]:
+ if budget is None or budget.max_budget is None:
+ return ()
+ return (
+ CustomerBudgetUsage(
+ source="scalar",
+ budget_duration=budget.budget_duration,
+ max_budget=budget.max_budget,
+ spend=entity.spend,
+ reset_at=entity.budget_reset_at,
+ ),
+ )
+
+
+def _usage(
+ counters: Sequence["BudgetCounter"],
+ rows: Mapping[tuple[str, str, str], "LiteLLM_BudgetWindowSpend"],
+) -> tuple[CustomerBudgetUsage, ...]:
+ from litellm.proxy.db.spend_counter_reseed import recorded_window_spend
+
+ return tuple(
+ CustomerBudgetUsage(
+ source="window",
+ budget_duration=counter.window_duration,
+ max_budget=counter.max_budget,
+ spend=recorded_window_spend(
+ rows.get((counter.entity_type, counter.entity_id, counter.window_duration or "")),
+ counter.entity_type,
+ counter.window_start,
+ ),
+ window_start=counter.window_start,
+ reset_at=counter.reset_at,
+ )
+ for counter in counters
+ )
+
+
+async def customer_budget_usage(
+ entities: Sequence[Entity],
+ table: TableActions["LiteLLM_BudgetWindowSpend"],
+ now: datetime,
+ settings: BudgetResetSettings,
+) -> tuple[Entity, ...]:
+ from litellm.proxy.spend_tracking.budget_reservation import customer_window_counters
+
+ if not entities:
+ return ()
+ identities: Final = tuple(_identity(entity) for entity in entities)
+ counters: Final = tuple(
+ customer_window_counters(scope, entity_id, budget.budget_limits or (), now=now, reset_settings=settings)
+ if budget is not None
+ else ()
+ for scope, entity_id, budget in identities
+ )
+ windows: Final = tuple(chain.from_iterable(counters))
+ rows: Final = await find_many_in(
+ table,
+ "entity_id",
+ tuple(counter.entity_id for counter in windows),
+ where={"entity_type": identities[0][0]},
+ )
+ by_window: Final = {(row.entity_type, row.entity_id, row.window_duration): row for row in rows}
+ return tuple(
+ entity.model_copy(
+ update={"budget_usage": _scalar_usage(entity, identity[2]) + _usage(entity_windows, by_window)}
+ )
+ for entity, identity, entity_windows in zip(entities, identities, counters, strict=True)
+ )
diff --git a/litellm/proxy/management_helpers/customer_hierarchy.py b/litellm/proxy/management_helpers/customer_hierarchy.py
index 631f338c32f..a65e3505715 100644
--- a/litellm/proxy/management_helpers/customer_hierarchy.py
+++ b/litellm/proxy/management_helpers/customer_hierarchy.py
@@ -17,6 +17,7 @@ from litellm.proxy.common_utils.timezone_utils import (
)
from litellm.proxy.db.db_span import db_span
from litellm.proxy.list_api.common import escape_like
+from litellm.proxy.management_helpers.customer_budget_usage import customer_budget_usage
from litellm.repositories.budget_repository import create_budget_row, update_budget_row
from litellm.repositories.chunked_in import delete_many_in, find_many_in
from litellm.repositories.prisma_protocols import TableActions
@@ -38,6 +39,7 @@ from litellm.types.proxy.management_endpoints.customer_hierarchy import (
if TYPE_CHECKING:
from prisma import Json, Prisma
+ from prisma.models import LiteLLM_BudgetWindowSpend
class ErrorCode(str, Enum):
@@ -472,6 +474,7 @@ class CustomerHierarchyStore:
self.teams: TableActions[PrismaRecord] = db.litellm_customerteamtable # pyright: ignore[reportAttributeAccessIssue] # protocol accepts immutable query mappings
self.members: TableActions[PrismaRecord] = db.litellm_customermembertable # pyright: ignore[reportAttributeAccessIssue] # protocol accepts immutable query mappings
self.budgets: TableActions[PrismaRecord] = db.litellm_budgettable # pyright: ignore[reportAttributeAccessIssue] # protocol accepts immutable query mappings
+ self.window_spend: TableActions[LiteLLM_BudgetWindowSpend] = db.litellm_budgetwindowspend # pyright: ignore[reportAttributeAccessIssue] # protocol accepts immutable query mappings
async def lock_free_capacity(self) -> None:
await self.db.query_raw("SELECT 1 AS locked FROM pg_advisory_xact_lock($1)", FREE_CAPACITY_ADVISORY_LOCK)
@@ -525,9 +528,10 @@ class CustomerHierarchyStore:
budgets: Final = {budget.budget_id: budget for budget in resolved}
counts: Final = await self.organization_member_counts(tuple(record.customer_org_id for record in records))
- return tuple(
+ responses: Final = tuple(
organization_response(record, budgets, counts.get(record.customer_org_id, 0)) for record in records
)
+ return await customer_budget_usage(responses, self.window_spend, self.now, self.settings)
async def organization_member_counts(self, organization_ids: tuple[str, ...]) -> Mapping[str, int]:
if not organization_ids:
@@ -554,11 +558,21 @@ class CustomerHierarchyStore:
async def get_team(self, team_id: str) -> Team | Failure:
row: Final = await self.teams.find_unique(where={"customer_team_id": team_id}, include=_MEMBER_INCLUDE)
- return team_response(row, self.now) if row is not None else Failure(ErrorCode.NOT_FOUND)
+ if row is None:
+ return Failure(ErrorCode.NOT_FOUND)
+ responses: Final = await customer_budget_usage(
+ (team_response(row, self.now),), self.window_spend, self.now, self.settings
+ )
+ return responses[0]
async def get_member(self, member_id: str) -> CustomerMember | Failure:
row: Final = await self.members.find_unique(where={"customer_member_id": member_id}, include=_MEMBER_INCLUDE)
- return member_response(row, self.now) if row is not None else Failure(ErrorCode.NOT_FOUND)
+ if row is None:
+ return Failure(ErrorCode.NOT_FOUND)
+ responses: Final = await customer_budget_usage(
+ (member_response(row, self.now),), self.window_spend, self.now, self.settings
+ )
+ return responses[0]
async def create_budget(self, budget: Budget, actor: str, name: str | None = None) -> str:
budget_id: Final = str(uuid4())
@@ -959,7 +973,12 @@ class CustomerHierarchyStore:
order=[{"created_at": "asc"}, {"customer_team_id": "asc"}],
include=_MEMBER_INCLUDE,
)
- return Page(tuple(team_response(row, self.now) for row in rows), count)
+ return Page(
+ await customer_budget_usage(
+ tuple(team_response(row, self.now) for row in rows), self.window_spend, self.now, self.settings
+ ),
+ count,
+ )
async def list_members(
self, parent_team_id: str | None, page: int, page_size: int, *, parent_org_id: str | None = None
@@ -976,7 +995,12 @@ class CustomerHierarchyStore:
order=[{"created_at": "asc"}, {"customer_member_id": "asc"}],
include=_MEMBER_INCLUDE,
)
- return Page(tuple(member_response(row, self.now) for row in rows), count)
+ return Page(
+ await customer_budget_usage(
+ tuple(member_response(row, self.now) for row in rows), self.window_spend, self.now, self.settings
+ ),
+ count,
+ )
async def _delete_unused_budgets(self, budget_ids: Sequence[str]) -> None:
where: Final[Mapping[str, object]] = {field: {"none": {}} for field in _BUDGET_REFERENCE_FIELDS}
diff --git a/litellm/types/proxy/management_endpoints/customer_hierarchy.py b/litellm/types/proxy/management_endpoints/customer_hierarchy.py
index aa977174bec..06300affb76 100644
--- a/litellm/types/proxy/management_endpoints/customer_hierarchy.py
+++ b/litellm/types/proxy/management_endpoints/customer_hierarchy.py
@@ -119,12 +119,28 @@ class MemberUpsert(MemberPatch):
return self
+class CustomerBudgetUsage(BaseModel):
+ model_config = ConfigDict(frozen=True)
+
+ source: Literal["scalar", "window"]
+ budget_duration: str | None
+ max_budget: float
+ spend: float | None
+ window_start: datetime | None = None
+ reset_at: datetime | None = None
+
+
class AuditFields(BaseModel):
model_config = ConfigDict(frozen=True)
alias: str | None = None
spend: float = 0.0
budget_reset_at: datetime | None = None
+ budget_usage: tuple[CustomerBudgetUsage, ...] | None = Field(
+ default=None,
+ description="Recorded spend for each independent effective budget. Excludes pending reservations and updates "
+ "after accounting flushes. Window boundaries follow the configured reset timezone and time.",
+ )
created_at: datetime
created_by: str
updated_at: datetime
diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/CustomerBudgetSpend.tsx b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/CustomerBudgetSpend.tsx
new file mode 100644
index 00000000000..2ba9b20418b
--- /dev/null
+++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/CustomerBudgetSpend.tsx
@@ -0,0 +1,94 @@
+import { useTranslation } from "react-i18next";
+import { formatUsd } from "@/app/(dashboard)/usage/_components/components/overview/overviewData";
+import { cn } from "@/lib/cva.config";
+import { CUSTOMER_BUDGET_LABELS, customerBudgetPeriod, type CustomerBudgetUsage } from "./customerBudgetUsage";
+
+function budgetPercentage(spend: number, limit: number | null): number {
+ if (limit === null) return 0;
+ if (limit === 0) return 100;
+ return Math.max(0, Math.min(100, (spend / limit) * 100));
+}
+
+export function CustomerBudgetWindow({
+ budget,
+ showReset = false,
+}: {
+ budget: CustomerBudgetUsage;
+ showReset?: boolean;
+}) {
+ const { t, i18n } = useTranslation();
+ const period = customerBudgetPeriod(budget.budget_duration);
+ const label = t(CUSTOMER_BUDGET_LABELS[period]);
+ const reset = budget.reset_at
+ ? t("customerPortal.analytics.budgetResets", {
+ date: new Date(budget.reset_at).toLocaleString(i18n.resolvedLanguage, { timeZone: "UTC" }),
+ })
+ : null;
+ return (
+
+
+ {showReset && reset &&
{reset}
}
+
+ );
+}
+
+export default function CustomerBudgetSpend({
+ spend,
+ limit,
+ label,
+ noLimitLabel,
+ compact = false,
+}: {
+ spend: number | null;
+ limit: number | null;
+ label: string;
+ noLimitLabel?: string;
+ compact?: boolean;
+}) {
+ const { t } = useTranslation();
+ const value = `${spend === null ? t("customerPortal.analytics.unknownSpend") : formatUsd(spend)} / ${limit === null ? noLimitLabel ?? t("customerPortal.analytics.noLimit") : formatUsd(limit)}`;
+ const atLimit = limit !== null && spend !== null && spend >= limit;
+ const percentage = budgetPercentage(spend ?? 0, limit);
+ const balance =
+ limit === null || spend === null
+ ? null
+ : t(spend > limit ? "customerPortal.analytics.budgetOver" : "customerPortal.analytics.budgetRemaining", {
+ amount: formatUsd(Math.abs(limit - spend)),
+ });
+ if (compact) return {value};
+ return (
+
+
+ {value}
+ {balance !== null && (
+
+ {balance}
+
+ )}
+
+ {limit !== null && spend !== null && (
+
+ )}
+
+ );
+}
diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/CustomerBudgetSummary.tsx b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/CustomerBudgetSummary.tsx
index 26adc7a3cbc..69c98d614ec 100644
--- a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/CustomerBudgetSummary.tsx
+++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/CustomerBudgetSummary.tsx
@@ -1,13 +1,7 @@
import { useTranslation } from "react-i18next";
-import { formatUsd } from "@/app/(dashboard)/usage/_components/components/overview/overviewData";
-import { cn } from "@/lib/cva.config";
import type { CustomerUsageEntity } from "./customerUsageApi";
-
-function budgetPercentage(spend: number, limit: number | null): number {
- if (limit === null) return 0;
- if (limit === 0) return 100;
- return Math.max(0, Math.min(100, (spend / limit) * 100));
-}
+import CustomerBudgetSpend, { CustomerBudgetWindow } from "./CustomerBudgetSpend";
+import { CUSTOMER_BUDGET_LABELS, customerBudgetPeriod, customerBudgetUsage } from "./customerBudgetUsage";
export default function CustomerBudgetSummary({
entity,
@@ -16,41 +10,35 @@ export default function CustomerBudgetSummary({
entity: CustomerUsageEntity;
settingsHref: string;
}) {
- const { t, i18n } = useTranslation();
- const limit = entity.budgetLimit;
- const atLimit = limit !== null && entity.spend >= limit;
- const percentage = budgetPercentage(entity.spend, limit);
- const cap = limit === null ? t("customerPortal.analytics.noCap") : formatUsd(limit);
- const value = `${formatUsd(entity.spend)} / ${cap}`;
+ const { t } = useTranslation();
+ const budgets = customerBudgetUsage(entity);
return (
-
+
- {value}
- {limit !== null && (
-
+ {budgets.map((budget) => {
+ const period = customerBudgetPeriod(budget.budget_duration);
+ return (
+
+
+ {t(CUSTOMER_BUDGET_LABELS[period])}
+ {period === "other" && budget.budget_duration && ` (${budget.budget_duration})`}
+
+
customerBudgetPeriod(item.budget_duration) === period).length > 1}
+ />
+
+ );
+ })}
+ {budgets.length === 0 && (
+
)}
-
- {t("customerPortal.analytics.budgetPeriod")}
- {entity.budgetResetAt &&
- ` · ${t("customerPortal.analytics.budgetResets", {
- date: new Date(entity.budgetResetAt).toLocaleDateString(i18n.resolvedLanguage, { timeZone: "UTC" }),
- })}`}
-
+ {t("customerPortal.analytics.budgetUsageHint")}
);
}
diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/CustomerHierarchyManager.tsx b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/CustomerHierarchyManager.tsx
index 5e90b329b27..0a72578a7c7 100644
--- a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/CustomerHierarchyManager.tsx
+++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/CustomerHierarchyManager.tsx
@@ -41,13 +41,16 @@ function HierarchyHeader({ hierarchy, selected }: Pick {
- if (member.budgetLimit === null) return "customerPortal.analytics.noCap" as const;
- if (member.spend > member.budgetLimit) return "customerPortal.analytics.overBudget" as const;
- if (member.spend === member.budgetLimit) return "customerPortal.analytics.atBudget" as const;
- return "customerPortal.analytics.withinBudget" as const;
-};
-
export default function CustomerMemberSpend({
data,
onMemberClick,
@@ -30,13 +25,17 @@ export default function CustomerMemberSpend({
const { t } = useTranslation();
const [table, setTable] = useQueryStates(MEMBER_TABLE_PARSERS);
const search = table.memberSearch;
- const usage = useMemo(() => new Map(data.members.map((member) => [member.id, member])), [data.members]);
+ const usage = useMemo(() => new Map(data.monthlyMembers.map((member) => [member.id, member])), [data.monthlyMembers]);
+ const yearlyUsage = useMemo(
+ () => new Map(data.yearlyMembers.map((member) => [member.id, member.spend])),
+ [data.yearlyMembers],
+ );
const members = useMemo(
() =>
data.memberBudgets
.filter((member) => member.label.toLocaleLowerCase().includes(search.toLocaleLowerCase()))
- .map((member) => ({ ...member, rangeUsage: usage.get(member.id) }))
- .sort((a, b) => (b.rangeUsage?.spend ?? 0) - (a.rangeUsage?.spend ?? 0) || a.label.localeCompare(b.label)),
+ .map((member) => ({ ...member, monthlyUsage: usage.get(member.id) }))
+ .sort((a, b) => (b.monthlyUsage?.spend ?? 0) - (a.monthlyUsage?.spend ?? 0) || a.label.localeCompare(b.label)),
[data.memberBudgets, search, usage],
);
@@ -65,15 +64,33 @@ export default function CustomerMemberSpend({
{t("customerPortal.analytics.member")}
- {t("customerPortal.analytics.spend")}
+ {t("customerPortal.analytics.monthlySpend")}
+ {t("customerPortal.analytics.yearlySpend")}
+ {t("customerPortal.analytics.customerSpendShare")}
{t("customerPortal.analytics.tokens")}
- {t("customerPortal.analytics.currentBudget")}
{t("customerPortal.analytics.status")}
{members.slice(start, start + PAGE_SIZE).map((member) => {
- const atLimit = member.budgetLimit !== null && member.spend >= member.budgetLimit;
+ const monthlySpend = member.monthlyUsage?.spend ?? 0;
+ const budgets = customerBudgetUsage(member);
+ const monthlyBudgets = budgets.filter(
+ (budget) => customerBudgetPeriod(budget.budget_duration) === "monthly",
+ );
+ const yearlyBudgets = budgets.filter((budget) => customerBudgetPeriod(budget.budget_duration) === "yearly");
+ const otherBudgets = budgets.filter((budget) => customerBudgetPeriod(budget.budget_duration) === "other");
+ const yearlySpend = yearlyUsage.get(member.id) ?? 0;
+ const spendShare =
+ data.monthlyOrganizationSpend > 0 ? (monthlySpend / data.monthlyOrganizationSpend) * 100 : 0;
+ const sharePercentage = Math.max(0, Math.min(100, spendShare));
+ const shareLabel = t("format.number", {
+ val: spendShare / 100,
+ style: "percent",
+ maximumFractionDigits: 1,
+ });
+ const status = customerBudgetStatus(budgets);
+ const atLimit = status === "customerPortal.analytics.reachedLimit";
return (
@@ -101,14 +118,58 @@ export default function CustomerMemberSpend({
- {formatUsd(member.rangeUsage?.spend ?? 0)}
-
- {formatCompact(member.rangeUsage?.tokens ?? 0)}
+
+
+ {monthlyBudgets.map((budget) => (
+
1} />
+ ))}
+ {monthlyBudgets.length === 0 && (
+
+ )}
+ {otherBudgets.map((budget) => (
+
+
+ {t("customerPortal.analytics.budgetPeriod")}
+ {budget.budget_duration && ` (${budget.budget_duration})`}
+
+
+
+ ))}
+
-
- {member.budgetLimit === null
- ? t("customerPortal.analytics.noBudget")
- : `${formatUsd(member.spend)} / ${formatUsd(member.budgetLimit)}`}
+
+
+ {yearlyBudgets.map((budget) => (
+ 1} />
+ ))}
+ {yearlyBudgets.length === 0 &&
+ `${formatUsd(yearlySpend)} / ${t("customerPortal.analytics.noYearlyLimit")}`}
+
+
+
+
+
+
+ {formatCompact(member.monthlyUsage?.tokens ?? 0)}
- {t(memberStatus(member))}
+ {t(status)}
@@ -125,7 +186,7 @@ export default function CustomerMemberSpend({
})}
{members.length === 0 && (
-
+
{t(search ? "customerPortal.analytics.noMatches" : "customerPortal.analytics.noMembers")}
diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerBudgetUsage.test.ts b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerBudgetUsage.test.ts
new file mode 100644
index 00000000000..eb943d83380
--- /dev/null
+++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerBudgetUsage.test.ts
@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import { customerBudgetPeriod, customerBudgetStatus, customerBudgetUsage } from "./customerBudgetUsage";
+import type { CustomerUsageEntity } from "./customerUsageApi";
+
+const entity: CustomerUsageEntity = {
+ id: "member",
+ label: "Member",
+ spend: 40,
+ budgetLimit: 50,
+ budgetDuration: "1mo",
+ budgetResetAt: null,
+ budgetLimits: [
+ { budget_duration: "1mo", max_budget: 10 },
+ { budget_duration: "12mo", max_budget: 100 },
+ ],
+};
+
+describe("customer budget usage", () => {
+ it("keeps independent counters and their limits paired, even with the same duration", () => {
+ const budgetUsage = [
+ { source: "scalar" as const, budget_duration: "1mo", max_budget: 50, spend: 40 },
+ { source: "window" as const, budget_duration: "1mo", max_budget: 10, spend: 8 },
+ { source: "window" as const, budget_duration: "12mo", max_budget: 100, spend: 62 },
+ ];
+ expect(customerBudgetUsage({ ...entity, budgetUsage })).toEqual(budgetUsage);
+ expect(customerBudgetStatus(budgetUsage)).toBe("customerPortal.analytics.withinBudget");
+ });
+
+ it.each([0, 10, 100])("marks a recorded exhausted limit including zero (%s)", (limit) => {
+ expect(customerBudgetStatus([{ source: "window", budget_duration: "12mo", max_budget: limit, spend: limit }])).toBe(
+ "customerPortal.analytics.reachedLimit",
+ );
+ });
+
+ it("distinguishes unavailable window usage from no budget and zero spend", () => {
+ const usage = customerBudgetUsage(entity);
+ expect(usage.map((budget) => [budget.max_budget, budget.spend])).toEqual([
+ [50, 40],
+ [10, null],
+ [100, null],
+ ]);
+ expect(customerBudgetStatus(usage)).toBe("customerPortal.analytics.budgetUsageUnavailable");
+ expect(customerBudgetStatus([])).toBe("customerPortal.analytics.noLimit");
+ expect(customerBudgetStatus([{ source: "window", budget_duration: "1mo", max_budget: 10, spend: 0 }])).toBe(
+ "customerPortal.analytics.withinBudget",
+ );
+ });
+
+ it.each([
+ ["1mo", "monthly"],
+ ["monthly", "monthly"],
+ ["30days", "monthly"],
+ ["12mo", "yearly"],
+ ["12months", "yearly"],
+ ["365d", "other"],
+ [null, "other"],
+ ] as const)("labels the configured duration %s without computing its reset", (duration, period) => {
+ expect(customerBudgetPeriod(duration)).toBe(period);
+ });
+});
diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerBudgetUsage.ts b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerBudgetUsage.ts
new file mode 100644
index 00000000000..c651a75454e
--- /dev/null
+++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerBudgetUsage.ts
@@ -0,0 +1,48 @@
+import type { components } from "@/lib/http/schema";
+import type { CustomerUsageEntity } from "./customerUsageApi";
+
+export type CustomerBudgetUsage = components["schemas"]["CustomerBudgetUsage"];
+export type CustomerBudgetPeriod = "monthly" | "yearly" | "other";
+
+export const CUSTOMER_BUDGET_LABELS = {
+ monthly: "customerPortal.analytics.monthlySpend",
+ yearly: "customerPortal.analytics.yearlySpend",
+ other: "customerPortal.analytics.budgetPeriod",
+} as const;
+
+export const customerBudgetPeriod = (duration: string | null): CustomerBudgetPeriod => {
+ const normalized = duration?.trim().toLowerCase() ?? "";
+ if (["1mo", "1month", "1months", "30d", "30days", "monthly"].includes(normalized)) return "monthly";
+ if (["12mo", "12month", "12months"].includes(normalized)) return "yearly";
+ return "other";
+};
+
+export const customerBudgetUsage = (entity: CustomerUsageEntity): CustomerBudgetUsage[] =>
+ entity.budgetUsage ?? [
+ ...(entity.budgetLimit === null
+ ? []
+ : [
+ {
+ source: "scalar" as const,
+ budget_duration: entity.budgetDuration,
+ max_budget: entity.budgetLimit,
+ spend: entity.spend,
+ reset_at: entity.budgetResetAt,
+ },
+ ]),
+ ...entity.budgetLimits.map((limit) => ({
+ source: "window" as const,
+ budget_duration: limit.budget_duration,
+ max_budget: limit.max_budget,
+ spend: null,
+ reset_at: limit.reset_at,
+ })),
+ ];
+
+export const customerBudgetStatus = (usage: CustomerBudgetUsage[]) => {
+ if (usage.some((budget) => budget.spend !== null && budget.spend >= budget.max_budget))
+ return "customerPortal.analytics.reachedLimit" as const;
+ if (usage.some((budget) => budget.spend === null)) return "customerPortal.analytics.budgetUsageUnavailable" as const;
+ if (usage.length === 0) return "customerPortal.analytics.noLimit" as const;
+ return "customerPortal.analytics.withinBudget" as const;
+};
diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageApi.test.ts b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageApi.test.ts
index cb4d2b738b2..cd13a5c3d6f 100644
--- a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageApi.test.ts
+++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageApi.test.ts
@@ -99,6 +99,10 @@ const request = {
accessToken: "test-session",
startDate: "2026-11-01",
endDate: "2026-11-03",
+ monthStartDate: "2026-11-01",
+ monthEndDate: "2026-11-03",
+ yearStartDate: "2026-01-01",
+ yearEndDate: "2026-11-03",
};
const list = (data: T[], page = 1, totalPages = 1) => ({
data,
@@ -167,6 +171,37 @@ beforeEach(() => {
afterEach(() => vi.unstubAllGlobals());
describe("customerHierarchyUsageCall", () => {
+ it("should preserve scalar and concurrent effective caps without treating recorded spend as window spend", async () => {
+ const budget = {
+ max_budget: 25,
+ budget_duration: "1mo",
+ budget_limits: [
+ { budget_duration: "1mo", max_budget: 0, reset_at: "2026-12-01T00:00:00Z" },
+ { budget_duration: "12mo", max_budget: 100, reset_at: "2027-01-01T00:00:00Z" },
+ ],
+ };
+ fetchMock.mockImplementation((input) =>
+ Promise.resolve(
+ requestUrl(input).pathname.endsWith("/customer_members/member-a")
+ ? json({ ...members[0], effective_budget: budget })
+ : serve(input),
+ ),
+ );
+ const result = await customerHierarchyUsageCall({
+ ...request,
+ scope: { org: "org-1", team: null, member: "member-a" },
+ });
+ const expected = {
+ spend: 40,
+ budgetLimit: 25,
+ budgetDuration: "1mo",
+ budgetLimits: budget.budget_limits,
+ };
+ expect(result.member).toMatchObject(expected);
+ expect(result.memberBudgets[0]).toEqual(result.member);
+ expect(result.organization.budgetLimits).toEqual([]);
+ });
+
it("should read exact daily activity routes, all pages, and scoped descendant lists", async () => {
fetchMock.mockImplementation((input) => {
const url = requestUrl(input);
@@ -202,9 +237,14 @@ describe("customerHierarchyUsageCall", () => {
expect(result.memberResults).toHaveLength(1);
expect(result.memberResults[0].breakdown.entities["member-b"].metrics.total_tokens).toBe(500);
expect(result.memberBudgets[0]).toMatchObject({ id: "member-a", spend: 40, budgetLimit: 10 });
+ expect(result.yearlyMembers.map((member) => member.spend)).toEqual([3, 1]);
for (const url of dailyUrls()) {
expect(url.pathname).toMatch(/^\/management\/v1\/customer_(organizations|teams|members)\/daily\/activity$/);
- expect(url.searchParams.get("start_date")).toBe(request.startDate);
+ expect(url.searchParams.get("start_date")).toBe(
+ url.pathname.includes("customer_members") && url.searchParams.get("start_date") === request.yearStartDate
+ ? request.yearStartDate
+ : request.startDate,
+ );
expect(url.searchParams.get("end_date")).toBe(request.endDate);
expect(url.searchParams.get("page_size")).toBe("100");
expect([...url.searchParams.keys()].filter((name) => name.endsWith("_ids"))).toHaveLength(1);
@@ -252,11 +292,35 @@ describe("customerHierarchyUsageCall", () => {
expect(Object.keys(result.teamResults[0].breakdown.entities)).toEqual(["team-a"]);
expect(result.teamResults[0].breakdown.entities["team-a"].metrics.spend).toBe(3);
expect(result.memberResults[0].breakdown.entities["member-a"].metrics.total_tokens).toBe(100);
- expect(dailyUrls()).toHaveLength(1);
- expect(dailyUrls()[0].searchParams.get("customer_member_ids")).toBe("member-a");
+ const memberReads = dailyUrls().filter((url) => url.searchParams.has("customer_member_ids"));
+ expect(memberReads.map((url) => url.searchParams.get("start_date"))).toEqual([
+ request.startDate,
+ request.yearStartDate,
+ ]);
+ expect(memberReads[0].searchParams.get("customer_member_ids")).toBe("member-a");
+ expect(result.monthlyOrganizationSpend).toBe(4);
+ expect(result.monthlyMembers.find((member) => member.id === "member-a")?.spend).toBe(3);
+ expect(result.yearlyMembers.find((member) => member.id === "member-a")?.spend).toBe(3);
expect(urls().some((url) => url.pathname === "/management/v1/customer_members")).toBe(false);
});
+ it("should retain both periods when the selected chart range is the current year", async () => {
+ const yearRequest = {
+ ...request,
+ scope: { org: "org-1", team: null, member: "member-a" },
+ startDate: request.yearStartDate,
+ endDate: request.yearEndDate,
+ };
+ const result = await customerHierarchyUsageCall(yearRequest);
+ expect(result.yearlyMembers).toEqual(result.members);
+ expect(result.monthlyMembers.find((member) => member.id === "member-a")?.spend).toBe(3);
+ expect(
+ dailyUrls()
+ .filter((url) => url.searchParams.has("customer_member_ids"))
+ .map((url) => url.searchParams.get("start_date")),
+ ).toEqual([request.yearStartDate, request.monthStartDate]);
+ });
+
it("should reject mismatched ancestry before requesting any usage", async () => {
fetchMock.mockImplementation((input) =>
Promise.resolve(
@@ -271,6 +335,29 @@ describe("customerHierarchyUsageCall", () => {
expect(dailyUrls()).toHaveLength(0);
});
+ it("should read monthly member totals and the whole organization independently of a team's selected chart dates", async () => {
+ fetchMock.mockImplementation((input) => {
+ const url = requestUrl(input);
+ if (url.pathname.endsWith("/daily/activity") && url.searchParams.get("start_date") === "2026-10-01")
+ return Promise.resolve(json({ results: [], metadata: EMPTY_DAILY_ACTIVITY_METADATA }));
+ return Promise.resolve(serve(input));
+ });
+ const teamRequest = {
+ ...request,
+ scope: { org: "org-1", team: "team-a", member: null },
+ startDate: "2026-10-01",
+ endDate: "2026-10-31",
+ };
+ const result = await customerHierarchyUsageCall(teamRequest);
+ expect(result.metadata.total_spend).toBe(0);
+ expect(result.monthlyOrganizationSpend).toBe(4);
+ expect(result.monthlyMembers.find((member) => member.id === "member-a")?.spend).toBe(3);
+ expect(result.yearlyMembers.find((member) => member.id === "member-a")?.spend).toBe(3);
+ const organizationReads = dailyUrls().filter((url) => url.searchParams.has("customer_org_ids"));
+ expect(organizationReads.map((url) => url.searchParams.get("page"))).toEqual(["1", "2"]);
+ expect(organizationReads.every((url) => url.searchParams.get("start_date") === request.monthStartDate)).toBe(true);
+ });
+
it("should never send an empty descendant filter and should retain unassigned usage", async () => {
fetchMock.mockImplementation((input) =>
Promise.resolve(requestUrl(input).pathname === "/management/v1/customer_teams" ? json(list([])) : serve(input)),
diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageApi.ts b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageApi.ts
index aedd12d5aa9..4852af7540b 100644
--- a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageApi.ts
+++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageApi.ts
@@ -27,7 +27,10 @@ export interface CustomerUsageEntity {
label: string;
spend: number;
budgetLimit: number | null;
+ budgetDuration: string | null;
+ budgetLimits: components["schemas"]["BudgetLimit"][];
budgetResetAt: string | null;
+ budgetUsage?: components["schemas"]["CustomerBudgetUsage"][] | null;
}
export interface CustomerHierarchyUsage extends ReturnType {
@@ -40,6 +43,9 @@ export interface CustomerHierarchyUsage extends ReturnType["results"];
memberResults: ReturnType["results"];
memberBudgets: CustomerUsageEntity[];
+ monthlyOrganizationSpend: number;
+ monthlyMembers: UsageRow[];
+ yearlyMembers: UsageRow[];
}
interface CustomerUsageRequest {
@@ -47,6 +53,10 @@ interface CustomerUsageRequest {
accessToken: string;
startDate: string;
endDate: string;
+ monthStartDate: string;
+ monthEndDate: string;
+ yearStartDate: string;
+ yearEndDate: string;
signal?: AbortSignal;
}
@@ -136,7 +146,7 @@ const activityPages = async (resource: Collection, ids: readonly string[], reque
};
interface ActivityJob {
- dimension: "scope" | "teams" | "members";
+ dimension: "scope" | "teams" | "members" | "monthlyOrganization" | "monthlyMembers" | "yearlyMembers";
resource: Collection;
ids: readonly string[];
}
@@ -148,13 +158,19 @@ const chunkJobs = (resource: Collection, dimension: ActivityJob["dimension"], id
ids: ids.slice(index * PAGE_SIZE, (index + 1) * PAGE_SIZE),
}));
-const entity = (id: string, record: Organization | Team | Member): CustomerUsageEntity => ({
- id,
- label: record.alias || id,
- spend: record.spend,
- budgetLimit: ("effective_budget" in record ? record.effective_budget : record.budget)?.max_budget ?? null,
- budgetResetAt: record.budget_reset_at ?? null,
-});
+const entity = (id: string, record: Organization | Team | Member): CustomerUsageEntity => {
+ const budget = "effective_budget" in record ? record.effective_budget : record.budget;
+ return {
+ id,
+ label: record.alias || id,
+ spend: record.spend,
+ budgetLimit: budget?.max_budget ?? null,
+ budgetDuration: budget?.budget_duration ?? null,
+ budgetLimits: budget?.budget_limits ?? [],
+ budgetResetAt: record.budget_reset_at ?? null,
+ budgetUsage: record.budget_usage,
+ };
+};
const selectedResource = (scope: ResolvedScope): Collection => {
if (scope.member) return "customer_members";
@@ -162,6 +178,21 @@ const selectedResource = (scope: ResolvedScope): Collection => {
return "customer_organizations";
};
+const monthlyJobs = (
+ isCurrentMonth: boolean,
+ resource: Collection,
+ organizationId: string,
+ memberIds: readonly string[],
+): ActivityJob[] => [
+ ...(!isCurrentMonth || resource !== "customer_organizations"
+ ? chunkJobs("customer_organizations", "monthlyOrganization", [organizationId])
+ : []),
+ ...(!isCurrentMonth ? chunkJobs("customer_members", "monthlyMembers", memberIds) : []),
+];
+
+const isSelectedRange = (request: CustomerUsageRequest, startDate: string, endDate: string): boolean =>
+ request.startDate === startDate && request.endDate === endDate;
+
export const customerHierarchyUsageCall = async (request: CustomerUsageRequest): Promise => {
assertIdentifiers([
request.scope.org,
@@ -171,6 +202,8 @@ export const customerHierarchyUsageCall = async (request: CustomerUsageRequest):
const children = await descendants(selected, request);
const resource = selectedResource(selected);
const selectedId = selected.member?.customer_member_id ?? selected.team?.customer_team_id ?? request.scope.org;
+ const isCurrentMonth = isSelectedRange(request, request.monthStartDate, request.monthEndDate);
+ const isCurrentYear = isSelectedRange(request, request.yearStartDate, request.yearEndDate);
const jobs: ActivityJob[] = [
{ dimension: "scope", resource, ids: [selectedId] },
...(!selected.team
@@ -187,10 +220,33 @@ export const customerHierarchyUsageCall = async (request: CustomerUsageRequest):
children.members.map((member) => member.customer_member_id),
)
: []),
+ ...monthlyJobs(
+ isCurrentMonth,
+ resource,
+ request.scope.org,
+ children.members.map((member) => member.customer_member_id),
+ ),
+ ...(!isCurrentYear
+ ? chunkJobs(
+ "customer_members",
+ "yearlyMembers",
+ children.members.map((member) => member.customer_member_id),
+ )
+ : []),
];
+ const monthRequest = { ...request, startDate: request.monthStartDate, endDate: request.monthEndDate };
+ const yearRequest = { ...request, startDate: request.yearStartDate, endDate: request.yearEndDate };
+ const requests: Record = {
+ scope: request,
+ teams: request,
+ members: request,
+ monthlyOrganization: monthRequest,
+ monthlyMembers: monthRequest,
+ yearlyMembers: yearRequest,
+ };
const activity = await batches(jobs, async (job) => ({
dimension: job.dimension,
- pages: await activityPages(job.resource, job.ids, request),
+ pages: await activityPages(job.resource, job.ids, requests[job.dimension]),
}));
const primary = mergeCustomerActivityPages(
activity.filter((result) => result.dimension === "scope").flatMap((result) => result.pages),
@@ -205,6 +261,22 @@ export const customerHierarchyUsageCall = async (request: CustomerUsageRequest):
: mergeCustomerActivityPages(
activity.filter((result) => result.dimension === "members").flatMap((result) => result.pages),
).results;
+ const monthlyOrganization =
+ isCurrentMonth && resource === "customer_organizations"
+ ? primary
+ : mergeCustomerActivityPages(
+ activity.filter((result) => result.dimension === "monthlyOrganization").flatMap((result) => result.pages),
+ );
+ const monthlyMemberDays = isCurrentMonth
+ ? memberDays
+ : mergeCustomerActivityPages(
+ activity.filter((result) => result.dimension === "monthlyMembers").flatMap((result) => result.pages),
+ ).results;
+ const yearlyMemberActivity = isCurrentYear
+ ? { results: memberDays, metadata: primary.metadata }
+ : mergeCustomerActivityPages(
+ activity.filter((result) => result.dimension === "yearlyMembers").flatMap((result) => result.pages),
+ );
const teamLabels = new Map(
children.teams.map((team) => [team.customer_team_id, team.alias || team.customer_team_id]),
);
@@ -232,5 +304,12 @@ export const customerHierarchyUsageCall = async (request: CustomerUsageRequest):
),
memberResults: customerEntityDailyData(primary.results, memberDays, memberLabels),
memberBudgets: children.members.map((member) => entity(member.customer_member_id, member)),
+ monthlyOrganizationSpend: monthlyOrganization.metadata.total_spend,
+ monthlyMembers: customerEntityRankings(monthlyMemberDays, memberLabels, monthlyOrganization.metadata, {
+ unassignedLabel: i18n.t("customerPortal.analytics.unassignedMember"),
+ }),
+ yearlyMembers: customerEntityRankings(yearlyMemberActivity.results, memberLabels, yearlyMemberActivity.metadata, {
+ unassignedLabel: i18n.t("customerPortal.analytics.unassignedMember"),
+ }),
};
};
diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageChartData.test.ts b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageChartData.test.ts
index 2d2a46178e4..adf9e33fb22 100644
--- a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageChartData.test.ts
+++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageChartData.test.ts
@@ -38,10 +38,21 @@ const day = (date: string, total: SpendMetrics, breakdown: Partial ({
- organization: { id: "org", label: "Organization", spend: 0, budgetLimit: null, budgetResetAt: null },
+ organization: {
+ id: "org",
+ label: "Organization",
+ spend: 0,
+ budgetLimit: null,
+ budgetDuration: null,
+ budgetLimits: [],
+ budgetResetAt: null,
+ },
team: null,
member: null,
memberBudgets: [],
+ monthlyOrganizationSpend: 0,
+ monthlyMembers: [],
+ yearlyMembers: [],
metadata: { ...EMPTY_DAILY_ACTIVITY_METADATA },
results: [
day("2026-11-01", metrics(100, 1_000, 100), {
diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageData.test.ts b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageData.test.ts
index c8e6d638c79..e9cf6809f42 100644
--- a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageData.test.ts
+++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageData.test.ts
@@ -1,7 +1,6 @@
import { describe, expect, it } from "vitest";
import type { DailyData, MetricWithMetadata, SpendMetrics } from "@/components/UsagePage/types";
import { rankCustomerModels, rankCustomerUsage, type CustomerUsageRow } from "./customerUsageData";
-
const metrics = (spend: number, tokens: number, requests: number): SpendMetrics => ({
spend,
prompt_tokens: tokens,
diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageData.ts b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageData.ts
index afa0d3c7767..6d66b92dfbb 100644
--- a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageData.ts
+++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageData.ts
@@ -9,7 +9,6 @@ import {
rollUpBreakdown,
type UsageMetric,
} from "@/app/(dashboard)/usage/_components/components/overview/overviewData";
-
export interface CustomerUsageTotals {
spend: number;
tokens: number;
diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/useCustomerHierarchyUsage.ts b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/useCustomerHierarchyUsage.ts
index 05fa467d0e5..67640a52240 100644
--- a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/useCustomerHierarchyUsage.ts
+++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/useCustomerHierarchyUsage.ts
@@ -21,6 +21,7 @@ import type { DailyData } from "@/components/UsagePage/types";
import { customerHierarchyUsageCall, type CustomerUsageScope } from "./customerUsageApi";
import { rankCustomerModels, rankCustomerUsage } from "./customerUsageData";
import { CUSTOMER_USAGE_DIMENSIONS, type CustomerUsageDimension } from "./CustomerUsageRankings";
+import { calendarDate, customerPresetRange } from "./customerUsageRange";
const usageParsers = {
org: parseAsString,
@@ -60,9 +61,30 @@ export default function useCustomerHierarchyUsage() {
const endDate = dateValue.to ? formatDate(dateValue.to) : undefined;
const scope = params.org ? { org: params.org, team: params.team, member: params.member } : null;
const request = usageRequest(scope, accessToken, startDate, endDate);
+ const month = customerPresetRange("month");
+ const monthStartDate = calendarDate(month.from);
+ const monthEndDate = calendarDate(month.to);
+ const year = customerPresetRange("YTD");
+ const yearStartDate = calendarDate(year.from);
+ const yearEndDate = calendarDate(year.to);
const usage = useQuery({
- queryKey: ["customer-hierarchy", "usage", params.org, params.team, params.member, startDate, endDate],
- queryFn: request ? ({ signal }) => customerHierarchyUsageCall({ ...request, signal }) : skipToken,
+ queryKey: [
+ "customer-hierarchy",
+ "usage",
+ params.org,
+ params.team,
+ params.member,
+ startDate,
+ endDate,
+ monthStartDate,
+ yearEndDate,
+ ],
+ queryFn: request
+ ? ({ signal }) => {
+ const periodRequest = { ...request, monthStartDate, monthEndDate, yearStartDate, yearEndDate, signal };
+ return customerHierarchyUsageCall(periodRequest);
+ }
+ : skipToken,
});
const data = usage.data;
const results = data?.results ?? EMPTY_RESULTS;
diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/manage/page.integration.test.tsx b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/manage/page.integration.test.tsx
index 269513b3045..e9c51fec78b 100644
--- a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/manage/page.integration.test.tsx
+++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/manage/page.integration.test.tsx
@@ -134,7 +134,7 @@ describe("customer hierarchy management", () => {
const table = await screen.findByRole("table", { name: "Customer teams" });
expect(within(table).getByRole("button", { name: "Product" })).toBeInTheDocument();
expect(screen.getByRole("heading", { name: "Example customer" })).toBeInTheDocument();
- expect(screen.getByRole("progressbar", { name: "Current budget" })).toHaveAttribute("aria-valuenow", "12");
+ expect(screen.getByRole("progressbar", { name: "Recorded budget spend" })).toHaveAttribute("aria-valuenow", "12");
expect(
requestedUrls()
.find((url) => url.pathname === "/management/v1/customer_teams")
@@ -152,6 +152,33 @@ describe("customer hierarchy management", () => {
]);
});
+ it("should show effective member window limits without treating them as an absent budget", async () => {
+ fetchMock.mockImplementation(async (input) =>
+ requestUrl(input).pathname === "/management/v1/customer_members/member-a"
+ ? json({
+ ...member,
+ effective_budget: {
+ max_budget: null,
+ budget_limits: [
+ { budget_duration: "1mo", max_budget: 10 },
+ { budget_duration: "12mo", max_budget: 100 },
+ ],
+ },
+ })
+ : serve(input),
+ );
+ renderWithProviders(, { searchParams: "?org=org-1&team=team-a&member=member-a" });
+ const summary = await screen.findByRole("region", { name: "Current budget" });
+ expect(within(summary).getByText("Unavailable / $10.00")).toBeInTheDocument();
+ expect(within(summary).getByText("Unavailable / $100.00")).toBeInTheDocument();
+ expect(within(summary).getByRole("link", { name: "Edit budget" })).toHaveAttribute(
+ "href",
+ `${uiHref("customers/manage")}?org=org-1&team=team-a&member=member-a&tab=settings`,
+ );
+ expect(within(summary).queryByText(/No limit/)).not.toBeInTheDocument();
+ expect(within(summary).queryByRole("progressbar")).not.toBeInTheDocument();
+ });
+
it("should list customer members across an organization and open their customer team context", async () => {
const user = userEvent.setup();
const onUrlUpdate = vi.fn();
diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/usage/page.integration.test.tsx b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/usage/page.integration.test.tsx
index a3472a36fb1..4eca6b81bb9 100644
--- a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/usage/page.integration.test.tsx
+++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/usage/page.integration.test.tsx
@@ -61,6 +61,19 @@ const members = [
},
];
const records = [
+ ...[
+ { date: "2026-03-01", spend: 42 },
+ { date: "2025-12-31", spend: 100 },
+ ].map(({ date, spend }) => ({
+ organization: "org-1",
+ team: "team-a",
+ member: "member-a",
+ model: "model-a",
+ key: "hash-a",
+ alias: "Assistant key",
+ metrics: metrics(spend, 50, 1),
+ date,
+ })),
{
organization: "org-1",
team: "team-a",
@@ -81,6 +94,26 @@ const records = [
metrics: metrics(3, 600, 5),
date: "2026-11-02",
},
+ {
+ organization: "org-1",
+ team: "team-a",
+ member: "member-a",
+ model: "model-a",
+ key: "hash-a",
+ alias: "Assistant key",
+ metrics: metrics(8, 300, 1),
+ date: "2026-11-10",
+ },
+ {
+ organization: "org-1",
+ team: "",
+ member: "",
+ model: "model-a",
+ key: "hash-c",
+ alias: "Organization key",
+ metrics: metrics(7, 200, 1),
+ date: "2026-11-10",
+ },
];
const fetchMock = vi.fn();
const json = (body: unknown, status = 200) =>
@@ -104,10 +137,13 @@ const filterFor = (resource: string | undefined) =>
team: "customer_team_ids",
member: "customer_member_ids",
})[activityDimension(resource)];
-const activityUrl = (resource: string, id: string) => {
+const activityUrl = (resource: string, id: string, endDate = "2026-11-03") => {
const filter = filterFor(resource);
return requestedUrls().findLast(
- (url) => url.pathname === `/management/v1/${resource}/daily/activity` && url.searchParams.get(filter) === id,
+ (url) =>
+ url.pathname === `/management/v1/${resource}/daily/activity` &&
+ url.searchParams.get(filter) === id &&
+ url.searchParams.get("end_date") === endDate,
);
};
const serve = (input: Parameters[0]): Response => {
@@ -117,7 +153,13 @@ const serve = (input: Parameters[0]): Response => {
const dimension = activityDimension(resource);
const filter = filterFor(resource);
const ids = url.searchParams.get(filter)?.split(",") ?? [];
- const selected = records.filter((record) => ids.includes(record[dimension]));
+ const selected = records
+ .filter((record) => ids.includes(record[dimension]))
+ .filter(
+ (record) =>
+ record.date >= (url.searchParams.get("start_date") ?? "") &&
+ record.date <= (url.searchParams.get("end_date") ?? ""),
+ );
const results = selected.map((record) => {
const key = { metrics: record.metrics, metadata: { key_alias: record.alias, team_id: null } };
const entry = { metrics: record.metrics, metadata: {}, api_key_breakdown: { [record.key]: key } };
@@ -148,6 +190,8 @@ const serve = (input: Parameters[0]): Response => {
describe("CustomerHierarchyUsagePage", () => {
beforeEach(() => {
+ vi.useFakeTimers({ toFake: ["Date"] });
+ vi.setSystemTime(new Date("2026-11-13T12:00:00Z"));
testQueryClient.clear();
registerBaseUrlGetter(() => "http://localhost");
fetchMock.mockReset();
@@ -160,6 +204,7 @@ describe("CustomerHierarchyUsagePage", () => {
});
afterEach(() => {
+ vi.useRealTimers();
testQueryClient.clear();
vi.unstubAllGlobals();
});
@@ -231,7 +276,7 @@ describe("CustomerHierarchyUsagePage", () => {
expect(activityUrl("customer_teams", "team-a")?.pathname).toBe("/management/v1/customer_teams/daily/activity");
expect(activityUrl("customer_teams", "team-a")?.searchParams.get("customer_team_ids")).toBe("team-a");
const teamBudget = screen.getByRole("region", { name: "Current budget" });
- expect(within(teamBudget).getByText("$40.00 / No cap")).toBeInTheDocument();
+ expect(within(teamBudget).getByText("$40.00 / No limit")).toBeInTheDocument();
expect(within(teamBudget).getByRole("link", { name: "Set budget" })).toHaveAttribute(
"href",
"/ui/customers/manage?org=org-1&team=team-a&tab=settings",
@@ -280,16 +325,20 @@ describe("CustomerHierarchyUsagePage", () => {
]);
});
- it("should retain a separate member spend table with range usage and current budget status across chart breakdowns", async () => {
+ it("should retain monthly member usage and whole-customer shares across chart breakdowns", async () => {
const user = userEvent.setup();
const onUrlUpdate = vi.fn();
renderWithProviders(, { searchParams: initialUrl, onUrlUpdate });
const table = await screen.findByRole("table", { name: "Customer member spend" });
const firstMember = within(table).getAllByRole("row")[1];
expect(firstMember).toHaveTextContent("Member One");
- expect(within(firstMember).getByText("$12.00")).toBeInTheDocument();
- expect(within(firstMember).getByText("$40.00 / $10.00")).toBeInTheDocument();
- expect(within(firstMember).getByText("Over budget")).toBeInTheDocument();
+ expect(within(firstMember).getByText("$20.00 / No monthly limit")).toBeInTheDocument();
+ expect(within(firstMember).getByRole("meter", { name: "Share of customer spend" })).toHaveAttribute(
+ "aria-valuetext",
+ "66.7%",
+ );
+ expect(firstMember).toHaveTextContent("Recorded budget spend$40.00 / $10.00");
+ expect(within(firstMember).getByText("Reached limit")).toBeInTheDocument();
await selectBreakdown(user, "Customer teams");
await user.click(screen.getByRole("radio", { name: "Tokens" }));
@@ -335,6 +384,105 @@ describe("CustomerHierarchyUsagePage", () => {
);
});
+ it.each([
+ { monthlySpend: 8, yearlySpend: 62, status: "Within budget" },
+ { monthlySpend: 10, yearlySpend: 62, status: "Reached limit" },
+ { monthlySpend: 8, yearlySpend: 100, status: "Reached limit" },
+ ])(
+ "should use each recorded budget window consistently across the table and summary (%#)",
+ async ({ monthlySpend, yearlySpend, status }) => {
+ const user = userEvent.setup();
+ const budgetUsage = [
+ { source: "scalar", budget_duration: "1mo", max_budget: 50, spend: 40, reset_at: "2026-12-01T00:00:00Z" },
+ {
+ source: "window",
+ budget_duration: "1mo",
+ max_budget: 10,
+ spend: monthlySpend,
+ window_start: "2026-11-01T17:00:00Z",
+ reset_at: "2026-12-01T17:00:00Z",
+ },
+ {
+ source: "window",
+ budget_duration: "12mo",
+ max_budget: 100,
+ spend: yearlySpend,
+ window_start: "2026-01-01T17:00:00Z",
+ reset_at: "2027-01-01T17:00:00Z",
+ },
+ ];
+ fetchMock.mockImplementation((input) => {
+ const url = requestUrl(input);
+ const member = {
+ ...members[0],
+ budget_usage: budgetUsage,
+ effective_budget: {
+ max_budget: 50,
+ budget_duration: "1mo",
+ budget_limits: [
+ { budget_duration: "1mo", max_budget: 10 },
+ { budget_duration: "12mo", max_budget: 100 },
+ ],
+ },
+ };
+ if (url.pathname === "/management/v1/customer_members")
+ return Promise.resolve(json(list(url.searchParams.get("parent_team_id") === "team-a" ? [member] : [])));
+ if (url.pathname.endsWith("/customer_members/member-a")) return Promise.resolve(json(member));
+ return Promise.resolve(serve(input));
+ });
+ renderWithProviders(, { searchParams: initialUrl });
+ const table = await screen.findByRole("table", { name: "Customer member spend" });
+ const row = within(table).getAllByRole("row")[1];
+ expect(within(row).getByText("$40.00 / $50.00")).toBeInTheDocument();
+ expect(within(row).getByText(`$${monthlySpend.toFixed(2)} / $10.00`)).toBeInTheDocument();
+ expect(within(row).getByText(`$${yearlySpend.toFixed(2)} / $100.00`)).toBeInTheDocument();
+ expect(
+ within(row)
+ .getAllByRole("progressbar")
+ .map((bar) => bar.getAttribute("aria-valuenow")),
+ ).toEqual(["80", String(monthlySpend * 10)]);
+ expect(within(row).getByRole("meter", { name: "Share of customer spend" })).toHaveAttribute(
+ "aria-valuetext",
+ "66.7%",
+ );
+ expect(within(row).getAllByRole("cell")[5]).toHaveTextContent(status);
+ await user.click(within(row).getByRole("button", { name: "Member One" }));
+ expect(await screen.findByRole("heading", { name: "Member One" })).toBeInTheDocument();
+ const summary = screen.getByRole("region", { name: "Current budget" });
+ expect(within(summary).getByText("$40.00 / $50.00")).toBeInTheDocument();
+ expect(within(summary).getByText(`$${monthlySpend.toFixed(2)} / $10.00`)).toBeInTheDocument();
+ expect(within(summary).getByText(`$${yearlySpend.toFixed(2)} / $100.00`)).toBeInTheDocument();
+ expect(
+ within(summary)
+ .getAllByRole("progressbar")
+ .map((bar) => bar.getAttribute("aria-valuenow")),
+ ).toEqual(["80", String(monthlySpend * 10)]);
+ },
+ );
+
+ it("should retain limits but not invent window spend when an older backend omits usage", async () => {
+ fetchMock.mockImplementation((input) => {
+ const url = requestUrl(input);
+ if (url.pathname === "/management/v1/customer_members")
+ return Promise.resolve(
+ json(
+ list(
+ url.searchParams.get("parent_team_id") === "team-a"
+ ? [{ ...members[0], effective_budget: { budget_limits: [{ budget_duration: "1mo", max_budget: 10 }] } }]
+ : [],
+ ),
+ ),
+ );
+ return Promise.resolve(serve(input));
+ });
+ renderWithProviders(, { searchParams: initialUrl });
+ const table = await screen.findByRole("table", { name: "Customer member spend" });
+ const row = within(table).getAllByRole("row")[1];
+ expect(within(row).getByText("Unavailable / $10.00")).toBeInTheDocument();
+ expect(within(row).getByText("Budget usage unavailable")).toBeInTheDocument();
+ expect(within(row).queryByRole("progressbar")).not.toBeInTheDocument();
+ });
+
it("should request a changed date range without showing stale totals or losing the customer scope", async () => {
const user = userEvent.setup();
const onUrlUpdate = vi.fn();
@@ -355,10 +503,14 @@ describe("CustomerHierarchyUsagePage", () => {
await user.click(screen.getByRole("button", { name: "Apply" }));
await waitFor(() =>
- expect(activityUrl("customer_organizations", "org-1")?.searchParams.get("start_date")).toBe("2026-10-01"),
+ expect(activityUrl("customer_organizations", "org-1", "2026-10-07")?.searchParams.get("start_date")).toBe(
+ "2026-10-01",
+ ),
);
- expect(activityUrl("customer_organizations", "org-1")?.searchParams.get("end_date")).toBe("2026-10-07");
- expect(activityUrl("customer_organizations", "org-1")?.pathname).toBe(
+ expect(activityUrl("customer_organizations", "org-1", "2026-10-07")?.searchParams.get("end_date")).toBe(
+ "2026-10-07",
+ );
+ expect(activityUrl("customer_organizations", "org-1", "2026-10-07")?.pathname).toBe(
"/management/v1/customer_organizations/daily/activity",
);
expect(screen.getByRole("status", { name: "Loading customer usage" })).toBeInTheDocument();
@@ -425,7 +577,7 @@ describe("CustomerHierarchyUsagePage", () => {
const budget = await screen.findByRole("region", { name: "Current budget" });
expect(within(budget).getByText("$40.00 / $0.00")).toBeInTheDocument();
expect(within(budget).getByRole("progressbar")).toHaveAttribute("aria-valuenow", "100");
- expect(within(budget).getByText(/Configured reset:.*UTC/)).toBeInTheDocument();
+ expect(within(budget).getByTitle(/Configured reset:.*UTC/)).toBeInTheDocument();
expect(within(budget).queryByRole("link", { name: "Set budget" })).not.toBeInTheDocument();
});
});
diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/UsageStatStrip.tsx b/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/UsageStatStrip.tsx
index 7e7ccf5aa8b..da8e85a05d2 100644
--- a/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/UsageStatStrip.tsx
+++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/UsageStatStrip.tsx
@@ -42,7 +42,9 @@ export default function UsageStatStrip({
: t("usage.statStrip.noBudget");
return (
- }>
+ 1 ? : undefined}
+ >
{spendDetails}
- }>
+ 1 ? : undefined
+ }
+ >
)}
- }>
+ 1 ? : undefined
+ }
+ >
None:
+ database: Final = Database()
+ http: Final = client(database=database)
+ family(http)
+ created: Final = http.post(
+ "/management/v1/customer_members",
+ json={
+ "customer_member_id": "window-member", "parent_team_ids": ["team"],
+ "budget_override": {
+ "max_budget": 50, "budget_duration": "1mo",
+ "budget_limits": [{"budget_duration": "1mo", "max_budget": 10}],
+ },
+ },
+ )
+ assert created.status_code == 201, created.text
+ database.litellm_budgetwindowspend.rows = {
+ "window-member": Record(
+ entity_type="customer_member", entity_id="window-member", window_duration="1mo",
+ window_start=NOW, spend=8,
+ ),
+ }
+ detail: Final = http.get("/management/v1/customer_members/window-member")
+ listing: Final = http.get("/management/v1/customer_members?parent_team_id=team")
+ assert detail.status_code == listing.status_code == 200
+ assert listing.json()["data"][0]["budget_usage"] == detail.json()["budget_usage"]
+ assert [(item["spend"], item["max_budget"]) for item in detail.json()["budget_usage"]] == [(0, 50), (8, 10)]
diff --git a/tests/unit/proxy/management_helpers/test_customer_budget_usage.py b/tests/unit/proxy/management_helpers/test_customer_budget_usage.py
new file mode 100644
index 00000000000..910cd23d406
--- /dev/null
+++ b/tests/unit/proxy/management_helpers/test_customer_budget_usage.py
@@ -0,0 +1,80 @@
+from datetime import datetime, time, timezone
+from typing import Final, cast
+
+import pytest
+from prisma.models import LiteLLM_BudgetWindowSpend
+
+from litellm.models.budget import BudgetLimit
+
+from litellm.proxy.common_utils.timezone_utils import BudgetResetSettings
+from litellm.proxy.management_helpers.customer_budget_usage import customer_budget_usage
+from litellm.proxy.spend_tracking.budget_reservation import customer_window_counters
+from litellm.repositories.prisma_protocols import TableActions
+from litellm.types.proxy.management_endpoints.customer_hierarchy import Budget, CustomerMember
+from tests.unit.proxy.management_helpers.test_customer_hierarchy import Database, Record
+
+NOW: Final = datetime(2026, 11, 13, 12, tzinfo=timezone.utc)
+SETTINGS: Final = BudgetResetSettings(timezone="America/Los_Angeles", reset_time_of_day=time(9))
+
+
+def member(member_id: str) -> CustomerMember:
+ return CustomerMember(
+ customer_member_id=member_id,
+ parent_org_id="org",
+ parent_team_ids=("team",),
+ spend=40,
+ effective_budget=Budget(
+ max_budget=50,
+ budget_duration="1mo",
+ budget_limits=(
+ BudgetLimit(budget_duration="1mo", max_budget=10),
+ BudgetLimit(budget_duration="12mo", max_budget=100),
+ ),
+ ),
+ created_at=NOW,
+ created_by="admin",
+ updated_at=NOW,
+ updated_by="admin",
+ )
+
+
+@pytest.mark.asyncio
+async def test_recorded_usage_matches_enforced_windows_and_keeps_shared_members_independent() -> None:
+ database: Final = Database()
+ first: Final = member("member-a")
+ second: Final = member("member-b")
+ counters: Final = customer_window_counters(
+ "customer_member", "member-a", first.effective_budget.budget_limits or (), now=NOW, reset_settings=SETTINGS
+ )
+ assert counters[0].window_start == datetime(2026, 11, 1, 17, tzinfo=timezone.utc)
+ database.litellm_budgetwindowspend.rows = {
+ "monthly": Record(
+ entity_type="customer_member", entity_id="member-a", window_duration="1mo",
+ window_start=counters[0].window_start, spend=8,
+ ),
+ "yearly": Record(
+ entity_type="customer_member", entity_id="member-a", window_duration="12mo",
+ window_start=counters[1].window_start, spend=62,
+ ),
+ "another-scope": Record(
+ entity_type="customer_team", entity_id="member-b", window_duration="1mo",
+ window_start=counters[0].window_start, spend=999,
+ ),
+ "expired": Record(
+ entity_type="customer_member", entity_id="member-b", window_duration="1mo",
+ window_start=datetime(2026, 10, 1, 16, tzinfo=timezone.utc), spend=100,
+ ),
+ }
+ result: Final = await customer_budget_usage(
+ (first, second),
+ cast(TableActions[LiteLLM_BudgetWindowSpend], database.litellm_budgetwindowspend),
+ NOW,
+ SETTINGS,
+ )
+ assert result[0].budget_usage is not None
+ assert tuple((item.spend, item.max_budget) for item in result[0].budget_usage) == ((40, 50), (8, 10), (62, 100))
+ assert tuple((item.window_start, item.reset_at) for item in result[0].budget_usage[1:]) == tuple(
+ (counter.window_start, counter.reset_at) for counter in counters
+ )
+ assert result[1].budget_usage is not None
+ assert tuple(item.spend for item in result[1].budget_usage) == (40, 0, 0)
diff --git a/tests/unit/proxy/management_helpers/test_customer_hierarchy.py b/tests/unit/proxy/management_helpers/test_customer_hierarchy.py
index 8d9be312ac9..da73d4617bf 100644
--- a/tests/unit/proxy/management_helpers/test_customer_hierarchy.py
+++ b/tests/unit/proxy/management_helpers/test_customer_hierarchy.py
@@ -243,6 +243,7 @@ class Database:
self.litellm_customerteamtable = Table("customer_team_id", self)
self.litellm_customermembertable = Table("customer_member_id", self)
self.litellm_budgettable = Table("budget_id", self)
+ self.litellm_budgetwindowspend = Table("entity_id", self)
self.litellm_verificationtoken = Table("token", self)
self.litellm_projecttable = Table("project_id", self)
self.litellm_customerbudgetincreaserequest = Table("request_id", self)