用户活动分析导读
analytics 适合回答趋势问题，不适合替代 request-level 排障。先把这个边界分清。
GET/v1/customer/analytics
analytics 的价值不在“又一个统计接口”，而在于把 request-level ledger 聚合成你能看趋势、 看分组、看 spend composition 的视图。但它回答的是 趋势问题，不适合解释单条请求的收费或失败原因。
最值得先看的参数
| Name | Type | Required | Description |
|---|---|---|---|
start_date | YYYY-MM-DD | Required | 查询起始日期。趋势判断必须先把窗口定清楚。 |
end_date | YYYY-MM-DD | Required | 查询结束日期。别拿不同时长的窗口直接对比。 |
api_key_id | string | 按 key 过滤。适合解释某个团队、环境或应用的趋势。 |
最关键的返回字段
text
summary.total_spend
summary.shared_model_spend
summary.byok_platform_fees
summary.managed_tool_fees
summary.agent_runtime_fees
summary.search_requests
timeseries[].total_spend
timeseries[].shared_model_spend
timeseries[].byok_platform_fees
timeseries[].managed_tool_fees
timeseries[].agent_runtime_fees最小请求
bash
curl "https://api.therouter.ai/v1/customer/analytics?start_date=2026-03-01&end_date=2026-03-07" \
-H "Authorization: Bearer $THEROUTER_API_KEY"看懂分层，比看总数更重要
如果一个团队总 spend 没变，但
byok_platform_fees、managed_tool_fees或 search_requests 在变，应该先确认变化来自哪个费用分层，而不是只盯着总花费。什么时候该看 analytics
- 你在看一周或一月的 spend 趋势，而不是单次请求。
- 你想看 shared / BYOK / 外部 tool 成本结构有没有变化。
- 你想看某个 key、某个团队或环境的流量是不是异常抬头。
最容易犯的错
text
1. 用 analytics 去解释单个 request 为什么收费不同。
2. 只看 total_spend，不看 shared / BYOK / tool 分层。
3. 用不同时间窗口做直接对比，得出错误结论。
4. 把 grouped analytics 当成 usage statement。