使用量和成本 API
The Admin API is unavailable for individual accounts. To collaborate with teammates and add members, set up your organization in Console → Settings → Organization.
使用量和成本管理 API 为您的组织提供历史 API 使用量和成本数据的编程化和细粒度访问。这些数据类似于 Claude Console 的使用量和成本页面中提供的信息。
此 API 使您能够更好地监控、分析和优化您的 Claude 实现：
- 准确的使用量跟踪： 获取精确的令牌计数和使用模式，而不是仅依赖响应令牌计数
- 成本对账： 将内部记录与 Anthropic 账单匹配，供财务和会计团队使用
- 产品性能和改进： 监控产品性能，同时测量系统更改是否改善了性能，或设置警报
- 速率限制和优先级层优化： 优化提示缓存或特定提示等功能，以充分利用分配的容量，或购买专用容量。
- 高级分析： 执行比 Console 中可用的更深入的数据分析
需要管理 API 密钥
此 API 是管理 API的一部分。这些端点需要管理 API 密钥（以 sk-ant-admin... 开头），与标准 API 密钥不同。只有具有管理员角色的组织成员才能通过 Claude Console 配置管理 API 密钥。
合作伙伴解决方案
领先的可观测性平台提供即用型集成，用于监控您的 Claude API 使用量和成本，无需编写自定义代码。这些集成提供仪表板、警报和分析功能，帮助您有效管理 API 使用量。
Datadog
具有自动跟踪和监控功能的 LLM 可观测性
Grafana Cloud
无代理集成，通过开箱即用的仪表板和警报轻松实现 LLM 可观测性
Honeycomb
通过 OpenTelemetry 进行高级查询和可视化
快速开始
获取您组织过去 7 天的每日使用量：
curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-08T00:00:00Z&\
ending_at=2025-01-15T00:00:00Z&\
bucket_width=1d" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ADMIN_API_KEY"为集成设置 User-Agent 标头
如果您正在构建集成，请设置您的 User-Agent 标头以帮助我们了解使用模式：
User-Agent: YourApp/1.0.0 (https://yourapp.com)使用量 API
通过 /v1/organizations/usage_report/messages 端点跟踪整个组织的令牌消耗，并按模型、工作区和服务层进行详细分解。
关键概念
- 时间桶： 以固定间隔（
1m、1h或1d）聚合使用量数据 - 令牌跟踪： 测量未缓存输入、缓存输入、缓存创建和输出令牌
- 过滤和分组： 按 API 密钥、工作区、模型、服务层或上下文窗口过滤，并按这些维度对结果进行分组
- 服务器工具使用： 跟踪服务器端工具（如网络搜索）的使用情况
有关完整的参数详细信息和响应架构，请参阅使用量 API 参考。
基本示例
按模型的每日使用量
curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-08T00:00:00Z&\
group_by[]=model&\
bucket_width=1d" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ADMIN_API_KEY"带过滤的每小时使用量
curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-15T00:00:00Z&\
ending_at=2025-01-15T23:59:59Z&\
models[]=claude-sonnet-4-5-20250929&\
service_tiers[]=batch&\
context_window[]=0-200k&\
bucket_width=1h" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ADMIN_API_KEY"按 API 密钥和工作区过滤使用量
curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-08T00:00:00Z&\
api_key_ids[]=apikey_01Rj2N8SVvo6BePZj99NhmiT&\
api_key_ids[]=apikey_01ABC123DEF456GHI789JKL&\
workspace_ids[]=wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ&\
workspace_ids[]=wrkspc_01XYZ789ABC123DEF456MNO&\
bucket_width=1d" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ADMIN_API_KEY"时间粒度限制
| 粒度 | 默认限制 | 最大限制 | 用例 |
|---|---|---|---|
1m | 60 个桶 | 1440 个桶 | 实时监控 |
1h | 24 个桶 | 168 个桶 | 每日模式 |
1d | 7 个桶 | 31 个桶 | 每周/每月报告 |
成本 API
使用 /v1/organizations/cost_report 端点检索以美元为单位的服务级成本分解。
关键概念
- 货币： 所有成本以美元计算，以最小单位（美分）的十进制字符串报告
- 成本类型： 跟踪令牌使用、网络搜索和代码执行成本
- 分组： 按工作区或描述对成本进行分组，以获得详细分解
- 时间桶： 仅每日粒度（
1d）
有关完整的参数详细信息和响应架构，请参阅成本 API 参考。
优先级层成本使用不同的计费模型，不包含在成本端点中。请通过使用量端点跟踪优先级层使用情况。
基本示例
curl "https://api.anthropic.com/v1/organizations/cost_report?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-31T00:00:00Z&\
group_by[]=workspace_id&\
group_by[]=description" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ADMIN_API_KEY"分页
两个端点都支持大型数据集的分页：
- 发出初始请求
- 如果
has_more为true，在下一个请求中使用next_page值 - 继续直到
has_more为false
# 第一个请求
curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-31T00:00:00Z&\
limit=7" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ADMIN_API_KEY"
# 响应包括："has_more": true, "next_page": "page_xyz..."
# 带分页的下一个请求
curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-31T00:00:00Z&\
limit=7&\
page=page_xyz..." \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ADMIN_API_KEY"常见用例
在 anthropic-cookbook 中探索详细实现：
- 每日使用量报告： 跟踪令牌消耗趋势
- 成本归属： 按工作区分配费用以进行退款
- 缓存效率： 测量和优化提示缓存
- 预算监控： 为支出阈值设置警报
- CSV 导出： 为财务团队生成报告
常见问题
数据有多新鲜？
使用量和成本数据通常在 API 请求完成后 5 分钟内出现，尽管偶尔可能会有更长的延迟。
推荐的轮询频率是多少？
API 支持每分钟轮询一次以持续使用。对于短时间突发（例如，下载分页数据），更频繁的轮询是可以接受的。为需要频繁更新的仪表板缓存结果。
如何跟踪代码执行使用情况？
代码执行成本出现在成本端点中，在描述字段中按 Code Execution Usage 分组。代码执行不包含在使用量端点中。
如何跟踪优先级层使用情况？
在使用量端点中按 service_tier 过滤或分组，并查找 priority 值。优先级层成本在成本端点中不可用。
Workbench 使用情况会发生什么？
来自 Workbench 的 API 使用量不与 API 密钥关联，因此即使按该维度分组，api_key_id 也将为 null。
默认工作区如何表示？
归属于默认工作区的使用量和成本的 workspace_id 值为 null。
如何获取 Claude Code 的每用户成本分解？
使用 Claude Code Analytics API，它提供每用户估计成本和生产力指标，而不会出现按许多 API 密钥分解成本的性能限制。对于具有许多密钥的一般 API 使用，请使用使用量 API跟踪令牌消耗作为成本代理。
另请参阅
使用量和成本 API 可用于帮助您为用户提供更好的体验、帮助您管理成本并保持您的速率限制。了解更多关于这些其他功能的信息：