Skip to main content
MonoRelay tracks usage statistics in two layers: a fast in-memory counter that persists to data/stats.json on every update, and a SQLite-backed log database that enables richer historical queries. The stats API surfaces both layers in a single response and also exposes per-client usage tracking from the dedicated usage tracker.

​
Authentication

All stats endpoints require a valid JWT token:

​
Endpoints

​
GET /api/stats

The primary stats endpoint. Returns a composite object combining in-memory global counters, persistent database aggregates, per-key statistics, and per-model detail breakdowns.
​
object
In-memory stats accumulated since the last restart or reset:
  • total_requests — total number of proxied requests
  • total_errors — number of requests that returned an error
  • error_rate — total_errors / total_requests
  • total_tokens_in — cumulative input tokens
  • total_tokens_out — cumulative output tokens
  • total_cache_hit_tokens — tokens served from upstream prompt cache
  • total_tokens — combined input and output tokens
  • estimated_total_cost — estimated USD spend
  • requests_by_provider — {"openrouter": 142, "anthropic": 58}
  • requests_by_model — {"claude-opus-4-5": 34, ...}
  • errors_by_provider — error counts by provider name
​
object
Aggregates computed from the SQLite request log:
  • total_requests — all logged requests (survives restarts)
  • total_cost — total estimated cost from log records
  • avg_latency_ms — average end-to-end latency
  • input_tokens — total input tokens across all log entries
  • output_tokens — total output tokens
  • cache_hit_tokens — total cache-hit tokens from log entries
​
object
Per-provider, per-key health data from the key manager: request counts, failure counts, cooldown state, and quota usage.
​
object
Per-model detail from the stats tracker. Each key is a model name:
  • requests — total requests using that model
  • errors — error count for that model
  • total_tokens_in / total_tokens_out — token totals
  • total_cache_hit_tokens — cache-hit tokens for that model
  • avg_first_token_ms — exponential-decay weighted average TTFT in ms
  • avg_speed_tps — exponential-decay weighted average output tokens per second
  • streaming_requests — number of streaming requests
Example response:

​
GET /api/stats/enhanced

Returns an expanded stats object that includes per-provider breakdowns enriched with provider configuration (cost rates, key counts) and a flat key health inventory useful for dashboards.
​
object
One entry per enabled provider:
  • enabled — provider enabled state
  • total_requests — requests routed to this provider
  • total_errors — errors from this provider
  • keys.total / keys.enabled — key inventory counts
  • cost_per_m_input / cost_per_m_output — configured pricing rates
​
array
Flat list of all keys across all providers, each entry containing provider, label, enabled, total_requests, total_failures, is_available, cooldown_until, quota_limit, quota_used, rate_limit_rps, and expires_at.

​
GET /api/stats/file

Return the raw stats.json file content as a string. Useful for backup or cross-instance synchronization.

​
PUT /api/stats/file

Replace the stats.json file content and immediately reload the in-memory stats from the new content.
​
string
required
JSON string to write as the new stats file content.

​
POST /api/stats/reset

Clear all in-memory and persisted statistics. Also deletes the stats.json file and clears the SQLite request log.
This operation is irreversible. Both the stats file and the full request log database will be cleared. Export or back up data before calling this endpoint.

​
Per-client usage stats

​
GET /api/usage/stats

Return usage statistics broken down by client identity (the username or access-key prefix that made each request). Pass client_id as a query parameter to retrieve stats for a single client.

​
POST /api/usage/clear

Reset per-client usage counters. Pass client_id to clear only that client’s data, or omit it to clear all clients.

​
Analytics endpoints

​
GET /api/analytics/overview

Aggregate cost and usage by provider and model over a date range. Defaults to the last 7 days.
​
integer
Total requests in the date range.
​
number
Estimated total cost in USD.
​
object
{"input": 84200, "output": 31500} — token totals for the period.
​
object
Per-provider request counts and costs.
​
object
Per-model request counts, costs, and token totals.

​
GET /api/analytics/slow-queries

List requests that exceeded a latency threshold, ordered by first-token latency descending.

​
GET /api/analytics/cost-distribution

Return cost broken down by provider and by model as percentage shares, useful for pie-chart visualizations in dashboards.

​
Dashboard integration

The MonoRelay dashboard reads all of these endpoints automatically. The stats overview panel uses GET /api/stats, the model breakdown table uses data.models, and the real-time activity feed uses GET /api/logs/stream. You can build your own monitoring dashboards using the same API surface that the built-in UI relies on.