Claude API 出了新的用量和花费分析接口（测试版），旧的 Usage and Cost API 改标 legacy

2026 年 10 月 29 日，Claude 开发平台的发布说明里多了一条：新的 Usage and Cost Analytics API 上线，目前是测试版。它查的是组织在 Claude API 上用了多少 token、花了多少钱，和控制台里用量页、花费页的数据差不多，但可以按更多维度拆开。

同一天，原来的 Usage and Cost API 改标 legacy。它还能用，官方也仍然支持，只是新接的建议改用新接口。

谁用得上

只有有组织管理凭据的人用得上：

• 控制台组织：用 Admin key，或者带 org:admin 范围的 OAuth 令牌。个人账号没有 Admin API。
• claude.ai 企业版组织：用主所有者在 claude.ai 里建的、带 read:analytics 范围的 Analytics key。

走中转站的读者用不上。这个接口查的是你自己的官方组织，中转站不会给你它那边的管理凭据，你在中转站花了多少，要看中转站自己的后台。

新接口有什么

• 两个地址：/v1/organizations/analytics/usage 返回 token 数和请求数，/v1/organizations/analytics/cost 返回美元金额。
• 每个请求都要带 anthropic-beta: analytics-usage-cost-2026-08-24，再加平常的 anthropic-version。官方 SDK 和命令行工具 ant 会自动带上这两个头，也会自动翻页。
• 能拆开看的维度多了：模型、工作区、API key、服务档位、发起请求的人或服务账号，还有 Managed Agents 的智能体、环境、部署和会话等。既能分组，也能按工作区、key 这些条件筛选。
• 时间桶可以按天、按小时、按分钟。
• 每一行的用量分成没走缓存的输入、缓存写（5 分钟和 1 小时两种）、缓存读、输出、合计，另有联网搜索次数和请求数。整个响应还带一个 data_refreshed_at，说明数据算到了什么时候。
• 控制台组织和企业版用同一套地址、参数和字段。 以前文档说 Admin key 和企业版的 Analytics key 互不通用，现在这个接口是唯一的例外。
• Claude Platform on AWS 和 Google Cloud 上由 Anthropic 运营的那种也能用，各用自己平台的地址和凭据。AWS 上每次只查一个区域，要覆盖整个组织得把各区域都查一遍，有几个维度（比如 user profile、Managed Agents 的几项）一律是 null。

官方文档里的第一个例子，按模型看 9 月第一周每天的用量：

curl --globoff "https://api.anthropic.com/v1/organizations/analytics/usage?\
starting_at=2026-09-01T00:00:00Z&\
ending_at=2026-09-08T00:00:00Z&\
time_bucket_width=1d&\
group_by[]=model&\
limit=10" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: analytics-usage-cost-2026-08-24" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

网址里有 []，要加 --globoff，不然 curl 会把方括号当成通配。

哪些改成了 legacy

• 控制台组织的 /v1/organizations/usage_report/messages 和 /v1/organizations/cost_report，也就是原来的 Usage and Cost API。
• 企业版 Claude Enterprise Analytics API 里的四个报表：usage_report、cost_report、user_usage_report、user_cost_report。企业分析接口的其余部分（活跃用户、各产品的使用情况等），发布说明没有提到。

发布说明写的是这些接口“仍然支持”，没有给停用的日期。官方另有一节从旧接口迁过来的说明。已经接好的看板和对账脚本可以先不动，新做的直接接新接口。

另外，Fast mode、Rate Limits API、功能总览等十几页文档里原来指向旧接口的链接，这次都改指新接口了。

本站没有实测

本站没有官方组织的管理凭据，上面全部按 10 月 30 日的官方文档整理，例子没有运行过。旧接口怎么用、管理凭据怎么建，见团队用 Claude API 之前要管好的事的第五节。