English ← MyDocs

使用量和成本 API

使用使用量和成本 Admin API 以编程方式访问您组织的 API 使用量和成本数据。

Tip

Admin API 不适用于个人账户。 要与团队成员协作和添加成员，请在控制台 → 设置 → 组织中设置您的组织。

使用量和成本 Admin API 提供对您组织历史 API 使用量和成本数据的编程和细粒度访问。此数据类似于 Claude 控制台和/cost 页面中提供的信息。

此 API 使您能够更好地监控、分析和优化您的 Claude 实现：

  • 精确的使用量跟踪： 获取精确的 token 计数和使用模式，而不是仅依赖响应 token 计数
  • 成本对账： 将内部记录与 Anthropic 计费进行匹配，供财务和会计团队使用
  • 产品性能和改进： 监控产品性能，同时衡量系统更改是否有所改进，或设置警报
  • 速率限制和优先层级优化： 优化提示缓存或特定提示等功能，以充分利用分配的容量，或购买专用容量
  • 高级分析： 执行比控制台中可用的更深入的数据分析
Check

需要 Admin API 密钥

此 API 是 Admin API 的一部分。这些端点需要一个 Admin API 密钥（以 sk-ant-admin... 开头），它与标准 API 密钥不同。只有具有管理员角色的组织成员才能通过 Claude 控制台配置 Admin API 密钥。

Note

Claude Platform on AWS： 编程使用量和成本 API 端点目前不可用。请改为在 Claude 控制台的使用量和成本页面上查看使用量和成本数据。

合作伙伴解决方案

领先的可观测性平台提供开箱即用的集成，用于监控您的 Claude API 使用量和成本，无需编写自定义代码。这些集成提供仪表板、警报和分析，帮助您有效管理 API 使用量。

◆CloudZero

用于跟踪和预测成本的云智能平台

◆Datadog

具有自动跟踪和监控的 LLM 可观测性

◆Grafana Cloud

无代理集成，通过开箱即用的仪表板和警报实现轻松的 LLM 可观测性

◆Honeycomb

通过 OpenTelemetry 进行高级查询和可视化

◆Vantage

用于 LLM 成本和使用量可观测性的 FinOps 平台

快速开始

获取您组织过去 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: $ANTHROPIC_ADMIN_KEY"
Tip

为集成设置 User-Agent 头

如果您正在构建集成，请设置 User-Agent 头以帮助我们了解使用模式：

User-Agent: YourApp/1.0.0 (https://yourapp.com)

使用量 API

使用 /v1/organizations/usage_report/messages 端点跟踪您组织的 token 消耗，按模型、工作区和服务层级进行详细分解。

核心概念

  • 时间桶： 以固定间隔（1m、1h 或 1d）聚合使用量数据
  • Token 跟踪： 测量未缓存输入、缓存输入、缓存创建和输出 token
  • 过滤和分组： 按 API 密钥、工作区、模型、服务层级、上下文窗口、数据驻留或速度（beta）过滤，并按这些维度分组结果
  • 服务器工具使用量： 跟踪网络搜索等服务器端工具的使用量

有关完整的参数详细信息和响应架构，请参阅使用量 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: $ANTHROPIC_ADMIN_KEY"

按工作区的每小时使用量

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-08T00:00:00Z&\
ending_at=2025-01-09T00:00:00Z&\
group_by[]=workspace_id&\
bucket_width=1h" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

特定工作区的使用量

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-08T00:00:00Z&\
workspace_ids[]=wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

响应字段

使用量 API 返回以下 token 计数：

字段描述
uncached_input_tokens未从缓存提供的输入 token
cached_input_tokens从缓存提供的输入 token
cache_creation_input_tokens用于创建缓存的输入 token
output_tokens生成的输出 token

服务器工具使用量

跟踪服务器端工具（如网络搜索）的使用量：

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[]=server_tool_use.type&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

成本 API

使用 /v1/organizations/cost_report/messages 端点跟踪您组织的 API 成本。

核心概念

  • 成本跟踪： 以您组织的计费货币测量成本
  • 过滤和分组： 按 API 密钥、工作区、模型、服务层级或速度（beta）过滤和分组
  • 时间桶： 以固定间隔聚合成本数据

有关完整的参数详细信息和响应架构，请参阅成本 API 参考。

基本示例

每日成本

curl "https://api.anthropic.com/v1/organizations/cost_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-08T00:00:00Z&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

按模型的每日成本

curl "https://api.anthropic.com/v1/organizations/cost_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: $ANTHROPIC_ADMIN_KEY"

响应字段

成本 API 返回以下字段：

字段描述
amount成本金额
currency货币代码（例如，"usd"）

Claude Code 使用量

使用 /v1/organizations/usage_report/claude_code 端点跟踪 Claude Code 使用量。

核心概念

  • 会话跟踪： 跟踪 Claude Code 会话
  • 用户分解： 按用户查看使用量
  • 时间桶： 以固定间隔聚合使用量数据

有关完整的参数详细信息和响应架构，请参阅 Claude Code 使用量 API 参考。

基本示例

每日 Claude Code 使用量

curl "https://api.anthropic.com/v1/organizations/usage_report/claude_code?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-08T00:00:00Z&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

分页

使用量和成本 API 支持分页。使用 limit 和 page 参数进行分页：

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-08T00:00:00Z&\
bucket_width=1d&\
limit=100&\
page=eyJ..." \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

最佳实践

  • 设置适当的时间范围： 使用较短的时间范围（小时或天）以获得更细粒度的数据
  • 使用分组： 按模型、工作区或其他维度分组以识别趋势
  • 过滤噪音： 过滤掉不相关的数据以关注重要指标
  • 定期监控： 设置定期报告以跟踪使用量和成本趋势
  • 使用合作伙伴集成： 考虑使用 Datadog、Grafana Cloud 等合作伙伴解决方案进行高级监控

常见问题

使用量和成本数据的延迟是多少？

使用量和成本数据通常在 5-15 分钟内可用。

我可以获取实时使用量数据吗？

不可以，使用量和成本数据是历史数据。对于实时监控，请考虑使用合作伙伴集成。

使用量数据与控制台中显示的有何不同？

使用量 API 提供与控制台相同的数据，但具有更细粒度的控制和过滤选项。

我可以导出使用量数据吗？

是的，您可以使用 API 以编程方式导出数据。对于大量数据，请考虑使用分页。

相关资源