Tokens API - Mission Control

Overview

The Tokens API provides comprehensive token usage tracking and cost analysis across all agents, models, and sessions. Track consumption patterns, analyze costs per agent, and export data for billing and optimization.

Authentication

All token endpoints require authentication via:

Session Cookie: mc-session (set after login)
API Key: x-api-key header

Minimum role requirements:

GET: Viewer role
POST: Operator role

Query Token Usage

GET /api/tokens

Query token usage with multiple action modes for different use cases.

Authorization: Viewer role required

Query Parameters

action

string

default:"list"

Query action to perform

Show Available actions

list - List recent token usage records
stats - Get aggregated statistics
agent-costs - Per-agent cost breakdown with timelines
export - Export data (JSON or CSV)
trends - Hourly usage trends (last 24 hours)

timeframe

string

default:"all"

Time window for data filtering

Show Allowed values

hour - Last 60 minutes
day - Last 24 hours
week - Last 7 days
month - Last 30 days
all - All recorded data

format

string

default:"json"

Export format (only for action=export)

Show Allowed values

json - JSON format
csv - CSV format

Action: List

List Token Usage Records

Retrieve recent token usage records with pagination.

Request

GET /api/tokens?action=list&timeframe=day&limit=100

Response Fields

usage

array

Array of token usage records (max 100)

Show TokenUsageRecord Object

string

Unique record identifier

model

string

Model identifier (e.g., “claude-sonnet-4”, “gpt-4”)

sessionId

string

Session identifier

agentName

string

Agent name extracted from session ID

timestamp

integer

Unix timestamp (milliseconds)

inputTokens

integer

Input tokens consumed

outputTokens

integer

Output tokens generated

totalTokens

integer

Total tokens (input + output)

cost

number

Estimated cost in USD

operation

string

Operation type (e.g., “chat_completion”, “heartbeat”)

duration

number

Request duration in milliseconds (optional)

total

integer

Total number of records matching filters

timeframe

string

Applied timeframe filter

Example Request

curl -X GET "https://your-domain.com/api/tokens?action=list&timeframe=day" \
  -H "x-api-key: your-api-key"

Example Response

{
  "usage": [
    {
      "id": "db-12345",
      "model": "claude-sonnet-4",
      "sessionId": "code-reviewer:chat",
      "agentName": "code-reviewer",
      "timestamp": 1709856000000,
      "inputTokens": 1523,
      "outputTokens": 842,
      "totalTokens": 2365,
      "cost": 0.007095,
      "operation": "heartbeat",
      "duration": 1250
    }
  ],
  "total": 1,
  "timeframe": "day"
}

Action: Stats

Get Aggregated Statistics

Retrieve aggregated token usage and cost statistics.

Request

GET /api/tokens?action=stats&timeframe=week

Response Fields

summary

object

Overall statistics

Show TokenStats Object

totalTokens

integer

Total tokens consumed

totalCost

number

Total cost in USD

requestCount

integer

Number of requests

avgTokensPerRequest

integer

Average tokens per request

avgCostPerRequest

number

Average cost per request

models

object

Statistics broken down by model (key: model name, value: TokenStats)

sessions

object

Statistics broken down by session (key: session ID, value: TokenStats)

agents

object

Statistics broken down by agent (key: agent name, value: TokenStats)

timeframe

string

Applied timeframe filter

recordCount

integer

Number of records analyzed

Example Request

cURL

curl -X GET "https://your-domain.com/api/tokens?action=stats&timeframe=week" \
  -H "x-api-key: your-api-key"

Example Response

{
  "summary": {
    "totalTokens": 1253842,
    "totalCost": 3.76,
    "requestCount": 342,
    "avgTokensPerRequest": 3665,
    "avgCostPerRequest": 0.011
  },
  "models": {
    "claude-sonnet-4": {
      "totalTokens": 985234,
      "totalCost": 2.96,
      "requestCount": 280,
      "avgTokensPerRequest": 3519,
      "avgCostPerRequest": 0.0106
    },
    "claude-3-5-haiku": {
      "totalTokens": 268608,
      "totalCost": 0.067,
      "requestCount": 62,
      "avgTokensPerRequest": 4332,
      "avgCostPerRequest": 0.0011
    }
  },
  "agents": {
    "code-reviewer": {
      "totalTokens": 523842,
      "totalCost": 1.57,
      "requestCount": 145,
      "avgTokensPerRequest": 3613,
      "avgCostPerRequest": 0.0108
    },
    "task-manager": {
      "totalTokens": 730000,
      "totalCost": 2.19,
      "requestCount": 197,
      "avgTokensPerRequest": 3706,
      "avgCostPerRequest": 0.0111
    }
  },
  "timeframe": "week",
  "recordCount": 342
}

Action: Agent Costs

Per-Agent Cost Breakdown

Detailed cost analysis per agent with model breakdown and daily timelines.

Request

GET /api/tokens?action=agent-costs&timeframe=month

Response Fields

agents

object

Cost breakdown per agent (key: agent name)

Show Agent Cost Object

stats

object

Overall agent statistics (TokenStats format)

models

object

Per-model breakdown (key: model name, value: TokenStats)

sessions

array

Array of unique session IDs for this agent

timeline

array

Daily cost and token timeline

Show Timeline Entry

date

string

Date (YYYY-MM-DD)

cost

number

Total cost for day

tokens

integer

Total tokens for day

timeframe

string

Applied timeframe filter

recordCount

integer

Number of records analyzed

Example Request

cURL

curl -X GET "https://your-domain.com/api/tokens?action=agent-costs&timeframe=month" \
  -H "x-api-key: your-api-key"

Example Response

{
  "agents": {
    "code-reviewer": {
      "stats": {
        "totalTokens": 2453842,
        "totalCost": 7.36,
        "requestCount": 687,
        "avgTokensPerRequest": 3571,
        "avgCostPerRequest": 0.0107
      },
      "models": {
        "claude-sonnet-4": {
          "totalTokens": 2250000,
          "totalCost": 6.75,
          "requestCount": 630,
          "avgTokensPerRequest": 3571,
          "avgCostPerRequest": 0.0107
        },
        "claude-3-5-haiku": {
          "totalTokens": 203842,
          "totalCost": 0.051,
          "requestCount": 57,
          "avgTokensPerRequest": 3577,
          "avgCostPerRequest": 0.0009
        }
      },
      "sessions": [
        "code-reviewer:chat",
        "code-reviewer:cron"
      ],
      "timeline": [
        {
          "date": "2026-02-15",
          "cost": 0.42,
          "tokens": 140234
        },
        {
          "date": "2026-02-16",
          "cost": 0.38,
          "tokens": 126842
        }
      ]
    }
  },
  "timeframe": "month",
  "recordCount": 687
}

Action: Export

Export Usage Data

Export complete token usage data in JSON or CSV format.

Request

GET /api/tokens?action=export&timeframe=week&format=csv

Response

Returns file download with appropriate Content-Disposition header. JSON Export:

Content-Type: application/json
Includes: usage records, summary stats, model stats, session stats

CSV Export:

Content-Type: text/csv
Columns: timestamp, agentName, model, sessionId, operation, inputTokens, outputTokens, totalTokens, cost, duration

Example Request

curl -X GET "https://your-domain.com/api/tokens?action=export&timeframe=week&format=json" \
  -H "x-api-key: your-api-key" \
  -o token-usage.json

Action: Trends

Hourly Usage Trends

Get hourly token usage and cost trends for the last 24 hours.

Request

GET /api/tokens?action=trends

Response Fields

trends

array

Array of hourly data points

Show Trend Object

timestamp

string

ISO 8601 timestamp (hour precision)

tokens

integer

Total tokens for this hour

cost

number

Total cost for this hour

requests

integer

Number of requests in this hour

timeframe

string

Applied timeframe (always includes recent 24h)

Example Response

{
  "trends": [
    {
      "timestamp": "2026-03-04T12:00:00.000Z",
      "tokens": 45234,
      "cost": 0.136,
      "requests": 12
    },
    {
      "timestamp": "2026-03-04T13:00:00.000Z",
      "tokens": 52891,
      "cost": 0.159,
      "requests": 15
    }
  ],
  "timeframe": "day"
}

Record Token Usage

POST /api/tokens

Manually record token usage for a session.

Authorization: Operator role required

Request Body

model

string

required

Model identifier (e.g., “claude-sonnet-4”)

sessionId

string

required

Session identifier

inputTokens

integer

required

Number of input tokens

outputTokens

integer

required

Number of output tokens

operation

string

default:"chat_completion"

Operation type

duration

number

Request duration in milliseconds

Response

success

boolean

Whether recording was successful

record

object

Created TokenUsageRecord object

Example Request

curl -X POST "https://your-domain.com/api/tokens" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "model": "claude-sonnet-4",
    "sessionId": "code-reviewer:chat",
    "inputTokens": 1523,
    "outputTokens": 842,
    "operation": "code_review",
    "duration": 1250
  }'

Example Response

{
  "success": true,
  "record": {
    "id": "1709856400000-abc123xyz",
    "model": "claude-sonnet-4",
    "sessionId": "code-reviewer:chat",
    "agentName": "code-reviewer",
    "timestamp": 1709856400000,
    "inputTokens": 1523,
    "outputTokens": 842,
    "totalTokens": 2365,
    "cost": 0.007095,
    "operation": "code_review",
    "duration": 1250
  }
}

Model Pricing

Supported Models & Pricing

Pricing per 1,000 tokens for supported models.

Pricing Table

Model	Cost per 1K tokens	Provider
`claude-sonnet-4`	$3.00	Anthropic
`claude-3-5-haiku`	$0.25	Anthropic
`claude-opus-4-5`	$15.00	Anthropic
`llama-3.1-8b-instant`	$0.05	Groq
`llama-3.3-70b-versatile`	$0.59	Groq
`kimi-k2.5`	$1.00	Moonshot
`minimax-m2.1`	$0.30	Minimax
`ollama/deepseek-r1:14b`	$0.00	Ollama (local)
`ollama/qwen2.5-coder:7b`	$0.00	Ollama (local)
`ollama/qwen2.5-coder:14b`	$0.00	Ollama (local)

Pricing is automatically calculated based on model names. If an exact match isn’t found, Mission Control attempts partial matching (e.g., “claude-sonnet” matches “anthropic/claude-sonnet-4”). Unknown models default to $1.00 per 1K tokens.

Data Sources

Token Data Sources

How Mission Control aggregates token usage data.

Priority Order

Token Usage Database (Primary)
- Stored in token_usage SQLite table
- Most authoritative source
- Includes heartbeat data from agents
JSON File Storage (Secondary)
- Manually recorded usage via POST endpoint
- File location: configured in tokensPath
- Limited to 10,000 most recent records
Gateway Sessions (Fallback)
- Derived from active OpenClaw sessions
- Used when no persistent data exists
- Real-time but less comprehensive

Best Practices

Optimization Tips

Recommendations for token usage monitoring and cost optimization.

Cost Monitoring

Set up regular exports - Export data weekly for billing analysis
Monitor agent-costs - Identify high-cost agents for optimization
Track model usage - Use cheaper models (Haiku) for simple tasks
Review trends - Identify usage spikes and anomalies

Performance

Use timeframe parameter to limit data volume
Export CSV for large datasets (more efficient than JSON)
Cache stats responses for dashboards
Use agent-costs for detailed analysis, stats for quick overview

Data Retention

JSON file storage limited to 10,000 records
Database storage unlimited (manage via SQL if needed)
Consider periodic exports for long-term archival

Overview

Core Resources

Monitoring

Integrations

Administration

​Overview

​Authentication

​Query Token Usage

GET /api/tokens

​Query Parameters

​Action: List

List Token Usage Records

​Request

​Response Fields

​Example Request

​Example Response

​Action: Stats

Get Aggregated Statistics

​Request

​Response Fields

​Example Request

​Example Response

​Action: Agent Costs

Per-Agent Cost Breakdown

​Request

​Response Fields

​Example Request

​Example Response

​Action: Export

Export Usage Data

​Request

​Response

​Example Request

​Action: Trends

Hourly Usage Trends

​Request

​Response Fields

​Example Response

​Record Token Usage

POST /api/tokens

​Request Body

​Response

​Example Request

​Example Response

​Model Pricing

Supported Models & Pricing

​Pricing Table

​Data Sources

Token Data Sources

​Priority Order

​Best Practices

Optimization Tips

​Cost Monitoring

​Performance

​Data Retention

Overview

Authentication

Query Token Usage

Query Parameters

Action: List

Request

Response Fields

Example Request

Example Response

Action: Stats

Request

Response Fields

Example Request

Example Response

Action: Agent Costs

Request

Response Fields

Example Request

Example Response

Action: Export

Request

Response

Example Request

Action: Trends

Request

Response Fields

Example Response

Record Token Usage

Request Body

Response

Example Request

Example Response

Model Pricing

Pricing Table

Data Sources

Priority Order

Best Practices

Cost Monitoring

Performance

Data Retention