Usage tracking API

The usage tracking system records per-event token consumption and tool execution metrics. You can query aggregated data by agent, model, or time period.

The usage tracker records events to a PostgreSQL database whenever an AI completion or tool call is made. The endpoints below are read-only query APIs for retrieving aggregated usage data. When no real usage data exists yet, the cost dashboard returns sample data with a isMockData: true flag.

Test usage logging (deprecated)

This endpoint was removed in the March 2026 security audit and is no longer available. Requests to this path return 404. Use the cost dashboard endpoint to verify that usage tracking is working.

POST /api/test-usage

~~A debug endpoint that fires a single test event through the usage logging pipeline.~~

Cost dashboard

GET /api/dashboard/cost

Returns aggregated cost, token, and call data for the cost dashboard. Breaks down spending by agent, model, and day. Requires session authentication. When no usage data is available, the endpoint returns realistic sample data with isMockData set to true and a message field explaining that usage tracking is not yet configured.

Query parameters

Parameter	Type	Default	Description
`period`	string	`7d`	Time window for the aggregation. Accepted values: `7d` (last 7 days), `30d` (last 30 days), `mtd` (month to date).

Response

{
  "period": "7d",
  "summary": {
    "totalCost": 13.68,
    "totalTokens": 4560000,
    "totalCalls": 1946,
    "avgCostPerCall": 0.007
  },
  "agents": [
    {
      "name": "Atlas",
      "tokens": 2840000,
      "cost": 8.52,
      "calls": 1247,
      "avgCostPerCall": 0.0068,
      "model": "claude-3-7-sonnet"
    }
  ],
  "daily": [
    {
      "date": "Mar 17",
      "cost": 1.42,
      "tokens": 380000
    }
  ],
  "modelBreakdown": [
    {
      "model": "claude-3-7-sonnet",
      "percent": 68,
      "cost": 9.30
    }
  ],
  "isMockData": false
}

Response fields

Field	Type	Description
`period`	string	The requested period echoed back (`7d`, `30d`, or `mtd`)
`summary.totalCost`	number	Total cost in USD for the period
`summary.totalTokens`	number	Total tokens (input + output) consumed
`summary.totalCalls`	number	Total API calls made
`summary.avgCostPerCall`	number	Blended average cost per call in USD
`agents`	array	Per-agent cost breakdown, sorted by cost descending
`agents[].name`	string	Agent name or identifier
`agents[].tokens`	number	Total tokens consumed by the agent
`agents[].cost`	number	Total cost in USD attributed to the agent
`agents[].calls`	number	Number of API calls made by the agent
`agents[].avgCostPerCall`	number	Average cost per call for the agent
`agents[].model`	string	Primary model used by the agent
`daily`	array	Daily cost and token totals
`daily[].date`	string	Formatted date label (e.g. `"Mar 17"`)
`daily[].cost`	number	Cost in USD for that day
`daily[].tokens`	number	Total tokens consumed that day
`modelBreakdown`	array	Cost breakdown by model, sorted by cost descending
`modelBreakdown[].model`	string	Model identifier
`modelBreakdown[].percent`	number	Percentage of total cost attributed to this model
`modelBreakdown[].cost`	number	Cost in USD for this model
`isMockData`	boolean	`true` when the response contains sample data because no real usage data is available
`message`	string \| undefined	Present only when `isMockData` is `true`. Explains that sample data is being returned.

Errors

Code	Description
500	Failed to fetch cost data

The remaining endpoints on this page are planned for a future release. They are not yet available. Usage events are recorded internally but these query APIs have not been deployed. This section documents the intended specification for reference.

All query endpoints below require bearer token authentication and are served by the backend API.

Usage summary

GET /api/usage/summary

Returns daily aggregated token usage and cost data across all agents and models.

Query parameters

Parameter	Type	Default	Description
`days`	integer	`30`	Number of days of history to return

Response

[
  {
    "date": "2026-03-22",
    "agent_id": "agent_abc",
    "model": "openrouter/anthropic/claude-sonnet-4",
    "provider": "openrouter",
    "input_tokens": 15200,
    "output_tokens": 3400,
    "total_tokens": 18600,
    "cost_usd": 0.042,
    "turn_count": 12
  }
]

Response fields

Field	Type	Description
`date`	string	Date in `YYYY-MM-DD` format
`agent_id`	string \| null	Agent that generated the usage, or `null` for unattributed events
`model`	string	Model identifier
`provider`	string	AI provider name
`input_tokens`	number	Total input tokens for the day
`output_tokens`	number	Total output tokens for the day
`total_tokens`	number	Sum of all token types (input, output, cache read, cache write)
`cost_usd`	number	Estimated cost in USD
`turn_count`	number	Number of individual completion calls

Usage by agent

GET /api/usage/by-agent/:agentId

Returns token usage grouped by model for a specific agent.

Path parameters

Parameter	Type	Description
`agentId`	string	ID of the agent to query

Query parameters

Parameter	Type	Default	Description
`days`	integer	`30`	Number of days of history to include

Response

[
  {
    "model": "openrouter/anthropic/claude-sonnet-4",
    "provider": "openrouter",
    "input_tokens": 45000,
    "output_tokens": 12000,
    "total_tokens": 57000,
    "cost_usd": 0.13,
    "events": 48
  }
]

Response fields

Field	Type	Description
`model`	string	Model identifier
`provider`	string	AI provider name
`input_tokens`	number	Total input tokens
`output_tokens`	number	Total output tokens
`total_tokens`	number	Total tokens across all types
`cost_usd`	number	Estimated cost in USD
`events`	number	Number of usage events

Usage by model

GET /api/usage/by-model

Returns token usage aggregated by model across all agents.

Query parameters

Parameter	Type	Default	Description
`days`	integer	`30`	Number of days of history to include

Response

[
  {
    "model": "openrouter/anthropic/claude-sonnet-4",
    "provider": "openrouter",
    "input_tokens": 120000,
    "output_tokens": 35000,
    "total_tokens": 155000,
    "cost_usd": 0.35,
    "turns": 200
  }
]

Response fields

Field	Type	Description
`model`	string	Model identifier
`provider`	string	AI provider name
`input_tokens`	number	Total input tokens
`output_tokens`	number	Total output tokens
`total_tokens`	number	Total tokens across all types
`cost_usd`	number	Estimated cost in USD
`turns`	number	Total completion turns

Daily totals

GET /api/usage/daily

Returns total token usage and cost per day.

Query parameters

Parameter	Type	Default	Description
`days`	integer	`7`	Number of days of history to return

Response

[
  {
    "date": "2026-03-22",
    "total_tokens": 85000,
    "cost_usd": 0.19,
    "turns": 72
  },
  {
    "date": "2026-03-21",
    "total_tokens": 62000,
    "cost_usd": 0.14,
    "turns": 55
  }
]

Response fields

Field	Type	Description
`date`	string	Date in `YYYY-MM-DD` format
`total_tokens`	number	Total tokens used that day
`cost_usd`	number	Estimated cost in USD
`turns`	number	Total completion turns

Tool stats

GET /api/usage/tools

Returns aggregated tool execution statistics, optionally filtered by agent.

Query parameters

Parameter	Type	Default	Description
`agentId`	string	—	Filter results to a specific agent. Omit for all agents.
`days`	integer	`7`	Number of days of history to include

Response

[
  {
    "tool_name": "web_search",
    "calls": 150,
    "successes": 142,
    "avg_ms": 1230.5
  },
  {
    "tool_name": "code_edit",
    "calls": 85,
    "successes": 83,
    "avg_ms": 450.2
  }
]

Response fields

Field	Type	Description
`tool_name`	string	Name of the tool
`calls`	number	Total number of invocations
`successes`	number	Number of successful invocations
`avg_ms`	number	Average execution duration in milliseconds

Usage event schema

Each usage event is stored as a row in the usage_logs table (Prisma model name: UsageLog). Events are recorded automatically whenever an AI completion is made (for example, from the demo chat endpoint or agent chat). Cost is calculated at write time using per-model pricing rates.

The usage_logs table is created via a dedicated SQL migration (20260323000000_add_usage_logs) rather than through Prisma’s schema push. This ensures the table is created reliably across deployments without requiring Prisma to manage the migration state.

Server-side logging

Every usage event emits a structured log line to the server console when it is recorded. This makes it possible to verify that the usage tracking pipeline is working without querying the database. Success log format:

[UsageLogger] Logging: <agentId> | <model> | <inputTokens>+<outputTokens> tokens | $<cost>

For example:

[UsageLogger] Logging: demo-chat | gpt-4o | 450+120 tokens | $0.004050

If the database write fails, an error is logged instead:

[UsageLogger] Failed to log usage: <error message>

Because usage recording is fire-and-forget (it never blocks the API response), these log lines are the primary way to diagnose write failures. Monitor your server logs for [UsageLogger] Failed to log usage entries if usage data appears to be missing from the cost dashboard.

Cost dashboard logging

The cost dashboard endpoint emits its own diagnostic log lines prefixed with [Cost API]. These help you verify that the aggregation query is running and returning data. Query result log:

[Cost API] Found <count> usage logs

For example:

[Cost API] Found 42 usage logs

If the Prisma query fails, the endpoint logs the error and falls back to sample data:

[Cost API] Prisma error: <error message>

If the entire handler fails, a general error is logged and a 500 response is returned:

[Cost API] Error: <error message>

Field	Type	Description
`id`	integer	Auto-incrementing primary key
`user_id`	varchar(255)	User who triggered the event
`agent_id`	varchar(255)	Agent that triggered the completion
`model`	varchar(100)	Model identifier (for example `anthropic/claude-sonnet-4.5`)
`input_tokens`	integer	Number of input (prompt) tokens. Defaults to `0`.
`output_tokens`	integer	Number of output (completion) tokens. Defaults to `0`.
`cost_usd`	decimal(10,6)	Computed cost in USD (six decimal places). Defaults to `0`.
`endpoint`	varchar(255) \| null	API route that generated the event (for example `/api/demo/chat`)
`latency_ms`	integer \| null	Response latency in milliseconds
`success`	boolean	Whether the completion succeeded. Defaults to `true`.
`error_message`	text \| null	Error description when `success` is `false`
`created_at`	timestamp	Timestamp when the event was recorded. Defaults to `NOW()`.

When accessing the table through the Prisma ORM, use the camelCase field names (userId, agentId, inputTokens, etc.). When writing raw SQL queries, use the snake_case column names shown above (user_id, agent_id, input_tokens, etc.).

The table is indexed on user_id, agent_id, created_at, and the composite pairs (user_id, created_at) and (agent_id, created_at) for efficient time-range queries.

The usage event schema was updated in the March 2026 release. The previous fields session_id, session_key, cache_read_tokens, cache_write_tokens, and total_tokens are no longer recorded. Use input_tokens + output_tokens to calculate total tokens.

Tool event schema

Each tool event records:

Field	Type	Description
`session_id`	string \| null	Session that triggered the tool call
`agent_id`	string \| null	Agent that invoked the tool
`tool_name`	string	Name of the tool
`success`	boolean	Whether the tool call succeeded
`duration_ms`	number \| null	Execution time in milliseconds

Errors

All usage tracking endpoints return the following error codes:

Code	Description
401	Unauthorized — missing or invalid bearer token
500	Database query failed

Getting Started

Core Concepts

Integrations

Core Services

Payments

API Reference

MCP

Security

​Usage tracking API

​Test usage logging (deprecated)

​Cost dashboard

​Query parameters

​Response

​Response fields

​Errors

​Usage summary

​Query parameters

​Response

​Response fields

​Usage by agent

​Path parameters

​Query parameters

​Response

​Response fields

​Usage by model

​Query parameters

​Response

​Response fields

​Daily totals

​Query parameters

​Response

​Response fields

​Tool stats

​Query parameters

​Response

​Response fields

​Usage event schema

​Server-side logging

​Cost dashboard logging

​Tool event schema

​Errors

Usage tracking API

Test usage logging (deprecated)

Cost dashboard

Query parameters

Response

Response fields

Errors

Usage summary

Query parameters

Response

Response fields

Usage by agent

Path parameters

Query parameters

Response

Response fields

Usage by model

Query parameters

Response

Response fields

Daily totals

Query parameters

Response

Response fields

Tool stats

Query parameters

Response

Response fields

Usage event schema

Server-side logging

Cost dashboard logging

Tool event schema

Errors