用量和成本 API · LHQ 的网络日志

提示

Admin API 不适用于个人账户。 如需与团队成员协作并添加成员，请在 Claude Console 的 Organization 页面（platform.claude.com/settings/organization）中设置您的组织。

注意

用量和成本 API（/v1/organizations/usage_report/messages 和 /v1/organizations/cost_report）是一个旧版 API，目前仍受支持。对于新的集成，请使用用量和成本分析 API，它以更多的分组和筛选维度报告用量和成本。要迁移现有集成，请参阅从用量和成本 API 迁移。

用量和成本 Admin API 为您的组织提供对历史 API 用量和成本数据的编程式、细粒度访问。这些数据与 Claude Console 中用量页面（platform.claude.com/usage）和成本页面（platform.claude.com/cost）上提供的信息类似。

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

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

须知

需要 Admin API 凭证。 这些端点属于 Admin API 的一部分。您可以使用 Admin API 密钥、具有 org:admin 作用域的 OAuth 令牌，或未限定于某个工作区的个人或服务账户密钥来访问它们；工作区 API 密钥无法使用。详情请参阅身份验证。

Claude Enterprise 组织使用 Analytics API 密钥配合不同的 API；请参阅您需要哪个 API？。

注意

Claude Platform on AWS： 用量和成本 API 端点不可用。请使用用量和成本分析 API。

注意

Claude Models on Google Cloud (Anthropic managed)： 在 Usage and Cost API 的各个端点中，仅 usage 端点可用。请通过组织级基础 URL 使用 Google Cloud 凭据（而非 Admin API 密钥）调用该端点。唯一允许此调用的预定义 IAM 角色是 roles/claude.admin。如需费用数据，请使用用量和成本分析 API或 Claude Console 的 Cost 页面。

您需要哪个 API？

要使用的 API 取决于您的组织使用哪个 Claude 产品：

您的组织	API	密钥类型
Claude Console（Claude Platform）	用量和成本分析 API（推荐），或本页介绍的旧版用量和成本 Admin API	Admin API 密钥（`sk-ant-admin01-...`）或其他 Admin API 凭证
Claude Enterprise（claude.ai）	用量和成本分析 API（推荐），或 Claude Enterprise Analytics API 的旧版成本和用量端点	Analytics API 密钥

Claude Enterprise 父组织不会出现在 Claude Console 中，也不携带 Admin API 密钥，因此对它们而言，Analytics API 密钥是访问此数据的唯一途径。请参阅 Analytics APIs 了解如何创建每种密钥类型以及 Claude Enterprise 成本数据适用于哪些计划。

合作伙伴解决方案

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

CloudZero：用于跟踪和预测成本的云智能平台
Datadog：具有自动追踪和监控功能的 LLM 可观测性
Grafana Cloud：无代理集成，通过开箱即用的仪表板和告警轻松实现 LLM 可观测性
Harness：用于云和 AI 成本管理的 FinOps 平台
Honeycomb：通过 OpenTelemetry 实现高级查询和可视化
Tempo：将用量和成本归因到 Jira 工作项
Vantage：用于 LLM 成本和用量可观测性的 FinOps 平台

快速开始

获取您组织过去 7 天的每日用量：

cURL

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" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

提示

为集成设置 User-Agent 标头

如果您正在构建集成，请设置您的 User-Agent 标头，以帮助 Anthropic 了解用量模式：
User-Agent: YourApp/1.0.0 (https://yourapp.com)

Usage API

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

关键概念

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

有关完整的参数详情和响应架构，请参阅 Usage API 参考。

基本示例

按模型的每日用量

cURL

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" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

带过滤的每小时用量

cURL

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-5-5&\
service_tiers[]=batch&\
context_window[]=0-200k&\
bucket_width=1h" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

按 API 密钥和工作区过滤用量

cURL

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" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

提示

要获取您组织的 API 密钥 ID，请使用 List API Keys 端点。

要获取您组织的工作区 ID，请使用 List Workspaces 端点，或在 Claude Console 中查找您组织的工作区 ID。

数据驻留

通过使用 inference_geo 维度对用量进行分组和过滤，跟踪您的数据驻留控制。这对于验证您组织的地理路由非常有用。

cURL

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" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

您还可以过滤到特定地理位置。有效值为 global、us 和 not_available：

cURL

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" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

注意

2026 年 2 月之前发布的模型（早于 Claude Opus 4.6 和 Claude Sonnet 4.6）不支持 inference_geo 请求参数，因此它们的用量报告在此维度上返回 "not_available"。您可以在 inference_geos[] 中使用 not_available 作为过滤值来定位这些模型。

快速模式

通过使用 speed 维度进行分组和过滤，跟踪快速模式用量。这对于监控标准模式与快速模式的用量非常有用。

cURL

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" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

您还可以过滤到特定速度。有效值为 standard 和 fast：

cURL

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" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

时间粒度限制

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

Cost API

使用 /v1/organizations/cost_report 端点检索以美元为单位的服务级成本细分。

关键概念

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

有关完整的参数详情和响应架构，请参阅 Cost API 参考。

警告

Priority Tier 成本使用不同的计费模型，不包含在成本端点中。请改为通过用量端点跟踪 Priority Tier 用量。

基本示例

cURL

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" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

分页

两个端点都支持对大型数据集进行分页：

发出初始请求。
如果 has_more 为 true，请在下一个请求中使用 next_page 值。
继续直到 has_more 为 false。

cURL

# 第一个请求
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" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_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..." \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

常见用例

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

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

常见问题

数据的新鲜度如何？

用量和成本数据通常在 API 请求完成后 5 分钟内出现，但延迟有时可能更长。

推荐的轮询频率是多少？

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

如何跟踪代码执行用量？

代码执行成本出现在成本端点中，在描述字段下归类为 Code Execution Usage。代码执行不包含在用量端点中。

如何跟踪 Priority Tier 用量？

在用量端点中按 service_tier 过滤或分组，并查找 priority 值。Priority Tier 成本在成本端点中不可用。

playground 用量会发生什么？

来自 Claude Console 中 playground（以及之前的旧版 Workbench）的 API 用量不与 API 密钥关联，因此即使按该维度分组，api_key_id 也将为 null。

为什么用量报告中显示了一个我没有创建的服务账户？

部分 Claude Managed Agents 会话的用量记录在一个由 Anthropic 管理的服务账户（svac_...）下。它不会与您创建的服务账户一起列出。请参阅查找整个组织的会话用量。

默认工作区如何表示？

归因于默认工作区的用量和成本的 workspace_id 值为 null。

如何获取 Claude Code 的每用户成本细分？

使用 products[]=claude_code&group_by[]=actor 调用用量和成本分析 API 的成本端点。如需按 API 密钥统计成本，请改为按 api_key_id 分组。Claude Code Analytics API 也提供按用户的估算成本和生产力指标。

另请参阅

使用 Usage 和 Cost API 为您的用户提供更好的体验、管理成本并保护您的速率限制。了解有关其他一些功能的更多信息：

Admin API
Admin API 参考
分析 API - 您的组织需要哪种分析 API 和密钥类型
定价
提示缓存 - 通过缓存优化成本
批处理 - 批量请求享受 50% 折扣
速率限制 - 了解使用层级
Rate Limits API - 读取您已配置的速率限制并设置工作区速率限制
数据驻留 - 控制推理的地理位置