openrouter-analytics

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

以编程方式查询你的OpenRouter使用数据。使用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

一个OpenRouter management key（配置密钥）。普通API密钥会返回403错误。
在https://openrouter.ai/settings/management-keys获取management key（与常规API密钥页面分开）
通过
```
--api-key <key>
```
传递密钥，或设置
```
OPENROUTER_API_KEY
```
环境变量

First-Time Setup

首次设置

bash

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

bash

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

用户想要…	操作步骤
了解可用数据	运行 `discover-schema.ts` 查看指标、维度和筛选条件
查看支出/使用情况/请求量	使用合适的指标运行 `query-analytics.ts`
按模型、提供商、API密钥细分	在查询中添加 `--dimensions` 参数
查看时间趋势	添加 `--granularity day` （或 `hour` 、 `week` 、 `month` ）
降低成本	运行 `suggest-queries.ts` ，找到成本优化模板并执行
检查单个生成任务	添加 `--dimensions generation_id` ，然后使用 `openrouter-generations` 技能查看详情
按分类器标签细分	在请求体中使用 `classifier_dimensions` （详见 `openrouter-analytics-query` 技能）
按分类器标签筛选	在请求体中使用 `classifier_filters` （详见 `openrouter-analytics-query` 技能）
回答特定问题	将问题映射为指标+维度，然后执行查询

Workflow

工作流程

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

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

For common questions,

suggest-queries.ts

provides ready-made query templates.

回答用户分析问题的推荐工作流程：

发现 — 调用
```
discover-schema.ts
```
查看可用的指标和维度
映射 — 将用户的问题转换为指标、维度、筛选条件和时间范围
查询 — 通过
```
query-analytics.ts
```
执行查询
解读 — 分析返回的数据并解释结果

对于常见问题，

suggest-queries.ts

提供了现成的查询模板。

Discover Available Data

发现可用数据

bash

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

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

Filter to a specific section:

bash

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.

bash

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

返回完整的 schema：指标、维度、筛选运算符和时间粒度。

筛选特定部分：

bash

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

如需了解解读schema响应以及将用户问题映射到正确指标和维度的详细指南，请查看

openrouter-analytics-schema

技能。

Query Analytics Data

查询分析数据

bash

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.

bash

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

如需完整的参数参考和查询构建指南，请查看

openrouter-analytics-query

技能。

Quick Examples

快速示例

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

bash

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

Top 10 models by cost:

bash

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

Usage by API key:

bash

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):

bash

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):

bash

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

过去7天的支出，按天细分：

bash

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

按成本排序的前10个模型：

bash

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

按API密钥统计的使用情况：

bash

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

按提供商统计的延迟（限制为31天范围）：

bash

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

使用成本细分（ credits、BYOK、上游、缓存、数据日志、网页搜索）：

bash

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

常用查询模板

bash

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)

bash

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

返回针对常见问题的预构建查询模板列表，每个模板包含：

它能回答的自然语言问题
查询参数（指标、维度、筛选条件、时间范围）
传递给
```
query-analytics.ts
```
的CLI标志
解读指南（如适用）

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
Rates (
```
cache_hit_rate
```
) are 0–1 ratios
Throughput (
```
avg_throughput
```
) is 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
```
,
```
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
Truncation: when consuming output programmatically, check
```
metadata.truncated
```
. If
```
true
```
, the result was capped at
```
--limit
```
and is a partial dataset — raise
```
--limit
```
or paginate before reporting totals or rankings

查询端点返回一个数据行数组。每行是一个扁平对象，键与请求的指标和维度匹配。

为用户解读结果时：

支出指标（

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

）以美元为单位。

total_usage

包含BYOK推理成本。

usage_data

通常为负值（数据日志折扣）

Token计数（
```
tokens_total
```
、
```
tokens_prompt
```
、
```
tokens_completion
```
）以模型原生Token为单位
延迟（
```
avg_latency
```
、
```
p50_latency
```
等）以毫秒为单位
比率（
```
cache_hit_rate
```
）为0–1的数值
吞吐量（
```
avg_throughput
```
）为每秒Token数
设置
```
granularity
```
后，行中会包含时间桶的
```
date__<granularity>
```
字段（例如
```
date__day
```
、
```
date__hour
```
、
```
date__month
```
）
标签解析：维度
```
api_key_id
```
、
```
app
```
、
```
user
```
和
```
workspace
```
的原始ID会在数据行中直接替换为人类可读的名称（密钥名称、应用标题、用户名、工作区名称）；
```
generation_id
```
和
```
session_id
```
返回原始值
截断：以编程方式处理输出时，请检查
```
metadata.truncated
```
。如果为
```
true
```
，结果已被限制在
```
--limit
```
数量内，是部分数据集——在报告总数或排名前，提高
```
--limit
```
或进行分页

Cost Optimization Guidance

成本优化指南

When the user asks "How can I spend less?" or similar:

Query top models by spend:

--metrics total_usage,tokens_total,cache_hit_rate,request_count --dimensions model --order-by total_usage --limit 10

Query cost breakdown:

--metrics credits_usage,byok_usage,byok_fees,usage_upstream,usage_cache,usage_data,usage_web,usage_file --granularity day

to see where spend goes

Look for:
- Models with high spend but low
```
cache_hit_rate
```
  — prompt caching can help
- Expensive models that could be replaced by cheaper alternatives for specific tasks
- High token counts with low request counts — may indicate oversized prompts
- Models where
```
reasoning_tokens
```
  are a large fraction of total — consider disabling extended thinking if not needed
- High
```
usage_web
```
  or
```
usage_file
```
  relative to
```
usage_upstream
```
  — web search and file processing add-on costs may be significant

当用户询问“如何减少支出？”或类似问题时：

查询按支出排序的热门模型：

--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

，查看支出去向

关注以下情况：
- 支出高但
```
cache_hit_rate
```
  低的模型——提示缓存可能会有所帮助
- 可被更便宜的替代模型完成特定任务的昂贵模型
- Token计数高但请求量低的情况——可能提示提示词过大
- ```
reasoning_tokens
```
  占总Token数比例较大的模型——如果不需要，考虑禁用扩展思考功能
- ```
usage_web
```
  或
```
usage_file
```
  相对于
```
usage_upstream
```
  占比高的情况——网页搜索和文件处理的附加成本可能很高

Drilling Down to Individual Generations

深入到单个生成任务

To inspect specific generations or sessions from your analytics results, add

generation_id

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.

bash

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 more
get-generation-content
— Fetch the stored prompt and completion text (unless Zero Data Retention was enabled)

bash

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.

要从分析结果中检查特定的生成任务或会话，添加

generation_id

或

session_id

作为维度。两者都是仅适用于生成任务的维度（31天限制）。

generation_id

返回结果集中每个生成任务的唯一ID。

session_id

将无会话请求分组并筛选为字面量

none

：ClickHouse列默认为空字符串，查询构建器将其合并为

none

。使用

neq 'none'

排除无会话请求；筛选

''

不会匹配任何内容。

bash

npx tsx query-analytics.ts --metrics total_usage,tokens_total --dimensions generation_id --order-by total_usage --limit 10

一旦你获得了生成任务ID（例如

gen-aBcDeFgHiJkLmNoPqRsT

），使用

openrouter-generations

技能获取详细信息：

get-generation
— 获取完整的请求元数据：成本细分、Token计数、延迟、提供商路由链、结束原因等
get-generation-content
— 获取存储的提示词和完成文本（除非启用了零数据保留）

bash

cd <openrouter-generations-skill-path>/scripts
npx tsx get-generation.ts gen-aBcDeFgHiJkLmNoPqRsT
npx tsx get-generation-content.ts gen-aBcDeFgHiJkLmNoPqRsT

此工作流程有助于通过分析识别出最昂贵或最慢的请求，然后检查实际的提示词/完成内容以了解原因。

API Reference

API参考

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

两个端点都需要通过

Authorization: Bearer sk-or-v1-...

传递management key。

端点	方法	描述
`/api/v1/analytics/meta`	GET	返回可用的指标、维度、运算符、时间粒度
`/api/v1/analytics/query`	POST	执行分析查询并返回结构化数据

完整文档：https://openrouter.ai/docs/api/api-reference/analytics