Spend Tracking & Cost Attribution

Relevant source files

The following files were used as context for generating this wiki page:

• schema.prisma
• litellm/proxy/management_endpoints/usage_endpoints/ai_usage_chat.py
• ui/litellm-dashboard/src/components/usage.tsx
• ui/litellm-dashboard/src/components/UsagePage/types.ts
• ui/litellm-dashboard/src/components/UsagePage/components/UsagePageView.tsx
• ui/litellm-dashboard/src/components/EntityUsageExport/utils.test.ts

Spend tracking and cost attribution in LiteLLM is a multi-layered system designed to provide granular visibility into LLM usage and associated financial expenditures. The system captures raw request metadata, calculates costs based on token usage, and aggregates these metrics into specific dimensions—including Users, Teams, Organizations, and Tags—to facilitate enterprise-grade financial governance and chargeback reporting.

The architecture relies on a persistent storage layer managed via Prisma, which stores both high-resolution transaction logs (LiteLLM_SpendLogs) and optimized aggregate tables. This allows the system to scale effectively for high-volume environments (1M+ rows) while maintaining responsive dashboards and AI-powered analytical capabilities.

Sources: schema.prisma:983-1025, ui/litellm-dashboard/src/components/UsagePage/components/UsagePageView.tsx:10-20

Data Architecture & Persistence

The system architecture distinguishes between individual transaction logging and optimized daily aggregation. Raw metrics are initially captured in the LiteLLM_SpendLogs table, providing a full audit trail for every LLM call.

Raw Transaction Logging

The LiteLLM_SpendLogs model serves as the primary source of truth, recording the following key metrics for every request:

• Monetary Spend: Calculated cost for the individual call.
• Token Metrics: Breakdown of prompt, completion, and total tokens.
• Performance Metadata: Request duration, latency, and cache status (hit/key).
• Attribution Data: Links to api_key, user, team_id, organization_id, and end_user.

Sources: schema.prisma:983-1015

Aggregate Metrics Layer

To support high-performance dashboarding and AI-driven queries, LiteLLM maintains specialized daily aggregate tables. These tables use composite unique keys to prevent duplication and ensure fast retrieval across time-series data.

Spend Metrics & Token Tracking

LiteLLM tracks a comprehensive set of metrics beyond simple prompt/completion counts. The system distinguishes between standard token usage and cache-related efficiency.

Metric Field	Description
spend	The total cost in USD for the request or period.
api_requests	Total number of calls made to LLM providers.
successful_requests	Total calls that returned a valid response.
failed_requests	Calls resulting in errors (routing, provider down, etc.).
cache_read_input_tokens	Tokens retrieved from cache (cost-saving).
cache_creation_input_tokens	Tokens written to cache for future use.

Sources: ui/litellm-dashboard/src/components/UsagePage/types.ts:1-11, schema.prisma:1129-1133

Attribution Dimensions

LiteLLM allows costs to be attributed across several logical entities, enabling complex organizational reporting.

1. Team-Based Attribution

Costs are grouped by team_id. The system supports tracking daily spend per team and provides comparative lists to identify high-spend groups within an organization.
Sources: ui/litellm-dashboard/src/components/usage.tsx:430-450

2. Customer (End-User) Attribution

Attribution is performed when a user parameter is passed in LLM calls. This enables SaaS providers to track spend per customer.
Sources: ui/litellm-dashboard/src/components/usage.tsx:642-648

3. Tag-Based Attribution

Requests can be labeled with custom tags (e.g., "production", "feature-x"). LiteLLM also automatically tracks reusable credentials as tags, prefixed with Credential:.
Sources: ui/litellm-dashboard/src/components/UsagePage/components/UsagePageView.tsx:613-625

AI-Powered Usage Analytics

The system includes an "AI Usage Chat" feature that utilizes LLM tool calling to answer natural language questions about spend data.

Tool Registry for AI Insights

The backend defines specific tools that the AI assistant can invoke to retrieve data from the Prisma aggregates.

Tool Name	Scope	Description
get_usage_data	Global/User	Fetches spend, token counts, and breakdowns by model/provider.
get_team_usage_data	Admin	Provides usage breakdown across specific team IDs.
get_tag_usage_data	Admin	Analyzes spend for specific labels (e.g., features, envs).

Sources: litellm/proxy/management_endpoints/usage_endpoints/ai_usage_chat.py:90-135

Data Summarization Flow

When the AI assistant fetches data, the system summarizes raw JSON into ranked text summaries (e.g., "Top Models by Spend") before the LLM generates a final response.
Sources: litellm/proxy/management_endpoints/usage_endpoints/ai_usage_chat.py:228-255

Visualization and Reporting

The LiteLLM Dashboard provides a visual interface for spend monitoring, utilizing the /user/daily/activity endpoint for efficient data retrieval.

Export Capabilities

The system supports exporting spend data in CSV and JSON formats. These exports include comprehensive metadata such as:

• Date Range: The specific interval for the export.
• Filters Applied: Any user or team-level exclusions.
• Summary Metrics: Aggregated totals for spend, tokens, and success rates.

Sources: ui/litellm-dashboard/src/components/EntityUsageExport/utils.test.ts:510-530

Conclusion

The Spend Tracking & Cost Attribution system provides a robust framework for monitoring LLM costs. By utilizing optimized aggregate tables for high-volume scale and providing flexible attribution via Teams and Tags, LiteLLM enables organizations to manage their AI budget with precision. The integration of AI-powered chat and detailed dashboard reporting ensures that stakeholders at all levels have accessible and accurate financial insights.