openrouter-analytics-schema

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenRouter Analytics Schema Discovery

OpenRouter分析架构探索

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

拥有OpenRouter 管理密钥。管理密钥与常规API密钥分开——可在https://openrouter.ai/settings/management-keys获取
通过
```
--api-key <key>
```
传入密钥，或设置
```
OPENROUTER_API_KEY
```
环境变量

Discovery Endpoint

探索端点

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

Or via the

openrouter-analytics

skill scripts:

bash

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

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

或通过

openrouter-analytics

技能脚本调用：

bash

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

Response Shape

响应结构

json

{
  "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" }
    ]
  }
}

json

{
  "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`

每个指标包含以下字段：

字段	含义
`name`	查询请求中使用的标识符
`display_label`	易读的显示标签
`is_rate`	是否为比率/速率指标（取平均值而非总和）
`display_format`	值的格式化方式： `number` （数字）、 `currency` （货币）、 `percent` （百分比）、 `latency` （延迟）或 `throughput` （吞吐量）

Time Range Limits

时间范围限制

Most volume and cost metrics support time ranges up to 365 days with daily granularity. Latency/throughput metrics and some dimensions (

provider

origin

country

finish_reason

external_user

context_length_bucket

generation_id

) are limited to 31-day time ranges. If a query times out, try narrowing the time range or removing latency/throughput metrics and per-generation dimensions.

大多数流量和成本指标支持最长365天的时间范围，粒度为天。延迟/吞吐量指标和部分维度（

provider

、

origin

、

country

、

finish_reason

、

external_user

、

context_length_bucket

、

generation_id

）的时间范围限制为31天。如果查询超时，尝试缩小时间范围，或移除延迟/吞吐量指标和单生成维度。

Metric Categories

指标分类

Volume metrics (how much):

```
request_count
```
— number of API requests (up to 365 days)

tokens_total

tokens_prompt

tokens_completion

— token counts (up to 365 days)

```
reasoning_tokens
```
— tokens used for extended thinking (up to 365 days)
```
cached_tokens
```
— tokens served from cache (up to 365 days)
```
byok_request_count
```
— number of BYOK requests (up to 365 days)
```
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 365 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 365 days)
```
credits_usage
```
— all charges billed to OpenRouter credits in USD, including BYOK platform fees (up to 365 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 365 days)
```
usage_cache
```
— cache cost component in USD (up to 365 days)
```
usage_data
```
— data logging cost adjustment in USD; typically negative when a data logging discount applies (up to 365 days)
```
usage_web
```
— web search cost in USD (up to 365 days)
```
usage_upstream_web
```
— provider-side web search cost in USD (up to 365 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)

Performance metrics (how fast):

avg_latency

p50_latency

p90_latency

p99_latency

— response latency in milliseconds

avg_throughput

p50_throughput

p90_throughput

p99_throughput

— tokens per second

Efficiency metrics (how well):

```
cache_hit_rate
```
— ratio of cached tokens to prompt tokens (0–1)
```
guardrail_invoked_rate
```
— ratio of requests that triggered guardrails
```
response_cached_rate
```
— ratio of responses served from cache

流量指标（数量维度）：

```
request_count
```
— API请求数量（最长365天）

tokens_total

tokens_prompt

tokens_completion

— 令牌数量（最长365天）

```
reasoning_tokens
```
— 用于扩展思考的令牌数量（最长365天）
```
cached_tokens
```
— 从缓存返回的令牌数量（最长365天）
```
byok_request_count
```
— BYOK请求数量（最长365天）
```
guardrail_invoked_count
```
— 触发防护机制的请求数量（31天限制）
```
response_cached_count
```
— 从缓存返回的响应数量（31天限制）

成本指标（费用维度）：

```
total_usage
```
— 总费用（美元），包含BYOK推理成本（最长365天）。计算方式为
```
sum(usage) + sum(byok_usage_inference)
```
，反映信用额度用户和BYOK用户的实际支出。
```
byok_usage
```
— BYOK（自带密钥）推理成本（美元）（最长365天）
```
credits_usage
```
— 所有计入OpenRouter信用额度的费用（美元），包含BYOK平台服务费（最长365天）
```
openrouter_usage
```
— 非BYOK推理支出（美元）；排除用户提供密钥的请求（31天限制）
```
byok_fees
```
— BYOK平台服务费（美元）；
```
credits_usage
```
中BYOK请求对应的平台服务费部分（31天限制）。
```
credits_usage
```
包含非BYOK推理费用和这些BYOK平台服务费。
```
usage_upstream
```
— 上游供应商成本（美元）（最长365天）
```
usage_cache
```
— 缓存成本组件（美元）（最长365天）
```
usage_data
```
— 数据日志成本调整（美元）；通常在应用数据日志折扣时为负值（最长365天）
```
usage_web
```
— 网页搜索成本（美元）（最长365天）
```
usage_upstream_web
```
— 上游供应商网页搜索成本（美元）（最长365天）
```
usage_file
```
— 文件处理成本（美元）（31天限制）
```
usage_upstream_file
```
— 上游供应商文件处理成本（美元）（31天限制）
```
usage_web_fetch
```
— 网页抓取成本（美元）（31天限制）
```
usage_upstream_web_fetch
```
— 上游供应商网页抓取成本（美元）（31天限制）

性能指标（速度维度）：

avg_latency

p50_latency

p90_latency

p99_latency

— 响应延迟（毫秒）

avg_throughput

p50_throughput

p90_throughput

p99_throughput

— 每秒处理令牌数

效率指标（效果维度）：

```
cache_hit_rate
```
— 缓存令牌占提示令牌的比率（0–1）
```
guardrail_invoked_rate
```
— 触发防护机制的请求比率
```
response_cached_rate
```
— 从缓存返回的响应比率

Understanding Dimensions

维度说明

Each dimension has:

Field	Meaning
`name`	Identifier to use in query requests
`display_label`	Human-readable label

Dimensions are what you break down by — "show me spend by model" means

dimensions: ["model"]

You can combine up to 2 dimensions in a single query (e.g.,

["model", "provider"]

每个维度包含以下字段：

字段	含义
`name`	查询请求中使用的标识符
`display_label`	易读的显示标签

维度用于拆分数据——“按模型展示支出”意味着

dimensions: ["model"]

。

单个查询最多可组合2个维度（例如

["model", "provider"]

）。

Label Resolution

标签解析

Some dimensions have their raw IDs automatically resolved to human-readable labels in query results. Data rows contain the resolved display names directly:

Dimension	Resolved to
`api_key_id`	Key name/label
`app`	App title or origin URL
`user`	User name or email address
`workspace`	Workspace name

All other dimensions (e.g.,

model

provider

country

) are returned as-is without resolution.

Rows with an empty
user
value represent traffic not attributed to a specific org member (e.g., API keys created at the org level).

部分维度的原始ID会在查询结果中自动解析为易读标签。数据行直接包含解析后的显示名称：

维度	解析结果
`api_key_id`	密钥名称/标签
`app`	应用标题或来源URL
`user`	用户名或邮箱地址
`workspace`	工作区名称

其他维度（如

model

、

provider

、

country

）将按原始值返回，不进行解析。

user
值为空的行代表未归属到特定组织成员的流量（例如在组织级别创建的API密钥产生的流量）。

Dimension Categories

维度分类

Available with all time ranges:

```
model
```
— the OpenRouter model ID (permaslug)
```
variant
```
— model variant (e.g., standard, extended)
```
api_key_id
```
— which API key made the request
```
user
```
— the creator user ID (for org-level queries)
```
workspace
```
— workspace ID
```
app
```
— application ID

Limited to 31-day time ranges:

```
generation_id
```
— unique ID for each generation (use to drill down to individual requests, then inspect via the
```
openrouter-generations
```
skill)
```
provider
```
— upstream provider name
```
origin
```
— request origin/source
```
country
```
— request country
```
finish_reason
```
— why the generation ended (stop, length, etc.)
```
external_user
```
— custom user ID passed by the caller
```
context_length_bucket
```
— bucketed context length (1K, 10K, 100K, etc.)

支持全时间范围的维度：

```
model
```
— OpenRouter模型ID（永久别名）
```
variant
```
— 模型变体（例如standard、extended）
```
api_key_id
```
— 发起请求的API密钥
```
user
```
— 创建者用户ID（组织级查询）
```
workspace
```
— 工作区ID
```
app
```
— 应用ID

仅支持31天时间范围的维度：

```
generation_id
```
— 每个生成任务的唯一ID（用于钻取到单个请求，然后通过
```
openrouter-generations
```
技能查看详细信息）
```
provider
```
— 上游供应商名称
```
origin
```
— 请求来源/发起方
```
country
```
— 请求发起国家
```
finish_reason
```
— 生成任务结束原因（stop、length等）
```
external_user
```
— 调用方传入的自定义用户ID
```
context_length_bucket
```
— 分桶后的上下文长度（1K、10K、100K等）

Classifier Dimensions

分类器维度

Beyond the standard dimensions above, you can group by classifier dimensions — dynamic labels produced by a user-created classifier (e.g., topic, sentiment, category).

Use the
```
classifier_dimensions
```
request field to group by classifier-produced values
Use the
```
classifier_filters
```
request field to filter on classifier values
The classifier must belong to your account (validated server-side)
Classifier dimensions/filters limit the query time range to 31 days
See the
```
openrouter-analytics-query
```
skill for the full request shape

除上述标准维度外，你还可以按分类器维度分组——由用户创建的分类器生成的动态标签（例如主题、情感、类别）。

使用
```
classifier_dimensions
```
请求字段按分类器生成的值分组
使用
```
classifier_filters
```
请求字段按分类器值过滤
分类器必须属于你的账户（服务器端验证）
分类器维度/过滤器会将查询时间范围限制为31天
完整请求结构请参考
```
openrouter-analytics-query
```
技能

Mapping Questions to Classifier Queries

问题到分类器查询的映射

Question pattern Request fields Notes

"Spend by topic"

Question pattern	Request fields	Notes
"Spend by topic"	`classifier_dimensions: { classifier_id, dimension_names: ["topic"] }` + `metrics: ["total_usage"]`	Single dimension → column aliased to `topic`
"Only billing-related requests"	`classifier_filters: { classifier_id, filters: [{ field: "category", operator: "eq", value: "billing" }] }`	Filters support `eq` , `neq` , `in` , `not_in` only
"Sentiment breakdown including unclassified"	`classifier_dimensions: { classifier_id, dimension_names: ["sentiment"], include_nulls: true }`	Includes rows without classification

classifier_dimensions: { classifier_id, dimension_names: ["topic"] }

metrics: ["total_usage"]

Single dimension → column aliased to

topic

"Only billing-related requests"

classifier_filters: { classifier_id, filters: [{ field: "category", operator: "eq", value: "billing" }] }

Filters support

eq

neq

in

not_in

only

"Sentiment breakdown including unclassified"

classifier_dimensions: { classifier_id, dimension_names: ["sentiment"], include_nulls: true }

Includes rows without classification

问题模式请求字段说明

“按主题展示支出”

问题模式	请求字段	说明
“按主题展示支出”	`classifier_dimensions: { classifier_id, dimension_names: ["topic"] }` + `metrics: ["total_usage"]`	单个维度→列别名设为 `topic`
“仅展示账单相关请求”	`classifier_filters: { classifier_id, filters: [{ field: "category", operator: "eq", value: "billing" }] }`	过滤器仅支持 `eq` 、 `neq` 、 `in` 、 `not_in`
“包含未分类内容的情感分布”	`classifier_dimensions: { classifier_id, dimension_names: ["sentiment"], include_nulls: true }`	包含未被分类的行

classifier_dimensions: { classifier_id, dimension_names: ["topic"] }

metrics: ["total_usage"]

单个维度→列别名设为

topic

“仅展示账单相关请求”

classifier_filters: { classifier_id, filters: [{ field: "category", operator: "eq", value: "billing" }] }

过滤器仅支持

eq

、

neq

、

in

、

not_in

“包含未分类内容的情感分布”

classifier_dimensions: { classifier_id, dimension_names: ["sentiment"], include_nulls: true }

包含未被分类的行

Understanding Operators

运算符说明

Filter operators for the

filters

array in query requests:

Operator	Value Type	Meaning
`eq`	scalar	Equals
`neq`	scalar	Not equals
`gt`	scalar	Greater than
`gte`	scalar	Greater than or equal
`lt`	scalar	Less than
`lte`	scalar	Less than or equal
`in`	array	In list
`not_in`	array	Not in list

查询请求中

filters

数组支持的过滤运算符：

运算符	值类型	含义
`eq`	标量	等于
`neq`	标量	不等于
`gt`	标量	大于
`gte`	标量	大于等于
`lt`	标量	小于
`lte`	标量	小于等于
`in`	数组	在列表中
`not_in`	数组	不在列表中

Understanding Granularities

时间粒度说明

Time bucketing for time-series queries:

Granularity	Use when
`minute`	Last few hours, real-time monitoring
`hour`	Last 1–3 days
`day`	Last week to 3 months
`week`	Last 3–12 months
`month`	Year-scale trends

When no granularity is set, the query returns aggregate totals without time bucketing.

时间序列查询的时间分桶方式：

粒度	使用场景
`minute`	最近几小时，实时监控
`hour`	最近1–3天
`day`	最近一周到3个月
`week`	最近3–12个月
`month`	年度趋势分析

未设置粒度时，查询将返回无时间分桶的聚合总计。

Mapping Questions to Queries

问题到查询的映射

Use this guide to translate natural-language questions into the right metric/dimension/filter combination:

Question pattern	Metrics	Dimensions	Notes
"How much did I spend?"	`total_usage`	—	Add granularity for trends
"Which models cost the most?"	`total_usage`	`model`	Order by `total_usage` desc
"How many requests?"	`request_count`	—	Add `model` or `api_key_id` for breakdown
"How many tokens?"	`tokens_total`	—	Use `tokens_prompt` / `tokens_completion` for split
"Which provider is fastest?"	`avg_latency` , `p90_latency`	`provider`	31-day limit
"What's my cache hit rate?"	`cache_hit_rate`	`model`	Rate metric — shows per-model caching
"Which API key uses the most?"	`request_count` , `total_usage`	`api_key_id`	—
"Usage over time"	`request_count` or `total_usage`	—	Set `granularity: "day"`
"Latency trends"	`p90_latency`	—	Set `granularity: "hour"` , 31d limit
"Usage by country"	`request_count`	`country`	31-day limit
"How can I save money?"	`total_usage` , `cache_hit_rate` , `tokens_total`	`model`	See cost optimization in `openrouter-analytics` skill
"Show me individual requests"	`total_usage` , `tokens_total`	`generation_id`	31-day limit. Use returned IDs with `openrouter-generations` skill for full metadata and content
"How much BYOK spend?"	`byok_usage`	`model`	Up to 365 days
"BYOK vs credits split?"	`byok_usage` , `credits_usage`	—	Both up to 365 days
"BYOK platform fees?"	`byok_fees`	`model`	31-day limit
"Non-BYOK inference spend?"	`openrouter_usage`	`model`	31-day limit
"How many guardrail triggers?"	`guardrail_invoked_count` , `guardrail_invoked_rate`	`model`	31-day limit
"How many cached responses?"	`response_cached_count` , `response_cached_rate`	`model`	31-day limit
"Where does my spend go?"	`usage_upstream` , `usage_cache` , `usage_data`	—	Full cost breakdown (up to 365 days)
"Web search costs?"	`usage_web` , `usage_upstream_web`	`model`	Up to 365 days
"File processing costs?"	`usage_file` , `usage_upstream_file`	`model`	31-day limit
"Web fetch costs?"	`usage_web_fetch` , `usage_upstream_web_fetch`	`model`	31-day limit

使用本指南将自然语言问题转换为正确的指标/维度/过滤器组合：

问题模式	指标	维度	说明
“我花费了多少钱？”	`total_usage`	—	添加粒度查看趋势
“哪些模型成本最高？”	`total_usage`	`model`	按 `total_usage` 降序排列
“有多少请求？”	`request_count`	—	添加 `model` 或 `api_key_id` 查看拆分数据
“有多少令牌？”	`tokens_total`	—	使用 `tokens_prompt` / `tokens_completion` 查看拆分数据
“哪个供应商速度最快？”	`avg_latency` , `p90_latency`	`provider`	31天限制
“我的缓存命中率是多少？”	`cache_hit_rate`	`model`	速率指标——展示各模型的缓存情况
“哪个API密钥使用量最大？”	`request_count` , `total_usage`	`api_key_id`	—
“随时间变化的使用情况”	`request_count` 或 `total_usage`	—	设置 `granularity: "day"`
“延迟趋势”	`p90_latency`	—	设置 `granularity: "hour"` ，31天限制
“按国家划分的使用情况”	`request_count`	`country`	31天限制
“如何节省成本？”	`total_usage` , `cache_hit_rate` , `tokens_total`	`model`	参考 `openrouter-analytics` 技能中的成本优化内容
“展示单个请求详情”	`total_usage` , `tokens_total`	`generation_id`	31天限制。使用返回的ID通过 `openrouter-generations` 技能查看完整元数据和内容
“BYOK支出是多少？”	`byok_usage`	`model`	最长365天
“BYOK与信用额度支出拆分？”	`byok_usage` , `credits_usage`	—	均支持最长365天
“BYOK平台服务费是多少？”	`byok_fees`	`model`	31天限制
“非BYOK推理支出是多少？”	`openrouter_usage`	`model`	31天限制
“防护机制触发了多少次？”	`guardrail_invoked_count` , `guardrail_invoked_rate`	`model`	31天限制
“有多少缓存响应？”	`response_cached_count` , `response_cached_rate`	`model`	31天限制
“我的支出流向哪里？”	`usage_upstream` , `usage_cache` , `usage_data`	—	完整成本拆分（最长365天）
“网页搜索成本是多少？”	`usage_web` , `usage_upstream_web`	`model`	最长365天
“文件处理成本是多少？”	`usage_file` , `usage_upstream_file`	`model`	31天限制
“网页抓取成本是多少？”	`usage_web_fetch` , `usage_upstream_web_fetch`	`model`	31天限制

Filter Value Reference

过滤值参考

Several dimensions are label-resolved in query results — the response shows human-readable names, but filters must use the underlying ID. Here's where to find each:

Dimension	Filter value	Where to find it
`api_key_id`	Numeric ID or 64-char SHA-256 hash	Numeric ID: generation metadata ( `api_key_id` field). Hash: `GET /api/v1/keys` ( `key_hash` field). Hashes are auto-resolved server-side. If a hash can't be resolved, a sentinel value returns zero rows (no error).
`user`	Clerk user ID (e.g. `user_abc123` )	User settings or org member list — not the display name/email shown in results.
`workspace`	Workspace UUID	Workspace settings page or `GET /api/v1/workspaces` — not the workspace name shown in results.
`app`	Numeric app ID	Generation metadata ( `app_id` field) or app settings — not the app title shown in results.
`model`	Permaslug (e.g. `openai/gpt-4o` )	Model page URL or `GET /api/v1/models` — not the display name.

Other dimensions (

provider

origin

country

finish_reason

external_user

, etc.) are not enriched — filter values match what's returned in results.

部分维度在查询结果中会被标签解析——响应显示易读名称，但过滤时必须使用底层ID。以下是各维度过滤值的获取方式：

维度	过滤值	获取位置
`api_key_id`	数字ID 或 64位SHA-256哈希	数字ID：生成任务元数据（ `api_key_id` 字段）。哈希： `GET /api/v1/keys` （ `key_hash` 字段）。哈希会在服务器端自动解析。如果哈希无法解析，将返回空结果行（无错误）。
`user`	Clerk用户ID（例如 `user_abc123` ）	用户设置或组织成员列表——不是结果中显示的用户名/邮箱。
`workspace`	工作区UUID	工作区设置页面或 `GET /api/v1/workspaces` ——不是结果中显示的工作区名称。
`app`	数字应用ID	生成任务元数据（ `app_id` 字段）或应用设置——不是结果中显示的应用标题。
`model`	永久别名（例如 `openai/gpt-4o` ）	模型页面URL或 `GET /api/v1/models` ——不是显示名称。

其他维度（

provider

、

origin

、

country

、

finish_reason

、

external_user

等）不会被增强——过滤值与结果中返回的值一致。

Constraints

约束条件

Maximum 2 dimensions per query
Maximum 20 filters per query
Maximum 10 classifier dimensions per query
Maximum 10 classifier filters per query
Maximum 10,000 rows returned per query (default 1,000)
```
group_limit
```
(1–10,000): controls max rows per dimension combination. Auto-computed on time-series queries with dimensions to guarantee full time-window coverage. Set explicitly to cap per-group rows (e.g., top N per model per day).
Most volume/cost metrics: up to 365 days with daily granularity
Latency/throughput metrics and per-generation dimensions: up to 31 days
Classifier dimensions/filters: always limited to 31 days
Minute granularity: only available when the time window is ≤ 3 hours
Rate-limited to 64 requests per minute

单个查询最多支持2个维度
单个查询最多支持20个过滤器
单个查询最多支持10个分类器维度
单个查询最多支持10个分类器过滤器
单个查询最多返回10,000行结果（默认1,000行）
```
group_limit
```
（1–10,000）：控制每个维度组合的最大行数。在带维度的时间序列查询中会自动计算，以保证完整时间窗口覆盖。可显式设置以限制每组行数（例如每天排名前N的模型）。
大多数流量/成本指标：最长365天时间范围，粒度为天
延迟/吞吐量指标和单生成维度：最长31天时间范围
分类器维度/过滤器：始终限制为31天
分钟粒度：仅在时间窗口≤3小时时可用
速率限制：每分钟最多64次请求 ",