/openrouter-analytics

name: openrouter-analytics
description: Answer natural-language questions about a user's OpenRouter usage data — spend, request volume, model breakdown, latency, token usage, and cost optimization. Use when the user asks about their API usage, billing, costs, top models, traffic patterns, or wants to optimize their OpenRouter spend.
version: 0.1.0

OpenRouter Analytics

Query your OpenRouter usage data programmatically. Answer questions like "What was my spend this month?", "Which models cost the most?", and "How can I reduce my bill?" using the Analytics API.

Prerequisites

• An OpenRouter **management key** (provisioning key). Regular API keys will get a 403.
• Get a management key at https://openrouter.ai/settings/management-keys (separate from the regular API keys page)
• Pass it via `--api-key <key>` or set the `OPENROUTER_API_KEY` environment variable

First-Time Setup

cd <skill-path>/scripts && npm install

Decision Tree

| User wants to… | Do this | |---|---| | Know what data is available | Run `discover-schema.ts` to see metrics, dimensions, and filters | | See spend / usage / volume | Run `query-analytics.ts` with appropriate metrics | | Break down by model, provider, API key | Add `--dimensions` to the query | | See trends over time | Add `--granularity day` (or `hour`, `week`, `month`) | | Reduce costs | Run `suggest-queries.ts`, find the cost optimization template, execute it | | Inspect individual generations | Add `--dimensions generation_id`, then use the `openrouter-generations` skill for details | | Break down by classifier labels | Use `classifier_dimensions` in the request body (see `openrouter-analytics-query` skill) | | Filter by classifier labels | Use `classifier_filters` in the request body (see `openrouter-analytics-query` skill) | | Answer a specific question | Map the question → metrics + dimensions, then query |

Workflow

The recommended workflow for answering a user's analytics question:

1. **Discover** — Call `discover-schema.ts` to see available metrics and dimensions 2. **Map** — Translate the user's question into metrics, dimensions, filters, and time range 3. **Query** — Execute via `query-analytics.ts` 4. **Interpret** — Analyze the returned data and explain the results

For common questions, `suggest-queries.ts` provides ready-made query templates.

Discover Available Data

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

Returns the full schema: metrics, dimensions, filter operators, and granularities.

Filter to a specific section:

npx tsx discover-schema.ts --section metrics
npx tsx discover-schema.ts --section dimensions
npx tsx discover-schema.ts --section operators
npx tsx discover-schema.ts --section granularities

See the `openrouter-analytics-schema` skill for detailed guidance on interpreting the schema response and mapping user questions to the right metrics and dimensions.

Query Analytics Data

cd <skill-path>/scripts && npx tsx query-analytics.ts --metrics request_count,total_usage

See the `openrouter-analytics-query` skill for the full parameter reference and query construction guide.

Quick Examples

Spend over the last 7 days, broken down by day:

npx tsx query-analytics.ts --metrics total_usage --granularity day

Top 10 models by cost:

npx tsx query-analytics.ts --metrics total_usage,request_count --dimensions model --order-by total_usage --limit 10

Usage by API key:

npx tsx query-analytics.ts --metrics request_count,tokens_total --dimensions api_key_id --order-by request_count --limit 10

Latency by provider (limited to 31-day range):

npx tsx query-analytics.ts --metrics avg_latency,p90_latency --dimensions provider --order-by p90_latency

Usage cost breakdown (credits, BYOK, upstream, cache, data logging, web search):

npx tsx query-analytics.ts --metrics credits_usage,byok_usage,byok_fees,usage_upstream,usage_cache,usage_data,usage_web --granularity day

Common Query Templates

cd <skill-path>/scripts && npx tsx suggest-queries.ts

Returns a list of pre-built query templates for common questions, each with:

• The natural-language question it answers
• The query parameters (metrics, dimensions, filters, time range)
• The CLI flags to pass to `query-analytics.ts`
• Interpretation guidance (where applicable)

Interpreting Results

The query endpoint returns an array of data rows. Each row is a flat object with keys matching the requested metrics and dimensions.

When interpreting results for the user:

• **Spend metrics** (`total_usage`, `credits_usage`, `openrouter_usage`, `byok_usage`, `byok_fees`, `usage_upstream`, `usage_cache`, `usage_web`, `usage_upstream_web`, `usage_file`, `usage_upstream_file`, `usage_web_fetch`, `usage_upstream_web_fetch`) are in USD. `total_usage` includes BYOK inference cost. `usage_data` is typically negative (a data logging discount)
• **Token counts** (`tokens_total`, `tokens_prompt`, `tokens_completion`) are in native model tokens
• **Latency** (`avg_latency`, `p50_latency`, etc.) is in milliseconds. `*_latency` is provider-side time to first token; `*_router_latency` is OpenRouter routing time; `*_total_time_to_first_token` is their sum over streamed requests only; `*_generation_time` is provider-side generation time; `*_inter_token_latency` is the average gap between completion tokens over streamed requests with more than one completion token. Each family has `avg_`, `p50_`, `p90_`, `p95_`, `p99_` variants and excludes server-tool rows
• **Rates** (`cache_hit_rate`, `possible_cache_hit_rate`, `cache_capture_rate`) are 0–1 ratios
• **Throughput** (`avg_throughput`, `p50_`/`p90_`/`p95_`/`p99_throughput`) is completion tokens per second
• When `granularity` is set, rows include a `date__<granularity>` field for the time bucket (e.g., `date__day`, `date__hour`, `date__month`)
• **Label resolution**: dimensions `api_key_id`, `app`, `u