Skip to main content
Goal: Run a cost review on your OpenRouter account using your coding agent, the Analytics API, and the openrouter-analytics skill. Outcome: A set of query recipes and agent prompts for digging into your own usage data: which models burn the most, which API keys cause it, and what to repoint or cache.
Then copy this prompt into your agent to run the full cost review.
Analytics queries need a management key from Settings → Management Keys. Regular inference keys get a 403. Management keys can’t make model requests, so the whole workflow is read-only and free, but the data it returns is your org’s full spend breakdown. Treat the key like any other credential.

Before you start

You need:
  • A management key your agent can read; the skill’s scripts expect it in OPENROUTER_API_KEY (or passed via --api-key)
  • Node.js with npx if you use the skill’s scripts (they run via npx tsx)
  • A coding agent (Claude Code, Devin, Cursor, or anything that can run shell commands)
  • At least a few weeks of real usage on your account, or there’s nothing to analyze
Use these references for exact schemas:

What you’re building

A cost review your agent runs for you. The conversation starts with one question:
The agent discovers the schema, pulls spend grouped by model, flags the lines where effective price per token is far above your blended rate (total spend divided by total tokens across all traffic, scaled to $ per million tokens), drills into the API keys behind those lines, and hands you actions ranked by dollar impact. We ran this internally and found a preview model burning ~$6.2K/month at roughly 25x the org’s blended rate. One drill-down query later, 98% of it traced to a single batch-pipeline key running a task that never needed a frontier model. The fix was a one-line model swap. The recipes below are the building blocks of that review. Each one is a prompt you can paste into your agent, followed by an under-the-hood look at the query the agent generates and the shape of what comes back.

Setup: install the skill and discover the schema

The skill bundles runnable query scripts so your agent doesn’t hand-write curl calls:
Schema discovery comes first. Metrics and dimensions evolve, so query what’s actually there instead of trusting a doc snapshot:
Or hit the endpoint directly:
The response lists every metric, dimension, filter operator, and granularity the API currently supports; the meta endpoint reference shows the full shape. Spend metrics (total_usage, usage_*) are in USD. Token metrics are native tokens. cache_hit_rate is a 0 to 1 ratio. Two things to know before reading any output: count metrics can come back as strings (the reference’s example shows them as numbers, so parse defensively and accept both), and metadata.truncated tells you whether the result hit the row limit. If it’s true, your totals are partial; raise limit or narrow the query before drawing conclusions. The API caps queries at 3 dimensions. A third dimension works only when every metric, dimension, and filter in the query is served from the activity rollups (for example model, api_key_id, endpoint, workspace, app, user, variant), or for the token-kind metrics below from their daily rollup (model, api_key_id, workspace, variant, endpoint, provider, data_region, billed_service_tier, long_context); combining three with a dimension or metric that needs raw generations (such as country, or latency percentiles, or provider without a token-kind metric) returns a 400 naming the incompatible fields. For the token-kind metrics, a third dimension also needs a time_range whose start and end are UTC midnights; a range of 31 days or less that starts or ends mid-day returns a 400 naming the off-midnight bound. A fourth dimension always returns a 400. When the agent needs another angle beyond that, it should run separate queries or add a time-axis granularity instead.

Recipe: which models burn the most?

The widest-angle question, and the right one to start with:
Under the hood, your agent generates a query like this (one POST to /api/v1/analytics/query with the management key):
An explicit time_range matters: without one the API defaults to a recent window that may miss the month you asked about. Sample response shape (1 row shown):
From here the agent computes total_usage / tokens_total * 1e6 for each row to get an effective $/Mtok per model (spend over tokens gives dollars per single token; the 1e6 scales it to dollars per million tokens, the unit model pricing is quoted in). Compare each against your blended rate: the same calculation run with no dimensions, so it covers all traffic in the window. A model priced at a large multiple of the blended rate is the strongest signal to chase, but you may not find one; if every model sits near the blended rate, your spend matches your pricing and the levers are elsewhere (cache rate, prompt size, or feature surcharges, covered in the recipes below). In the internal run above, the flagged model had spent $6,185 on 0.25B tokens (6185 / 250000000 * 1e6 ≈ $24.7/Mtok) with a 7.6% cache rate, about 25x that org’s blended rate.

Recipe: which keys drive a model’s cost?

The model row shows where spend concentrates, but the thing you can change is the key, app, or pipeline calling that model. This works whether the model is an outlier or just your biggest fairly-priced line, since the per-key split still shows which workload to optimize:
Under the hood, the agent filters to that model and groups by api_key_id using a filters array on the request body:
api_key_id, app, and workspace resolve to human-readable names in the response, so each row names the key directly. Here’s the row shape, filled with the internal run’s numbers (rounded, key name changed):
The user dimension is the exception: grouping by user returns two fields per row instead of one. user is the account’s display name (or null when the user has no name set), and user_email is their email (null when the user has no email on file). The raw user ID is never returned, so use user_email to cross-reference users against your own records:
In the internal run, this is where the recommendation wrote itself: a batch-pipeline key doing 37K requests at ~$48/Mtok is high-volume, low-complexity work on the wrong model. Repointing it to a cheap production model recovers the whole line item at near-zero risk. A sharper variant of the same prompt skips the model step entirely:

Recipe: what did the money actually buy?

total_usage is a single number. The usage_* components split it into what each dollar paid for:
Under the hood, the agent queries the component metrics over a time axis:
Each row carries a time-series key named date__<granularity> or created_at__<granularity> (here, created_at__day) depending on which data source the query resolves to, so accept either prefix. The rest of the row is the components in USD. Unused components come back as null, not 0:
  • usage_upstream: raw inference cost
  • usage_cache: what caching saved (or cost, for cache writes)
  • usage_data: discounts, typically negative
  • usage_web, usage_file: web search and file parsing surcharges
If usage_web or usage_file is a meaningful slice, the fix is gating those features. If usage_cache savings are near zero on a prompt-heavy workload, caching is your lever. And if cache rates are already high, skip the caching advice entirely; in the internal run, caching was near-maxed and the only real lever was model mix.

Separate batch traffic

Batch API requests are recorded with the batch variant, so the variant dimension separates them from synchronous traffic at any time range:
Rows with "variant": "batch" are batch traffic. Filter with { "field": "variant", "operator": "eq", "value": "batch" } to keep only batch requests, or neq to exclude them.

Recipe: what did each token kind cost?

usage_upstream and byok_usage are single numbers too. The token-kind metrics split them by the kind of token they paid for, at the rates actually billed (provider discounts included), not catalog prices:
  • usage_upstream_uncached_input, usage_upstream_cache_read, usage_upstream_cache_write, usage_upstream_output, usage_upstream_reasoning: upstream inference cost OpenRouter paid, in USD.
  • byok_usage_uncached_input, byok_usage_cache_read, byok_usage_cache_write, byok_usage_output, byok_usage_reasoning: the same split of BYOK inference cost billed by your provider.
  • uncached_input_tokens and cache_write_tokens: billed token counts for the two input kinds that have no other metric.
  • token_kind_request_count: the requests that carry the split, to compare against request_count when a row comes back null.
  • usage_upstream_token_kind_total and byok_usage_token_kind_total: the upstream cost the split adds up to over the same requests, so one query returns the parts and their total.
Reasoning is its own kind only where the provider bills it at its own rate (Gemini and Perplexity today). Everywhere else, including OpenAI, Anthropic, and xAI, reasoning tokens are billed and reported as output, so usage_upstream_reasoning is 0 while reasoning_tokens is not. tokens_completion always includes reasoning tokens, and cached_tokens and reasoning_tokens are provider-reported counts over every request, so don’t divide a per-kind cost by them to get a per-token rate. They are UTC-daily totals over any range up to a year. The same daily totals also serve request_count, tokens_prompt, tokens_completion, reasoning_tokens, cached_tokens, and tokens_total, with the same values as everywhere else, so one query can put the token counts next to the per-kind costs. The daily totals group by model, api_key_id, workspace, variant, endpoint, provider, data_region, billed_service_tier, and long_context, with granularity of day, week, month, or none. Any other dimension or filter (such as app, user, or country), hour or minute granularity, or a timezone reads raw generations instead, which allows at most 31 days; past that the query returns a 400 naming what kept it off the daily totals. A time_range of 31 days or less that starts or ends off a UTC midnight also reads raw generations, however far back it is, so it is not widened to whole days, and with three dimensions such a range returns a 400 instead, so use UTC midnight bounds; a longer one reads the daily totals for every whole UTC day it touches. Without a time_range, the default last 7 days is snapped out to whole UTC days on the daily totals, as it is on the other activity rollups. Group them by pricing qualifiers to see where the rate came from: billed_service_tier (the tier you were billed at, which can differ from the tier that served the request), long_context ("true" when a long-context price tier applied), endpoint (the endpoint UUID, the same endpoint_id that GET /api/v1/activity returns with its provider), provider (the provider that served the request), and data_region (global, or the region the request was routed in, such as europe). A daily pull by model and key with one qualifier looks like this:
Three things to know before summing them:
  • They start on 20 November 2026 (UTC), and the first day reads null. The split is recorded as requests are billed, from the release that added these metrics; there is no backfill. The daily totals treat their earliest day as incomplete, because it can hold only part of that day’s traffic, so every metric of a row on or before that day (or of an ungranular query whose range starts on or before it) is null, including request_count. The rule relies on the daily totals being switched on before their first day begins, and on any later backfill filling one unbroken run of days up to and including that first day.
  • A row is either complete or null. A token-kind metric is null for a row unless every request in it carries the split, that is unless token_kind_request_count equals request_count. Requests whose billed rows can’t be reconciled with what was charged (for example fallback pricing when a provider reports no usage, or batch estimates), or whose charged amount was not recorded, have no split, so a row containing one reads as null rather than as a partial total. Batch requests never carry the split, so keep variant in the grouping (or filter it out) when a model takes both batch and synchronous traffic.
  • They don’t always add up to usage_upstream. Server tools billed by the provider (such as native web search), Anthropic advisor-model tokens, and other non-token charges belong to no token kind, so the five kinds can sum to less than usage_upstream. Pricing qualifiers are recorded on chat, Responses, and Messages requests; other request types (embeddings, images, batch) group under an empty value.

Recipe: is my workload prompt-heavy?

The token shape decides whether caching or prompt trimming is worth the effort:
Under the hood:
A 20:1 prompt-to-completion ratio points at oversized context, and a large reasoning_tokens share means you’re paying for thinking you may not need. Pair the ratio with cache_hit_rate: prompt-heavy traffic with a low cache rate is the textbook caching win, while prompt-heavy traffic with a high cache rate is already optimized and the lever moves back to model mix.

Recipe: did spend actually change?

Grouping spend over a time axis covers 2 jobs: finding what changed when a bill jumps, and verifying that a fix landed. For the first:
Under the hood, the agent groups per-key spend over a weekly time axis:
Sample output:
For the bill-doubled case, the key (or model, if the agent groups by model instead) whose weekly line jumped is your culprit. For verification, ask the agent to re-run the same query after a fix ships: a successful repoint shows the key’s weekly total_usage falling off a cliff at the deploy date, like the sample above. Filter values must match what the dimension stores internally, so agents should filter on model slugs (which they know exactly) and group by api_key_id rather than filtering on resolved key names. Save the prompts that worked and re-run them monthly; the copy-prompt at the top chains all of these recipes into one full review.

Next steps