openrouter-analytics

OpenRouter Analytics

通过编程方式查询你的 OpenRouter 使用数据。使用 Analytics API 回答“我这个月花了多少钱？”“哪些模型费用最高？”以及“如何降低账单？”等问题。

先决条件

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

首次设置

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

决策树

用户想要……	操作
了解有哪些数据可用	运行 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 技能）
回答特定问题	将问题映射到指标和维度，然后查询

工作流

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

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

对于常见问题，suggest-queries.ts 会提供现成的查询模板。

发现可用数据

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

返回完整架构：指标、维度、筛选运算符和粒度。

筛选到特定部分：

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

有关如何解读架构响应，以及如何将用户问题映射到合适指标和维度的详细指导，请参阅 openrouter-analytics-schema 技能。

查询分析数据

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

有关完整的参数参考和查询构建指南，请参阅 openrouter-analytics-query 技能。

快速示例

按天拆分过去 7 天的支出：

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

费用最高的前 10 个模型：

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

按 API 密钥统计使用情况：

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

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

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

使用成本明细（credits、BYOK、上游、缓存、数据记录、网页搜索）：

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

返回一系列适用于常见问题的预构建查询模板，每个模板包含：

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

解读结果

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

向用户解读结果时：

• 支出指标（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）的单位为 USD。total_usage 包含 BYOK 推理成本。usage_data 通常为负数（数据记录折扣）
• Token 数量（tokens_total、tokens_prompt、tokens_completion）以模型原生 Token 为单位
• 延迟（avg_latency、p50_latency 等）的单位为毫秒。*_latency 是提供方侧的首 Token 时间；*_router_latency 是 OpenRouter 路由时间；*_total_time_to_first_token 是仅针对流式请求的两者之和；*_generation_time 是提供方侧的生成时间；*_inter_token_latency 是针对包含多个完成 Token 的流式请求，完成 Token 之间的平均间隔。每组指标都有 avg_、p50_、p90_、p95_、p99_ 变体，且不包含服务端工具行
• 比率（cache_hit_rate、possible_cache_hit_rate、cache_capture_rate）的取值范围为 0–1
• 吞吐量（avg_throughput、p50_/p90_/p95_/p99_throughput）以每秒完成 Token 数量计
• 设置 granularity 时，行中会包含一个 date__<granularity> 字段，用于表示时间段（例如：date__day、date__hour、date__month）
• 标签解析：维度 api_key_id、app、user 和 workspace 的原始 ID 会直接在数据行中替换为便于理解的名称（密钥名称、应用标题、用户名、工作区名称）；generation_id 和 session_id 返回原始值；特殊分桶会显示为相应标签（api_key_id -1 → Chatroom，app -1 → Unknown，最大 UUID 的工作区 → Unattributed）
• 截断：以编程方式处理输出时，请检查 metadata.truncated。如果为 true，则结果已截断至 --limit，属于部分数据集——在报告总量或排名前，请增大 --limit 或进行分页

成本优化建议

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

1. 按支出查询排名靠前的模型：--metrics total_usage,tokens_total,cache_hit_rate,request_count --dimensions model --order-by total_usage --limit 10
2. 查询成本细分：--metrics credits_usage,byok_usage,byok_fees,usage_upstream,usage_cache,usage_data,usage_web,usage_file --granularity day，查看支出流向
3. 留意以下情况：
   • 支出高但 cache_hit_rate 低的模型——提示词缓存可能有所帮助
   • 针对特定任务，可替换为更便宜替代方案的高价模型
   • 请求数较少但 Token 数量较高——可能表示提示词过长
   • reasoning_tokens 占总量比例较高的模型——如果不需要扩展思考，可考虑将其关闭
   • 相较于 usage_upstream，usage_web 或 usage_file 较高——网页搜索和文件处理附加成本可能较为显著

深入查看单次生成

若要查看分析结果中的特定生成或会话，请将 generation_id 或 session_id 添加为维度。这两者都只能用于生成（限 31 天）。generation_id 会返回结果集内每次生成的唯一 ID。session_id 会将无会话请求归为字面值 none：ClickHouse 列默认值为空字符串，查询构建器会将其合并为 none。使用 neq 'none' 可排除无会话请求；筛选 '' 不会匹配任何内容。

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

获取生成 ID（例如 gen-aBcDeFgHiJkLmNoPqRsT）后，使用 openrouter-generations skill 获取详细信息：

• get-generation — 获取完整请求元数据：成本明细、令牌数量、延迟、提供商路由链、结束原因等
• get-generation-content — 获取存储的提示词和补全文本（除非启用了 Zero Data Retention）

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

此工作流适用于通过分析找出成本最高或最慢的请求，再检查实际提示词和补全文本以了解原因。

API 参考

两个端点都需要通过 Authorization: Bearer sk-or-v1-... 提供管理密钥。

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

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