Usage Analytics API

Track token usage, costs, and usage patterns across all Claude Code sessions. The usage analytics system aggregates data from JSONL files and provides multiple views of consumption data.

Overview

The usage API provides endpoints for:

Daily, hourly, and monthly usage summaries
Per-model cost breakdowns
Session history and project tracking
Anomaly detection for cost spikes
Real-time cache status

Authentication

All endpoints are available on localhost only (http://localhost:3000). No authentication required.

Endpoints

GET /api/usage/summary

Get overall usage summary with total tokens, cost, and daily averages. Query Parameters:

since (optional): Start date in YYYYMMDD format
until (optional): End date in YYYYMMDD format

curl "http://localhost:3000/api/usage/summary?since=20260101&until=20260131"

{
  "totalTokens": 15000000,
  "totalCost": 45.50,
  "inputTokens": 10000000,
  "outputTokens": 5000000,
  "cacheReadTokens": 2000000,
  "cacheWriteTokens": 500000,
  "dailyAverage": {
    "tokens": 500000,
    "cost": 1.52
  },
  "dateRange": {
    "from": "2026-01-01",
    "to": "2026-01-31"
  },
  "modelsUsed": ["claude-sonnet-4", "gemini-3-flash"]
}

GET /api/usage/daily

Get daily usage trends with per-day breakdowns.

curl http://localhost:3000/api/usage/daily

{
  "daily": [
    {
      "date": "2026-01-05",
      "inputTokens": 450000,
      "outputTokens": 200000,
      "cacheReadTokens": 100000,
      "cacheWriteTokens": 25000,
      "cost": 1.85,
      "modelsUsed": ["claude-sonnet-4", "gemini-3-flash"],
      "modelBreakdown": {
        "claude-sonnet-4": {
          "inputTokens": 300000,
          "outputTokens": 150000,
          "cost": 1.35
        },
        "gemini-3-flash": {
          "inputTokens": 150000,
          "outputTokens": 50000,
          "cost": 0.50
        }
      }
    }
  ]
}

GET /api/usage/hourly

Get hourly usage trends for detailed time-series analysis. Includes gap filling for continuous charts.

curl http://localhost:3000/api/usage/hourly

{
  "hourly": [
    {
      "hour": "2026-01-05 14:00",
      "inputTokens": 50000,
      "outputTokens": 20000,
      "cacheReadTokens": 10000,
      "cacheWriteTokens": 2500,
      "cost": 0.21,
      "modelsUsed": ["claude-sonnet-4"]
    },
    {
      "hour": "2026-01-05 15:00",
      "inputTokens": 0,
      "outputTokens": 0,
      "cost": 0,
      "modelsUsed": []
    }
  ]
}

GET /api/usage/models

Get per-model usage statistics with cost breakdowns and I/O ratios.

curl http://localhost:3000/api/usage/models

{
  "models": [
    {
      "model": "claude-sonnet-4",
      "inputTokens": 8000000,
      "outputTokens": 3500000,
      "cacheReadTokens": 1500000,
      "cacheWriteTokens": 400000,
      "cost": 32.50,
      "percentage": 71.4,
      "ioRatio": 2.29
    },
    {
      "model": "gemini-3-flash",
      "inputTokens": 2000000,
      "outputTokens": 1500000,
      "cost": 13.00,
      "percentage": 28.6,
      "ioRatio": 1.33
    }
  ],
  "totalCost": 45.50
}

GET /api/usage/insights

Get usage anomalies and insights for cost optimization.

curl http://localhost:3000/api/usage/insights

{
  "anomalies": [
    {
      "type": "cost_spike",
      "date": "2026-01-04",
      "value": 5.20,
      "threshold": 2.50,
      "message": "Daily cost 208% above average"
    },
    {
      "type": "high_input",
      "date": "2026-01-03",
      "value": 12000000,
      "threshold": 10000000,
      "message": "Input tokens exceeded 10M threshold"
    }
  ],
  "thresholds": {
    "highInput": 10000000,
    "highIoRatio": 100,
    "costSpikeMultiplier": 2,
    "highCacheRead": 1000000000
  }
}

Anomaly Types:

cost_spike: Daily cost significantly above average
high_input: Input tokens exceed 10M threshold
high_io_ratio: Input-to-output ratio exceeds 100:1
high_cache_read: Cache read tokens exceed 1B

GET /api/usage/sessions

Get session history with pagination support. Query Parameters:

limit (optional): Number of sessions to return (default: 50)
offset (optional): Pagination offset (default: 0)

curl "http://localhost:3000/api/usage/sessions?limit=10&offset=0"

{
  "sessions": [
    {
      "sessionId": "abc123",
      "projectPath": "~/projects/my-app",
      "lastActivity": "2026-01-05T14:30:00Z",
      "inputTokens": 100000,
      "outputTokens": 50000,
      "cost": 0.45,
      "modelsUsed": ["claude-sonnet-4"],
      "version": "1.2.3"
    }
  ],
  "total": 150,
  "limit": 10,
  "offset": 0
}

GET /api/usage/monthly

Get monthly aggregated usage data.

curl http://localhost:3000/api/usage/monthly

{
  "monthly": [
    {
      "month": "2026-01",
      "inputTokens": 10000000,
      "outputTokens": 5000000,
      "cacheReadTokens": 2000000,
      "cacheWriteTokens": 500000,
      "cost": 45.50
    },
    {
      "month": "2025-12",
      "inputTokens": 8000000,
      "outputTokens": 4000000,
      "cost": 36.00
    }
  ]
}

POST /api/usage/refresh

Force cache refresh to fetch latest usage data.

curl -X POST http://localhost:3000/api/usage/refresh

{
  "success": true,
  "message": "Cache cleared, refreshing data",
  "timestamp": 1704467400000
}

GET /api/usage/status

Get cache status and last fetch timestamp.

curl http://localhost:3000/api/usage/status

{
  "cached": true,
  "lastFetch": 1704467400000,
  "lastFetchHuman": "2026-01-05T14:30:00Z",
  "cacheAge": 120000,
  "cacheAgeHuman": "2 minutes ago"
}

Caching Strategy

The usage API uses a three-tier caching system:

In-Memory Cache: TTL varies by endpoint (1-5 minutes)
Disk Cache: Persisted to ~/.ccs/.cache/usage-cache.json (7-day stale TTL)
Stale-While-Revalidate: Returns stale cache immediately, refreshes in background

Cache Behavior

Fresh Cache (<1 min): Instant response from memory
Stale Cache (1-7 days): Instant response, background refresh
No Cache: Blocking fetch from JSONL files

Data Sources

Usage data is aggregated from:

~/.claude/projects/*/usage.jsonl - Default Claude directory
~/.ccs/instances/*/usage.jsonl - CCS account instances

Model Pricing

Costs are calculated using built-in pricing for:

Claude (Haiku, Sonnet, Opus variants)
OpenAI (GPT-4o, o1, o3, Codex)
Google Gemini (Flash, Pro)
GLM, Kimi, MiniMax, DeepSeek, Mistral

Pricing includes input/output tokens, cache creation, and cache reads.

Error Responses

{
  "error": "Failed to fetch usage data",
  "message": "Detailed error message"
}

{
  "error": "Cache unavailable",
  "message": "No cached data available and fetch failed"
}

CLI Reference

Config Reference

API Reference

Troubleshooting

Architecture

Usage Analytics API

Usage Analytics API

Overview

Authentication

Endpoints

GET /api/usage/summary

GET /api/usage/daily

GET /api/usage/hourly

GET /api/usage/models

GET /api/usage/insights

GET /api/usage/sessions

GET /api/usage/monthly

POST /api/usage/refresh

GET /api/usage/status

Caching Strategy

Cache Behavior

Data Sources

Model Pricing

Error Responses

​Usage Analytics API

​Overview

​Authentication

​Endpoints

​GET /api/usage/summary

​GET /api/usage/daily

​GET /api/usage/hourly

​GET /api/usage/models

​GET /api/usage/insights

​GET /api/usage/sessions

​GET /api/usage/monthly

​POST /api/usage/refresh

​GET /api/usage/status

​Caching Strategy

​Cache Behavior

​Data Sources

​Model Pricing

​Error Responses

Usage Analytics API

Overview

Authentication

Endpoints

GET /api/usage/summary

GET /api/usage/daily

GET /api/usage/hourly

GET /api/usage/models

GET /api/usage/insights

GET /api/usage/sessions

GET /api/usage/monthly

POST /api/usage/refresh

GET /api/usage/status

Caching Strategy

Cache Behavior

Data Sources

Model Pricing

Error Responses