Analytics
Inspect gateway usage — request counts, tokens, latency, and failures — via the analytics endpoints.
The gateway records one event per completion request (unless flagged with x-freerouter-test: 1). Three read-only endpoints summarize that data for the dashboard.
All analytics routes require the session token (x-freerouter-session), obtained from GET /v1/gateway/bootstrap on localhost.
GET /v1/analytics/summary
Aggregate totals across all recorded events.
TOK=$(curl -s -H "host: localhost" http://localhost:4141/v1/gateway/bootstrap \
| python3 -c "import sys,json;print(json.load(sys.stdin)['token'])")
curl -H "x-freerouter-session: $TOK" http://localhost:4141/v1/analytics/summaryExample response shape:
{
"totalRequests": 128,
"totalInputTokens": 24820,
"totalOutputTokens": 9120,
"totalLatencyMs": 182340,
"successCount": 121,
"errorCount": 7,
"byStatus": { "success": 121, "error": 7 }
}GET /v1/analytics/timeseries
Bucketed counts over time. Use the bucket query param: day (default), week, or month.
curl -H "x-freerouter-session: $TOK" \
"http://localhost:4141/v1/analytics/timeseries?bucket=week"{
"points": [
{ "bucket": "2026-08-18", "requests": 12, "tokens": 1840 },
{ "bucket": "2026-08-19", "requests": 31, "tokens": 4022 }
]
}GET /v1/analytics/events
Most recent raw events (newest first). Limit with limit (default 100).
curl -H "x-freerouter-session: $TOK" \
"http://localhost:4141/v1/analytics/events?limit=10"{
"events": [
{
"timestamp": 1710000123000,
"gatewayKeyId": "gk_...",
"alias": "free:auto",
"model": "groq/llama-3.1-8b-instant",
"status": "success",
"latencyMs": 412,
"inputTokens": 24,
"outputTokens": 11
}
]
}Privacy
Events attribute usage to a (hashed) gateway key id and the model/alias used — they never contain provider keys or message contents.
Resetting analytics
Analytics live in usage_events.jsonl under the data directory. Run npx @freerouter/gateway reset to clear it (and all other local state).