Terminal
Terminal/Skill
Answers questions about your OpenRouter usage, including spend, request volume, top models, latency, and ways to cut costs.
By OpenRouter
Works with
npx skills add openrouterteam/skills --skill openrouter-analyticsQuery 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.
--api-key <key> or set the OPENROUTER_API_KEY environment variablecd <skill-path>/scripts && npm install
| 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 |
The recommended workflow for answering a user's analytics question:
discover-schema.ts to see available metrics and dimensionsquery-analytics.tsFor common questions, suggest-queries.ts provides ready-made query templates.
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.
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.
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
cd <skill-path>/scripts && npx tsx suggest-queries.ts
Returns a list of pre-built query templates for common questions, each with:
query-analytics.tsThe 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:
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)tokens_total, tokens_prompt, tokens_completion) are in native model tokensavg_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 rowscache_hit_rate, possible_cache_hit_rate, cache_capture_rate) are 0–1 ratiosavg_throughput, p50_/p90_/p95_/p99_throughput) is completion tokens per secondgranularity is set, rows include a date__<granularity> field for the time bucket (e.g., date__day, date__hour, date__month)api_key_id, app, user, and workspace have their raw IDs replaced with human-readable names (key name, app title, user name, workspace name) directly in the data rows; generation_id and session_id return raw values; sentinel buckets are labelled (api_key_id -1 → Chatroom, app -1 → Unknown, the max-UUID workspace → Unattributed)metadata.truncated. If true, the result was capped at --limit and is a partial dataset — raise --limit or paginate before reporting totals or rankingsWhen the user asks "How can I spend less?" or similar:
--metrics total_usage,tokens_total,cache_hit_rate,request_count --dimensions model --order-by total_usage --limit 10--metrics credits_usage,byok_usage,byok_fees,usage_upstream,usage_cache,usage_data,usage_web,usage_file --granularity day to see where spend goescache_hit_rate — prompt caching can helpreasoning_tokens are a large fraction of total — consider disabling extended thinking if not neededusage_web or usage_file relative to usage_upstream — web search and file processing add-on costs may be significantTo inspect specific generations or sessions from your analytics results, add generation_id or session_id as a dimension. Both are generations-only dimensions (31-day limit). generation_id returns the unique ID for each generation in the result set. session_id groups and filters sessionless requests as the literal none: the ClickHouse column defaults to an empty string, and the query builder coalesces it to none. Use neq 'none' to exclude sessionless requests; filtering on '' matches nothing.
npx tsx query-analytics.ts --metrics total_usage,tokens_total --dimensions generation_id --order-by total_usage --limit 10
Once you have a generation ID (e.g., gen-aBcDeFgHiJkLmNoPqRsT), use the openrouter-generations skill to get detailed information:
get-generation — Fetch full request metadata: cost breakdown, token counts, latency, provider routing chain, finish reason, and moreget-generation-content — Fetch the stored prompt and completion text (unless Zero Data Retention was enabled)cd <openrouter-generations-skill-path>/scripts
npx tsx get-generation.ts gen-aBcDeFgHiJkLmNoPqRsT
npx tsx get-generation-content.ts gen-aBcDeFgHiJkLmNoPqRsT
This workflow is useful for identifying your most expensive or slowest requests via analytics, then inspecting the actual prompt/completion to understand why.
Both endpoints require a management key via Authorization: Bearer sk-or-v1-....
| Endpoint | Method | Description |
|---|---|---|
/api/v1/analytics/meta | GET | Returns available metrics, dimensions, operators, granularities |
/api/v1/analytics/query | POST | Executes an analytics query and returns structured data |
Full documentation: https://openrouter.ai/docs/api/api-reference/analytics