Skip to main content

​
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"

​
GET /api/usage/daily

Get daily usage trends with per-day breakdowns. 
curl http://localhost:3000/api/usage/daily

​
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

​
GET /api/usage/models

Get per-model usage statistics with cost breakdowns and I/O ratios. 
curl http://localhost:3000/api/usage/models

​
GET /api/usage/insights

Get usage anomalies and insights for cost optimization. 
curl http://localhost:3000/api/usage/insights
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"

​
GET /api/usage/monthly

Get monthly aggregated usage data. 
curl http://localhost:3000/api/usage/monthly

​
POST /api/usage/refresh

Force cache refresh to fetch latest usage data. 
curl -X POST http://localhost:3000/api/usage/refresh

​
GET /api/usage/status

Get cache status and last fetch timestamp. 
curl http://localhost:3000/api/usage/status

​
Caching Strategy

The usage API uses a three-tier caching system:
  1. In-Memory Cache: TTL varies by endpoint (1-5 minutes)
  2. Disk Cache: Persisted to ~/.ccs/.cache/usage-cache.json (7-day stale TTL)
  3. 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"
}