Usage
The usage API tracks token consumption and costs across all AI-powered features: chat conversations, cron agents, and memory extraction. Use the list endpoint for paginated records and the stats endpoint for aggregated analytics.
Endpoints
List Usage Records
GET /api/usage
Retrieve paginated token usage records with optional filtering by source, search text, and time period.
Authentication: Required
Query Parameters:
| Param | Type | Required | Description |
|---|---|---|---|
period | string | No | Time window: 24h, 7d (default), or 30d |
source | string | No | Filter by source: chat, agent, or memory_extraction |
search | string | No | Search by source name (ILIKE) |
page | number | No | Page number, starts at 1 (default) |
limit | number | No | Results per page (default 20, max 100) |
Response: 200 OK
{
"data": [
{
"id": "uuid",
"source": "chat",
"sourceId": "conversation-uuid",
"sourceName": "Help me refactor the auth module",
"inputTokens": 12500,
"outputTokens": 3200,
"costUsd": 0.042,
"durationMs": 8500,
"numTurns": 3,
"createdAt": "2026-02-18T12:00:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 85,
"totalPages": 5
}
}
Usage Stats
GET /api/usage/stats
Aggregated usage analytics for a time period. Includes daily/hourly time-series data, breakdown by source, and top consumers.
Authentication: Required
Query Parameters:
| Param | Type | Required | Description |
|---|---|---|---|
period | string | No | Time window: 24h, 7d (default), or 30d |
granularity | string | No | Bucket size: daily (default) or hourly |
tzOffset | number | No | Client timezone offset in minutes from UTC (e.g., -300 for EST) |
Response: 200 OK
{
"data": {
"totalCostUsd": 2.45,
"totalInputTokens": 580000,
"totalOutputTokens": 145000,
"totalCalls": 67,
"avgCostPerCall": 0.0366,
"dailyUsage": [
{
"date": "2026-02-17",
"chat": 0.85,
"agent": 0.32,
"memory": 0.05,
"totalCost": 1.22,
"inputTokens": 290000,
"outputTokens": 72000,
"calls": 34
}
],
"bySource": [
{ "source": "chat", "cost": 1.80, "calls": 45, "tokens": 520000 },
{ "source": "agent", "cost": 0.55, "calls": 18, "tokens": 180000 },
{ "source": "memory_extraction", "cost": 0.10, "calls": 4, "tokens": 25000 }
],
"topConsumers": [
{ "name": "Refactor auth module", "source": "chat", "cost": 0.42, "calls": 5 },
{ "name": "Daily standup agent", "source": "agent", "cost": 0.25, "calls": 7 }
]
}
}
Pass tzOffset to align daily buckets with the user's local timezone. Without it, buckets are based on UTC. The value uses the same sign convention as Date.getTimezoneOffset() -- positive values are behind UTC.
Sources
| Source | Description |
|---|---|
chat | Interactive chat conversations via the WebSocket chat protocol |
agent | Automated cron agent runs |
memory_extraction | AI-powered memory extraction from session transcripts |
Type Reference
See Database Schema for the full token_usage table definition.
interface TokenUsageRecord {
id: string
source: 'chat' | 'agent' | 'memory_extraction'
sourceId?: string // ID of the conversation or agent run
sourceName?: string // Human-readable label
inputTokens: number
outputTokens: number
costUsd: number
durationMs?: number
numTurns?: number
createdAt: Date
}