# Cost Analytics
Relevant source files The following files were used as context for generating this wiki page: * [docs/PRDS/52-UNIFIED-ANALYTICS.md](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/docs/PRDS/52-UNIFIED-ANALYTICS.md) * [frontend/app/analytics/page.tsx](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/frontend/app/analytics/page.tsx) * [frontend/components/analytics/analytics-admin.tsx](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/frontend/components/analytics/analytics-admin.tsx) * [frontend/components/analytics/analytics-agents.tsx](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/frontend/components/analytics/analytics-agents.tsx) * [frontend/components/analytics/analytics-costs.tsx](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/frontend/components/analytics/analytics-costs.tsx) * [frontend/components/analytics/analytics-documents.tsx](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/frontend/components/analytics/analytics-documents.tsx) * [frontend/components/analytics/analytics-memory.tsx](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/frontend/components/analytics/analytics-memory.tsx) * [frontend/components/analytics/analytics-openrouter-credits.tsx](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/frontend/components/analytics/analytics-openrouter-credits.tsx) * [frontend/components/analytics/analytics-overview.tsx](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/frontend/components/analytics/analytics-overview.tsx) * [frontend/components/analytics/analytics-page.tsx](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/frontend/components/analytics/analytics-page.tsx) * [frontend/components/analytics/analytics-pandas-chart.tsx](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/frontend/components/analytics/analytics-pandas-chart.tsx) * [frontend/components/analytics/analytics-plan-usage.tsx](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/frontend/components/analytics/analytics-plan-usage.tsx) * [frontend/components/analytics/analytics-recommendations.tsx](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/frontend/components/analytics/analytics-recommendations.tsx) * [frontend/components/analytics/analytics-workflows.tsx](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/frontend/components/analytics/analytics-workflows.tsx) * [frontend/components/dashboard/widgets/system-health-widget.tsx](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/frontend/components/dashboard/widgets/system-health-widget.tsx) * [frontend/components/knowledge/QueryTemplatesGrid.tsx](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/frontend/components/knowledge/QueryTemplatesGrid.tsx) * [frontend/components/system/rag-configuration.tsx](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/frontend/components/system/rag-configuration.tsx) * [frontend/hooks/use-unified-analytics.ts](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/frontend/hooks/use-unified-analytics.ts) * [orchestrator/api/llm\_analytics.py](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/orchestrator/api/llm_analytics.py) * [orchestrator/core/llm/openrouter\_analytics.py](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/orchestrator/core/llm/openrouter_analytics.py)
This document covers the **cost analytics subsystem** that tracks, analyzes, and visualizes LLM API costs across the platform. Cost analytics provides workspace-level cost breakdowns by model, provider, agent, and time period, along with projections, optimization recommendations, and OpenRouter integration for credit tracking. *** ## Cost Tracking Data Model All LLM API calls are logged to the `LLMUsage` table with cost attribution. Each row captures detailed metadata for granular reporting. | Field | Type | Description | | --------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `workspace_id` | UUID | Workspace scope for multi-tenancy [orchestrator/api/llm\_analytics.py:95-96](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md) | | `agent_id` | Integer | Optional agent that initiated the request [orchestrator/api/llm\_analytics.py:103-103](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md) | | `model_id` | String | Model identifier (e.g., `openai/gpt-4o`) [orchestrator/api/llm\_analytics.py:101-101](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md) | | `provider` | String | Provider name (`openai`, `anthropic`, `openrouter`) [orchestrator/api/llm\_analytics.py:102-102](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md) | | `tier` | String | Model tier (`fast`, `smart`, `aggregator`) [orchestrator/api/llm\_analytics.py:104-104](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md) | | `input_tokens` | Integer | Prompt tokens consumed [orchestrator/api/llm\_analytics.py:114-114](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md) | | `output_tokens` | Integer | Completion tokens generated [orchestrator/api/llm\_analytics.py:115-115](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md) | | `total_tokens` | Integer | Sum of input + output [orchestrator/api/llm\_analytics.py:116-116](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md) | | `input_cost` | Float | Cost for input tokens [orchestrator/api/llm\_analytics.py:168-168](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md) | | `output_cost` | Float | Cost for output tokens [orchestrator/api/llm\_analytics.py:169-169](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md) | | `total_cost` | Float | Sum of input + output costs [orchestrator/api/llm\_analytics.py:117-117](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md) | | `is_byok` | Boolean | True if user provided their own API key [orchestrator/api/llm\_analytics.py:105-105](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md) | | `latency_ms` | Float | Request duration [orchestrator/api/llm\_analytics.py:215-215](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md) | | `status` | String | `success` or `error` [orchestrator/api/llm\_analytics.py:219-219](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md) | | `created_at` | Timestamp | When the request occurred [orchestrator/api/llm\_analytics.py:121-121](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md) | Sources: [orchestrator/api/llm\_analytics.py:21-21](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md), [orchestrator/api/llm\_analytics.py:100-121](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md) *** ## Cost Analytics Architecture ### Frontend to Backend Flow The analytics dashboard utilizes a series of React Query hooks defined in `use-unified-analytics.ts` to fetch aggregated data from the FastAPI backend. All queries are scoped using `wsScope()` to ensure workspace isolation by calling `getAdminWorkspaceOverride()` [frontend/hooks/use-unified-analytics.ts:12-14](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md). Title: Cost Analytics Data Flow ```mermaid graph TB subgraph "Frontend - [analytics-costs.tsx]" CostsUI["AnalyticsCosts Component"] CostHooks["useCostAnalyticsUnified
useCostProjections
useModelComparison
useDailyCostByModel"] end subgraph "API Client & Hooks - [use-unified-analytics.ts]" QueryKeys["unifiedAnalyticsKeys.costs(days)
unifiedAnalyticsKeys.costProjections(period)
unifiedAnalyticsKeys.modelComparison(modelIds, period)"] APIClient["apiClient.request()"] end subgraph "Backend - [llm_analytics.py]" UsageEndpoint["GET /api/analytics/llm/usage"] CostsEndpoint["GET /api/analytics/llm/costs"] SummaryEndpoint["GET /api/analytics/llm/summary"] ProjectionsEndpoint["GET /api/analytics/llm/projections"] ComparisonEndpoint["GET /api/analytics/llm/comparison"] end subgraph "Database Layer - [core/models/core.py]" LLMUsageTable[("LLMUsage Table
workspace_id scoped")] Aggregations["SQLAlchemy aggregations:
func.sum(total_cost)
func.count()
func.avg()
group_by model/provider/agent"] end CostsUI --> CostHooks CostHooks --> QueryKeys QueryKeys --> APIClient APIClient --> UsageEndpoint APIClient --> CostsEndpoint APIClient --> SummaryEndpoint APIClient --> ProjectionsEndpoint APIClient --> ComparisonEndpoint UsageEndpoint --> Aggregations CostsEndpoint --> Aggregations SummaryEndpoint --> Aggregations ProjectionsEndpoint --> Aggregations ComparisonEndpoint --> Aggregations Aggregations --> LLMUsageTable ``` Sources: [orchestrator/api/llm\_analytics.py:28-30](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md), [orchestrator/api/llm\_analytics.py:87-191](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md), [frontend/components/analytics/analytics-costs.tsx:44-50](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md), [frontend/hooks/use-unified-analytics.ts:18-43](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md) *** ## Cost Breakdown Queries ### Usage by Dimension The `get_usage` endpoint in `llm_analytics.py` aggregates tokens and costs by a specified dimension using SQLAlchemy's `group_by`. Supported dimensions include `model`, `provider`, `agent`, and `tier` [orchestrator/api/llm\_analytics.py:90-90](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md). ```python # Available grouping dimensions group_col_map = { "model": LLMUsage.model_id, "provider": LLMUsage.provider, "agent": LLMUsage.agent_id, "tier": LLMUsage.tier, "is_byok": LLMUsage.is_byok, "request_type": LLMUsage.request_type, } ``` Response schema is defined by the `UsageGroup` Pydantic model, providing a unified structure for charts and tables [orchestrator/api/llm\_analytics.py:34-41](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md). Sources: [orchestrator/api/llm\_analytics.py:34-41](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md), [orchestrator/api/llm\_analytics.py:87-138](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md) *** ### Summary Endpoint The `get_summary` function provides dashboard-level aggregates, including top models and cost trends over a period (e.g., `7d`, `30d`) [orchestrator/api/llm\_analytics.py:194-204](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md). Title: Summary Aggregation Logic ```mermaid graph LR subgraph "GET /api/analytics/llm/summary - [llm_analytics.py]" Query["SQLAlchemy Query:
filter(workspace_id, created_at >= since)"] subgraph "Aggregates" TotalReqs["COUNT(id) → total_requests"] TotalTokens["SUM(total_tokens) → total_tokens"] TotalCost["SUM(total_cost) → total_cost"] AvgLatency["AVG(latency_ms) → avg_latency_ms"] ErrorRate["COUNT(status='error') / Total"] end TopModels["Top 5 models by cost:
GROUP BY model_id
ORDER BY SUM(total_cost) DESC"] CostTrend["Daily cost trend:
GROUP BY DATE(created_at)"] end Query --> TotalReqs Query --> TotalTokens Query --> TotalCost Query --> AvgLatency Query --> ErrorRate Query --> TopModels Query --> CostTrend ``` Sources: [orchestrator/api/llm\_analytics.py:194-261](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md) *** ## OpenRouter Integration The platform includes deep integration with OpenRouter for credit management and activity synchronization. ### Activity Sync Pipeline The `OpenRouterAnalyticsService` fetches usage data from OpenRouter's `/activity` endpoint and upserts it into the local `LLMUsage` table. This is deduplicated by `workspace_id`, `model_id`, and `created_at` [orchestrator/core/llm/openrouter\_analytics.py:97-106](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md). Title: OpenRouter Sync Architecture ```mermaid graph TB subgraph "OpenRouter Cloud" OR_Activity["/api/v1/activity"] OR_Credits["/api/v1/credits"] end subgraph "Orchestrator Backend - [openrouter_analytics.py]" OR_Service["OpenRouterAnalyticsService"] SyncTask["sync_activity()"] DB_Upsert["_upsert_activity_rows()"] end subgraph "Data Store - [core/models/core.py]" UsageTable[("LLMUsage Table")] end OR_Activity --> OR_Service OR_Service --> SyncTask SyncTask --> DB_Upsert DB_Upsert --> UsageTable OR_Credits --> OR_Service ``` Sources: [orchestrator/core/llm/openrouter\_analytics.py:27-148](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md), [orchestrator/api/llm\_analytics.py:668-689](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md) *** ## Plan Usage and Projections The system monitors workspace resource consumption against defined plan limits. * **Plan Usage Tracking**: The `AnalyticsPlanUsage` component visualizes consumption for agents, storage, and API calls [frontend/components/analytics/analytics-plan-usage.tsx:73-112](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md). * **Projections**: The `useCostProjections` hook retrieves forecasted spending based on current consumption rates [frontend/hooks/use-unified-analytics.ts:40-40](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md). * **Model Comparison**: Allows users to compare costs and performance across multiple model IDs over a specific period [frontend/hooks/use-unified-analytics.ts:39-39](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md). Sources: [frontend/components/analytics/analytics-plan-usage.tsx:9-116](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md), [frontend/hooks/use-unified-analytics.ts:38-41](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md) *** ## Admin Analytics Super admins have access to a platform-wide dashboard via `AnalyticsAdmin`, providing visibility into cross-workspace costs and plan distribution. * **Cross-Workspace Stats**: Aggregates costs, requests, and agent counts across all workspaces [frontend/components/analytics/analytics-admin.tsx:183-194](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md). * **Plan Distribution**: Visualizes the breakdown of workspaces across `starter`, `pilot`, `pro`, and `enterprise` tiers [frontend/components/analytics/analytics-admin.tsx:199-206](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md). * **Top Spenders**: A sortable table identifying the highest-cost workspaces [frontend/components/analytics/analytics-admin.tsx:173-178](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md). Sources: [frontend/components/analytics/analytics-admin.tsx:164-210](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md), [frontend/hooks/use-unified-analytics.ts:42-42](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md) *** ## Recommendations and Optimization The `AnalyticsRecommendations` system analyzes usage patterns to suggest cost-saving measures. * **Recommendation Types**: Includes `cost`, `performance`, `document`, and `quota` optimizations [frontend/components/analytics/analytics-recommendations.tsx:21-21](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md). * **Impact Assessment**: Quantifies the potential benefit of an action (e.g., "Switch Agent X to a cheaper LLM") [frontend/components/analytics/analytics-recommendations.tsx:24-24](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md). * **Potential Savings**: The backend `Recommendation` model specifically tracks `potential_savings` to prioritize optimizations [orchestrator/api/llm\_analytics.py:65-65](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md). Sources: [orchestrator/api/llm\_analytics.py:61-68](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md), [frontend/components/analytics/analytics-recommendations.tsx:19-169](/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md) *** --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.automatos.app/automatos-ai-docs/design-docs/analytics-monitoring/cost-analytics.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.