使用量与费用 API

管理监控

使用情况和成本 API

通过使用情况和成本管理 API 以编程方式访问您的组织的 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 使用情况。

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: $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-opus-4-7&\
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"

要检索您的组织的 API 密钥 ID，请使用列出 API 密钥端点。

要检索您的组织的工作区 ID，请使用列出工作区端点，或在 Anthropic Console 中查找您的组织的工作区 ID。

数据驻留

通过使用 inference_geo 维度分组和筛选使用情况来跟踪您的数据驻留控制。这对于验证整个组织的地理路由很有用。

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-02-01T00:00:00Z&\
ending_at=2026-02-08T00:00:00Z&\
group_by[]=inference_geo&\
group_by[]=model&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ADMIN_API_KEY"

您也可以筛选到特定的地理位置。有效值为 global、us 和 not_available：

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-02-01T00:00:00Z&\
ending_at=2026-02-08T00:00:00Z&\
inference_geos[]=us&\
group_by[]=model&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ADMIN_API_KEY"

在 2026 年 2 月之前发布的模型（Claude Opus 4.6 之前）不支持 inference_geo 请求参数，因此其使用情况报告为此维度返回 "not_available"。您可以在 inference_geos[] 中使用 not_available 作为筛选值来针对这些模型。

快速模式（测试版：研究预览）

通过使用 speed 维度分组和筛选来跟踪快速模式使用情况。这对于监控标准模式与快速模式的使用情况很有用。

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-02-01T00:00:00Z&\
ending_at=2026-02-08T00:00:00Z&\
group_by[]=speed&\
group_by[]=model&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "anthropic-beta: fast-mode-2026-02-01" \
  --header "x-api-key: $ADMIN_API_KEY"

您也可以筛选到特定的速度。有效值为 standard 和 fast：

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-02-01T00:00:00Z&\
ending_at=2026-02-08T00:00:00Z&\
speeds[]=fast&\
group_by[]=model&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "anthropic-beta: fast-mode-2026-02-01" \
  --header "x-api-key: $ADMIN_API_KEY"

speeds[] 筛选和 speed group_by 值都需要 fast-mode-2026-02-01 测试版标头。

时间粒度限制

粒度	默认限制	最大限制	用例
`1m`	60 个桶	1440 个桶	实时监控
`1h`	24 个桶	168 个桶	每日模式
`1d`	7 个桶	31 个桶	周/月报告

成本 API

使用 /v1/organizations/cost_report 端点以美元检索服务级别成本分解。

关键概念

货币： 所有成本以美元计，报告为最低单位（美分）的十进制字符串
成本类型： 跟踪令牌使用、网络搜索和代码执行成本
分组： 按工作区或描述对成本进行分组，以获得详细的分解。按 description 分组时，响应包括解析的字段，如 model 和 inference_geo
时间桶： 仅限每日粒度（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"

常见用例

在 Claude 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 分析 API，它提供按用户的估计成本和生产力指标，而不受按许多 API 密钥分解成本的性能限制。对于具有许多密钥的一般 API 使用，使用使用情况 API 来跟踪令牌消耗作为成本代理。

另请参阅

使用情况和成本 API 可用于帮助您为用户提供更好的体验，帮助您管理成本，并保留您的速率限制。了解有关这些其他功能的更多信息：

管理 API 概述
管理 API 参考
定价
提示缓存 - 通过缓存优化成本
批处理 - 批处理请求享受 50% 折扣
速率限制 - 了解使用层
数据驻留 - 控制推理地理位置

Was this page helpful?

管理监控

使用情况和成本 API

通过使用情况和成本管理 API 以编程方式访问您的组织的 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 使您能够更好地监控、分析和优化您的 Claude 实现：

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

需要管理 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: $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-opus-4-7&\
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"

要检索您的组织的 API 密钥 ID，请使用列出 API 密钥端点。

要检索您的组织的工作区 ID，请使用列出工作区端点，或在 Anthropic Console 中查找您的组织的工作区 ID。

数据驻留

通过使用 inference_geo 维度分组和筛选使用情况来跟踪您的数据驻留控制。这对于验证整个组织的地理路由很有用。

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-02-01T00:00:00Z&\
ending_at=2026-02-08T00:00:00Z&\
group_by[]=inference_geo&\
group_by[]=model&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ADMIN_API_KEY"

您也可以筛选到特定的地理位置。有效值为 global、us 和 not_available：

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-02-01T00:00:00Z&\
ending_at=2026-02-08T00:00:00Z&\
inference_geos[]=us&\
group_by[]=model&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ADMIN_API_KEY"

快速模式（测试版：研究预览）

通过使用 speed 维度分组和筛选来跟踪快速模式使用情况。这对于监控标准模式与快速模式的使用情况很有用。

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-02-01T00:00:00Z&\
ending_at=2026-02-08T00:00:00Z&\
group_by[]=speed&\
group_by[]=model&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "anthropic-beta: fast-mode-2026-02-01" \
  --header "x-api-key: $ADMIN_API_KEY"

您也可以筛选到特定的速度。有效值为 standard 和 fast：

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-02-01T00:00:00Z&\
ending_at=2026-02-08T00:00:00Z&\
speeds[]=fast&\
group_by[]=model&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "anthropic-beta: fast-mode-2026-02-01" \
  --header "x-api-key: $ADMIN_API_KEY"

speeds[] 筛选和 speed group_by 值都需要 fast-mode-2026-02-01 测试版标头。

时间粒度限制

粒度	默认限制	最大限制	用例
`1m`	60 个桶	1440 个桶	实时监控
`1h`	24 个桶	168 个桶	每日模式
`1d`	7 个桶	31 个桶	周/月报告

成本 API

使用 /v1/organizations/cost_report 端点以美元检索服务级别成本分解。

关键概念

货币： 所有成本以美元计，报告为最低单位（美分）的十进制字符串
成本类型： 跟踪令牌使用、网络搜索和代码执行成本
分组： 按工作区或描述对成本进行分组，以获得详细的分解。按 description 分组时，响应包括解析的字段，如 model 和 inference_geo
时间桶： 仅限每日粒度（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"

常见用例

在 Claude Cookbook 中探索详细的实现：

每日使用情况报告： 跟踪令牌消耗趋势
成本归因： 按工作区分配费用以进行费用分摊
缓存效率： 测量和优化提示缓存
预算监控： 为支出阈值设置警报
CSV 导出： 为财务团队生成报告

常见问题

数据有多新鲜？

使用情况和成本数据通常在 API 请求完成后的 5 分钟内出现，尽管延迟有时可能更长。

推荐的轮询频率是多少？

该 API 支持持续使用时每分钟轮询一次。对于短突发（例如，下载分页数据），更频繁的轮询是可以接受的。为需要频繁更新的仪表板缓存结果。

如何跟踪代码执行使用情况？

代码执行成本出现在成本端点中，在描述字段中分组为 Code Execution Usage。代码执行不包括在使用端点中。

如何跟踪优先级层使用情况？

在使用端点中按 service_tier 筛选或分组，并查找 priority 值。优先级层成本在成本端点中不可用。

Workbench 使用情况会发生什么？

来自 Workbench 的 API 使用情况不与 API 密钥关联，因此即使按该维度分组，api_key_id 也将为 null。

默认工作区如何表示？

归因于默认工作区的使用情况和成本对 workspace_id 具有 null 值。

如何获取 Claude Code 的按用户成本分解？

另请参阅

使用情况和成本 API 可用于帮助您为用户提供更好的体验，帮助您管理成本，并保留您的速率限制。了解有关这些其他功能的更多信息：

管理 API 概述
管理 API 参考
定价
提示缓存 - 通过缓存优化成本
批处理 - 批处理请求享受 50% 折扣
速率限制 - 了解使用层
数据驻留 - 控制推理地理位置

Was this page helpful?