LLM Usage
Documentation for LLM Usage
Base path: /api/v1/llm-usage
Provides a summary of LLM (Large Language Model) token usage and costs for the active organization.
All endpoints require JWT authentication and an x-active-org header.
Endpoints Overview
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/llm-usage/summary | Get aggregated LLM usage summary |
GET /api/v1/llm-usage/summary
Returns aggregated LLM usage statistics for the active organization. Supports date range filtering and various grouping options.
Authentication
Requires JWT (authMiddleware).
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
startDate | string (ISO 8601) | No | Filter usage from this date (inclusive) |
endDate | string (ISO 8601) | No | Filter usage until this date (inclusive) |
groupBy | string | No | Group results by: "model", "source", "user", or "day" |
Response 200 OK
Without grouping:
json
With groupBy=model:
json
Response fields:
| Field | Type | Description |
|---|---|---|
totals | object | Aggregated totals across all usage |
totals.inputTokens | number | Total input (prompt) tokens |
totals.cachedInputTokens | number | Cached input tokens (counted at reduced cost) |
totals.outputTokens | number | Total output (completion) tokens |
totals.thinkingTokens | number | Thinking/reasoning tokens (for supported models) |
totals.costMicros | number | null | Total cost in micro-dollars (1,000,000 = $1.00) |
breakdowns | array | null | Per-group breakdown (only when groupBy is specified) |
Breakdown item fields:
| Field | Type | Description |
|---|---|---|
group | string | The group value (model name, source, user ID, or date) |
inputTokens | number | Input tokens for this group |
cachedInputTokens | number | Cached input tokens for this group |
outputTokens | number | Output tokens for this group |
thinkingTokens | number | Thinking tokens for this group |
costMicros | number | null | Cost in micro-dollars for this group |
GroupBy Values
| Value | Description |
|---|---|
model | Group by AI model name (e.g. "GPT-4o", "Claude-3-5-Sonnet") |
source | Group by usage source (e.g. "chat", "chain:schedule-parser", "rules-chat") |
user | Group by user ID |
day | Group by calendar day (ISO 8601 date string) |
Example
bash
Cost Calculation Note
Costs are tracked in micro-dollars to avoid floating-point precision issues. To convert to dollars:
javascript
If costMicros is null, cost tracking was not available for those records (e.g., for models where pricing is not configured).
api-docs/llm-usage