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

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)

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

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

array

Array of token usage records (max 100)

Show TokenUsageRecord Object

string

Unique record identifier

string

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

string

Session identifier

string

Agent name extracted from session ID

integer

Unix timestamp (milliseconds)

integer

Input tokens consumed

integer

Output tokens generated

integer

Total tokens (input + output)

number

Estimated cost in USD

string

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

number

Request duration in milliseconds (optional)

integer

Total number of records matching filters

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"

const response = await fetch('/api/tokens?action=list&timeframe=day', {
  headers: {
    'x-api-key': 'your-api-key'
  }
});
const data = await response.json();

import requests

response = requests.get(
    'https://your-domain.com/api/tokens',
    params={'action': 'list', 'timeframe': 'day'},
    headers={'x-api-key': 'your-api-key'}
)
usage = response.json()

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

object

Overall statistics

Show TokenStats Object

integer

Total tokens consumed

number

Total cost in USD

integer

Number of requests

integer

Average tokens per request

number

Average cost per request

object

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

object

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

object

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

string

Applied timeframe filter

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

object

Cost breakdown per agent (key: agent name)

Show Agent Cost Object

object

Overall agent statistics (TokenStats format)

object

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

array

Array of unique session IDs for this agent

array

Daily cost and token timeline

Show Timeline Entry

string

Date (YYYY-MM-DD)

number

Total cost for day

integer

Total tokens for day

string

Applied timeframe filter

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

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

const response = await fetch('/api/tokens?action=export&format=csv&timeframe=week', {
  headers: {
    'x-api-key': 'your-api-key'
  }
});
const blob = await response.blob();
const url = window.URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'token-usage.csv';
a.click();

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

array

Array of hourly data points

Show Trend Object

string

ISO 8601 timestamp (hour precision)

integer

Total tokens for this hour

number

Total cost for this hour

integer

Number of requests in this hour

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

string

required

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

string

required

Session identifier

integer

required

Number of input tokens

integer

required

Number of output tokens

string

default:"chat_completion"

Operation type

number

Request duration in milliseconds

Response

boolean

Whether recording was successful

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
  }'

const response = await fetch('/api/tokens', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'your-api-key'
  },
  body: JSON.stringify({
    model: 'claude-sonnet-4',
    sessionId: 'code-reviewer:chat',
    inputTokens: 1523,
    outputTokens: 842,
    operation: 'code_review',
    duration: 1250
  })
});
const data = await response.json();

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

​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