/openrouter-analytics-schema

name: openrouter-analytics-schema
description: Discover the OpenRouter analytics schema — available metrics, dimensions, filter operators, and granularities. Use when you need to know what analytics data is queryable, what dimensions you can break down by, or how to map a user's question to the right metric/dimension combination.
version: 0.1.0

OpenRouter Analytics Schema Discovery

Discover what analytics data is available for querying. The meta endpoint returns live, always-current definitions of metrics, dimensions, filter operators, and granularities.

Prerequisites

• An OpenRouter **management key**. Management keys are separate from regular API keys — get one at https://openrouter.ai/settings/management-keys
• Pass it via `--api-key <key>` or set the `OPENROUTER_API_KEY` environment variable

Discovery Endpoint

GET https://openrouter.ai/api/v1/analytics/meta
Authorization: Bearer sk-or-v1-...

Or via the `openrouter-analytics` skill scripts:

cd <openrouter-analytics-skill-path>/scripts && npx tsx discover-schema.ts

Response Shape

{
  "data": {
    "metrics": [
      { "name": "request_count", "display_label": "Request Count", "is_rate": false, "display_format": "number" }
    ],
    "dimensions": [
      { "name": "model", "display_label": "Model" }
    ],
    "operators": [
      { "name": "eq", "value_type": "scalar" }
    ],
    "granularities": [
      { "name": "day", "display_label": "Day" }
    ]
  }
}

Understanding Metrics

Each metric has:

| Field | Meaning | |---|---| | `name` | Identifier to use in query requests | | `display_label` | Human-readable label | | `is_rate` | Whether this is a ratio/rate (averaged, not summed) | | `display_format` | How the value should be formatted: `number`, `currency`, `percent`, `latency`, or `throughput` |

Time Range Limits

Most volume and cost metrics support time ranges up to **367 days** with day or coarser granularity. Latency/throughput metrics, `blended_cost_per_million_tokens`, and generations-only dimensions (`provider`, `origin`, `country`, `data_region`, `skin`, `finish_reason`, `external_user`, `context_length_bucket`, `generation_id`, `session_id`, `streamed`) are limited to **31-day** time ranges, as is `hour` granularity. Possible-cache metrics (`possible_cached_tokens`, `possible_cache_hit_rate`, `cache_capture_rate`) always read an hourly rollup, so they are capped at **31 days** too and coarser granularity does not lift that cap.

Exceeding a cap returns 400 with the applicable maximum in the message, not a truncated result. If a query times out instead, try narrowing the time range or removing latency/throughput metrics and per-generation dimensions.

Metric Categories

**Volume metrics** (how much):

• `request_count` — number of API requests (up to 367 days). Excludes server-tool rows (web search / file-parsing charges recorded alongside a request), so it counts model requests, not billed line items
• `tokens_total`, `tokens_prompt`, `tokens_completion` — token counts (up to 367 days)
• `reasoning_tokens` — tokens used for extended thinking (up to 367 days)
• `cached_tokens` — tokens served from cache (up to 367 days)
• `possible_cached_tokens` — prompt tokens that were eligible for caching, whether or not they were cached (31-day limit, hourly rollup only)
• `byok_request_count` — number of BYOK requests (up to 367 days). Server-tool rows are excluded when the query reads raw generations (any latency/throughput metric or generations-only dimension in the same request) but still counted when served from the rollups, so the two paths can differ for BYOK traffic that uses server tools
• `guardrail_invoked_count` — count of requests that triggered guardrails (31-day limit)
• `response_cached_count` — count of responses served from cache (31-day limit)

**Cost metrics** (how much money):

• `total_usage` — total cost in USD, including BYOK inference cost (up to 367 days). Computed as `sum(usage) + sum(byok_usage_inference)` so it reflects true spend for both credits and BYOK users.
• `byok_usage` — BYOK (bring your own key) inference cost in USD (up to 367 days)
• `credits_usage` — all charges billed to OpenRouter credits in USD, including BYOK platform fees (up to 367 days)
• `openrouter_usage` — non-BYOK inference spend in USD; excludes requests made with user-provided keys (31-day limit)
• `byok_fees` — BYOK platform fees in USD; the platform fee portion of `credits_usage` charged on BYOK requests (31-day limit). `credits_usage` includes both non-BYOK inference charges and these BYOK platform fees.
• `usage_upstream` — provider-side (upstream) cost in USD (up to 367 days)
• `usage_cache` — cache cost component in USD (up to 367 days)
• `usage_data` — data logging cost adjustment in USD; typically negative when a data logging discount applies (up to 367 days)
• `usage_web` — web search cost in USD (up to 367 days)
• `usage_upstream_web` — provider-side web search cost in USD (up to 367 days)
• `usage_file` — file processing cost in USD (31-day limit)
• `usage_upstream_file` — provider-side file processing cost in USD (31-day limit)
• `usage_web_fetch` — web fetch cost in USD (31-day limit)
• `usage_upstream_web_fetch` — provider-side web fetch cost in USD (31-day limit)
• `blended_cost_per_million_tokens` — average cost per 1M tokens (prompt + completion), including BYOK inference cost (31-day limit; always reads raw generations). Server-tool spend is excluded from the numerator. A rate metric: `null` for buckets with no tokens, so it cannot be summed across rows.

**Performance metrics** (how fast; all 31-day limit, milliseconds unless noted). Each family has `avg_`, `p50_`, `p90_`, `p95_`, and `p99_` variants:

• `*_latency` — provider-side time to first token (full response time for non-streamed requests)
• `*_router_latency` — time spent in OpenRouter routing before the provider request
• `*_total_time_to_first_token` — `latency + router_latency`,