openrouter-analytics-schema

OpenRouter 分析架构发现

发现可供查询的分析数据。meta 端点会返回实时且始终最新的指标、维度、筛选运算符和粒度定义。

前提条件

• 一个 OpenRouter 管理密钥。管理密钥与常规 API 密钥分开——请前往 https://openrouter.ai/settings/management-keys 获取
• 通过 --api-key <key> 传入，或设置 OPENROUTER_API_KEY 环境变量

发现端点

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

或者通过 openrouter-analytics 技能脚本：

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

响应结构

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

了解指标

每个指标包含：

字段	含义
name	在查询请求中使用的标识符
display_label	易于理解的标签
is_rate	是否为比率／速率（取平均值，而非求和）
display_format	值的格式：number、currency、percent、latency 或 throughput

时间范围限制

大多数用量和成本指标支持最长 367 天 的时间范围，粒度为天或更粗。延迟／吞吐量指标、blended_cost_per_million_tokens 以及仅适用于生成记录的维度（provider、origin、country、data_region、skin、finish_reason、external_user、context_length_bucket、generation_id、session_id、streamed）的时间范围最长为 31 天，hour 粒度也有相同限制。可能的缓存指标（possible_cached_tokens、possible_cache_hit_rate、cache_capture_rate）始终读取小时汇总数据，因此也限制为 31 天，使用更粗的粒度也不会解除此限制。

超出上限时会返回 400，并在消息中说明适用的最大值，而不是返回截断后的结果。如果查询超时，请尝试缩短时间范围，或移除延迟／吞吐量指标和逐生成记录维度。

指标类别

用量指标（用量有多少）：

• request_count — API 请求数（最长 367 天）。不包括服务器工具行（与请求一同记录的网络搜索／文件解析费用），因此统计的是模型请求数，而非计费行项目数
• tokens_total、tokens_prompt、tokens_completion — Token 数（最长 367 天）
• reasoning_tokens — 用于扩展思考的 Token 数（最长 367 天）
• cached_tokens — 由缓存提供的 Token 数（最长 367 天）
• possible_cached_tokens — 符合缓存条件的提示词 Token 数，无论其是否已缓存（限制为 31 天，且仅支持小时汇总）
• byok_request_count — BYOK 请求数（最长 367 天）。查询读取原始生成记录时（同一请求中包含任何延迟／吞吐量指标或仅适用于生成记录的维度），不包括服务器工具行；但从汇总数据提供结果时仍会计入，因此对于使用服务器工具的 BYOK 流量，两种查询方式的结果可能不同
• guardrail_invoked_count — 触发护栏的请求数（限制为 31 天）
• response_cached_count — 由缓存提供的响应数（限制为 31 天） 成本指标（花费了多少钱）：
• total_usage — 总成本（美元），包括 BYOK 推理成本（最多 367 天）。计算方式为 sum(usage) + sum(byok_usage_inference)，因此能反映使用积分和 BYOK 用户的实际支出。
• byok_usage — BYOK（自带密钥）推理成本（美元，最多 367 天）
• credits_usage — 计入 OpenRouter 积分的所有费用（美元），包括 BYOK 平台费（最多 367 天）
• openrouter_usage — 非 BYOK 推理支出（美元）；不包括使用用户提供的密钥发送的请求（最多 31 天）
• byok_fees — BYOK 平台费（美元）；即 BYOK 请求的 credits_usage 中计收的平台费部分（最多 31 天）。credits_usage 包括非 BYOK 推理费用和这些 BYOK 平台费。
• usage_upstream — 服务提供商侧（上游）成本（美元，最多 367 天）
• usage_cache — 缓存成本部分（美元，最多 367 天）
• usage_data — 数据记录成本调整（美元）；应用数据记录折扣时通常为负值（最多 367 天）
• usage_web — 网页搜索成本（美元，最多 367 天）
• usage_upstream_web — 服务提供商侧网页搜索成本（美元，最多 367 天）
• usage_file — 文件处理成本（美元，最多 31 天）
• usage_upstream_file — 服务提供商侧文件处理成本（美元，最多 31 天）
• usage_web_fetch — 网页抓取成本（美元，最多 31 天）
• usage_upstream_web_fetch — 服务提供商侧网页抓取成本（美元，最多 31 天）
• blended_cost_per_million_tokens — 每 100 万个令牌的平均成本（提示词 + 补全），包括 BYOK 推理成本（最多 31 天；始终读取原始生成记录）。分子中不包括服务端工具支出。这是一项比率指标：没有令牌的时间桶中值为 null，因此不能跨行求和。

性能指标（速度如何；全部最多 31 天，除非另有说明，单位为毫秒）。每组指标都有 avg_、p50_、p90_、p95_ 和 p99_ 变体：

• *_latency — 服务提供商侧的首个令牌响应时间（非流式请求为完整响应时间）
• *_router_latency — 向服务提供商发送请求前，在 OpenRouter 路由中耗费的时间
• *_total_time_to_first_token — latency + router_latency，仅根据流式请求计算
• *_generation_time — 服务提供商侧的生成时间
• *_inter_token_latency — 连续补全令牌之间的平均时间，计算方式为 (generation_time - latency) / (native_tokens_completion - 1)；仅根据令牌数超过 1 个的流式请求计算
• *_throughput — 每秒补全令牌数，根据 native_tokens_completion / generation_time 计算；没有补全令牌的请求值为 null

所有性能指标都不包括服务端工具行（与请求一同记录的网页搜索／文件解析费用）。

效率指标（效果如何）：

• cache_hit_rate — 缓存令牌数与提示词令牌数之比（0–1）
• possible_cache_hit_rate — 符合缓存条件的提示词令牌数与提示词令牌数之比（0–1；最多 31 天，仅支持按小时汇总）
• cache_capture_rate — 实际从缓存中提供的、符合缓存条件的提示词令牌数所占比例（按定义介于 0–1；最多 31 天，仅支持按小时汇总）
• guardrail_invoked_rate — 触发护栏的请求所占比例
• response_cached_rate — 从缓存提供的响应所占比例

了解维度

每个维度包含以下字段：

字段	含义
name	查询请求中使用的标识符
display_label	便于人类阅读的标签

维度用于拆分数据，例如，“按模型查看支出”表示 dimensions: ["model"]。

单个查询最多可以组合 2 个维度（例如，["model", "provider"]）。

标签解析

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

维度	解析为
api_key_id	密钥名称/标签
app	应用标题或来源 URL
user	用户名或电子邮件地址
workspace	工作区名称（已删除的工作区仍会显示名称）

哨兵值桶会显示命名标签，而非原始值：

• api_key_id -1 → Chatroom（没有 API 密钥的流量，例如聊天室请求）
• app -1 → Unknown（没有应用归属的行）
• workspace 最大 UUID 哨兵值 → Unattributed（写入行时无法解析工作区）

所有其他维度（例如 model、provider、country）均按原样返回，不进行解析。

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

工作区解析功能推出前写入的行，其工作区 UUID 全为零。分组时会将它们归入账户的默认工作区；对默认工作区 UUID 的筛选也会匹配这些行，因此同一个逻辑工作区始终只会显示为一组。

维度类别

适用于所有时间范围：

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

仅适用于 31 天的时间范围：

• generation_id — 每次生成的唯一 ID（用于深入查看单个请求，然后通过 openrouter-generations 技能检查）
• provider — 上游提供商名称
• origin — 请求来源/源
• country — 请求所在国家/地区
• data_region — 提供请求服务的数据区域；空值会报告为 global
• skin — API 样式（请求使用的 API 形态，根据请求路径推导）
• finish_reason — 生成结束原因（stop、length 等）
• external_user — 调用方传入的自定义用户 ID
• context_length_bucket — 分桶后的上下文长度（1K、10K、100K 等）
• session_id — 请求所属的会话；无会话的请求会归为字面值 none
• streamed — 请求是否采用流式传输；值为字符串 true 和 false

分类器维度

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

• 使用 classifier_dimensions 请求字段按分类器生成的值分组
• 每个查询最多可指定 2 个分类器维度名称；指定两个名称时，结果会同时按两者交叉分组
• 使用 classifier_filters 请求字段按分类器值筛选
• 分类器必须属于你的账户（由服务器端验证）
• 使用分类器维度/筛选条件时，查询时间范围不得超过 31 天
• 完整的请求格式请参阅 openrouter-analytics-query 技能

将问题映射为分类器查询

问题模式	请求字段	备注
“按主题统计支出”	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 }	包含未分类的行

了解运算符

查询请求中 filters 数组的筛选运算符：

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

in 和 not_in 可以接受可选参数 include_unset: true，以匹配维度没有值的行。只有具有未设置值分组的维度支持此参数（api_key_id、app、user）；其他维度均会返回 400 错误。

了解粒度

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

粒度	适用场景
minute	最近几小时、实时监控
hour	最近 1–3 天
day	最近一周到 3 个月
week	最近 3–12 个月
month	按年查看趋势

未设置粒度时，查询会返回不按时间分桶的汇总总量。

将问题映射为查询

使用本指南将自然语言问题转换为合适的指标／维度／筛选条件组合：

问题模式	指标	维度	备注
“我花了多少钱？”	total_usage	—	添加粒度以查看趋势
“哪些模型最贵？”	total_usage	model	按 total_usage 降序排列
“有多少个请求？”	request_count	—	添加 model 或 api_key_id 以细分
“有多少个 token？”	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 天
“流式传输有多流畅？”	p50_inter_token_latency、p95_inter_token_latency	model 或 provider	限制为 31 天。仅统计完成 token 数量大于 1 的流式请求
“按国家查看用量”	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	最长 367 天
“BYOK 与额度的用量细分？”	byok_usage、credits_usage	—	两者均最长 367 天
“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	—	完整费用明细（最长 367 天）
“网页搜索费用？”	usage_web、usage_upstream_web	model	最长 367 天
“文件处理费用？”	usage_file、usage_upstream_file	model	限制为 31 天
“网页抓取费用？”	usage_web_fetch、usage_upstream_web_fetch	model	限制为 31 天

筛选值参考

查询结果中的多个维度已解析为标签——响应会显示易读的名称，但筛选条件必须使用底层 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。筛选默认工作区 UUID 时，也会匹配在工作区解析功能推出前写入的旧行。	工作区设置页面或 GET /api/v1/workspaces，而不是结果中显示的工作区名称。
app	数字应用 ID	生成元数据（app_id 字段）或应用设置，而不是结果中显示的应用标题。
model	Permaslug（例如 openai/gpt-4o）	模型页面 URL 或 GET /api/v1/models，而不是显示名称。

其他维度（provider、origin、country、finish_reason、external_user 等）不会进行增强处理——筛选值与结果中返回的值一致。

限制

• 每次查询最多 2 个维度
• 每次查询最多 20 个筛选条件
• 每次查询最多 2 个分类器维度名称
• 每次查询最多 10 个分类器筛选条件
• 每次查询最多返回 10,000 行（默认 1,000 行）
• group_limit（1–10,000）：控制每种维度组合的最大行数。对于包含维度的时间序列查询，会自动计算该值，以确保覆盖完整时间窗口。也可显式设置该值来限制每组行数（例如，每天每个模型取前 N 条）。
• 大多数用量／成本指标：按日粒度时最长 367 天
• 延迟／吞吐量指标、blended_cost_per_million_tokens 和单次生成维度：最长 31 天
• 分类器维度／筛选条件：始终限制为 31 天
• 分钟粒度：仅当时间窗口 ≤ 3 小时时可用
• hour 粒度会读取分钟级物化视图：最长 31 天
• 可能的缓存指标（possible_cached_tokens、possible_cache_hit_rate、cache_capture_rate）：最长 31 天，粒度为 hour 或更粗，并且仅支持 model／provider 维度和筛选条件——使用任何其他维度、筛选条件或分类器，或使用 minute 粒度，都会返回 400
• 速率限制为每分钟 64 个请求