# 使用量和成本 API
使用使用量和成本 Admin API 以编程方式访问您组织的 API 使用量和成本数据。
---
**Admin API 不适用于个人账户。** 要与团队成员协作和添加成员，请在**控制台 → 设置 → 组织**中设置您的组织。
使用量和成本 Admin API 提供对您组织历史 API 使用量和成本数据的编程和细粒度访问。此数据类似于 [Claude 控制台](/usage)和[/cost](/cost) 页面中提供的信息。
此 API 使您能够更好地监控、分析和优化您的 Claude 实现：
* **精确的使用量跟踪：** 获取精确的 token 计数和使用模式，而不是仅依赖响应 token 计数
* **成本对账：** 将内部记录与 Anthropic 计费进行匹配，供财务和会计团队使用
* **产品性能和改进：** 监控产品性能，同时衡量系统更改是否有所改进，或设置警报
* **[速率限制](/docs/en/api/rate-limits)和[优先层级](/docs/en/api/service-tiers#get-started-with-priority-tier)优化：** 优化[提示缓存](/docs/en/build-with-claude/prompt-caching)或特定提示等功能，以充分利用分配的容量，或购买专用容量
* **高级分析：** 执行比控制台中可用的更深入的数据分析
**需要 Admin API 密钥**
此 API 是 [Admin API](/docs/en/manage-claude/admin-api) 的一部分。这些端点需要一个 Admin API 密钥（以 `sk-ant-admin...` 开头），它与标准 API 密钥不同。只有具有管理员角色的组织成员才能通过 [Claude 控制台](/settings/admin-keys)配置 Admin API 密钥。
**Claude Platform on AWS：** 编程使用量和成本 API 端点目前不可用。请改为在 Claude 控制台的**使用量**和**成本**页面上查看使用量和成本数据。
## 合作伙伴解决方案
领先的可观测性平台提供开箱即用的集成，用于监控您的 Claude API 使用量和成本，无需编写自定义代码。这些集成提供仪表板、警报和分析，帮助您有效管理 API 使用量。
用于跟踪和预测成本的云智能平台
具有自动跟踪和监控的 LLM 可观测性
无代理集成，通过开箱即用的仪表板和警报实现轻松的 LLM 可观测性
通过 OpenTelemetry 进行高级查询和可视化
用于 LLM 成本和使用量可观测性的 FinOps 平台
## 快速开始
获取您组织过去 7 天的每日使用量：
```bash 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" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ANTHROPIC_ADMIN_KEY"
```
**为集成设置 User-Agent 头**
如果您正在构建集成，请设置 User-Agent 头以帮助我们了解使用模式：
```text
User-Agent: YourApp/1.0.0 (https://yourapp.com)
```
## 使用量 API
使用 `/v1/organizations/usage_report/messages` 端点跟踪您组织的 token 消耗，按模型、工作区和服务层级进行详细分解。
### 核心概念
- **时间桶：** 以固定间隔（`1m`、`1h` 或 `1d`）聚合使用量数据
- **Token 跟踪：** 测量未缓存输入、缓存输入、缓存创建和输出 token
- **过滤和分组：** 按 API 密钥、工作区、模型、服务层级、上下文窗口、[数据驻留](/docs/en/manage-claude/data-residency)或速度（beta）过滤，并按这些维度分组结果
- **服务器工具使用量：** 跟踪网络搜索等服务器端工具的使用量
有关完整的参数详细信息和响应架构，请参阅[使用量 API 参考](/docs/en/api/admin-api/usage-cost/get-messages-usage-report)。
### 基本示例
#### 按模型的每日使用量
```bash 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" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ANTHROPIC_ADMIN_KEY"
```
#### 按工作区的每小时使用量
```bash cURL
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"
```
#### 特定工作区的使用量
```bash 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&\
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 |
### 服务器工具使用量
跟踪服务器端工具（如网络搜索）的使用量：
```bash 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[]=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 参考](/docs/en/api/admin-api/usage-cost/get-messages-cost-report)。
### 基本示例
#### 每日成本
```bash cURL
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"
```
#### 按模型的每日成本
```bash cURL
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 参考](/docs/en/api/admin-api/usage-cost/get-claude-code-usage-report)。
### 基本示例
#### 每日 Claude Code 使用量
```bash cURL
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` 参数进行分页：
```bash 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&\
bucket_width=1d&\
limit=100&\
page=eyJ..." \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ANTHROPIC_ADMIN_KEY"
```
## 最佳实践
- **设置适当的时间范围：** 使用较短的时间范围（小时或天）以获得更细粒度的数据
- **使用分组：** 按模型、工作区或其他维度分组以识别趋势
- **过滤噪音：** 过滤掉不相关的数据以关注重要指标
- **定期监控：** 设置定期报告以跟踪使用量和成本趋势
- **使用合作伙伴集成：** 考虑使用 Datadog、Grafana Cloud 等合作伙伴解决方案进行高级监控
## 常见问题
不可以，使用量和成本数据是历史数据。对于实时监控，请考虑使用合作伙伴集成。
使用量 API 提供与控制台相同的数据，但具有更细粒度的控制和过滤选项。
是的，您可以使用 API 以编程方式导出数据。对于大量数据，请考虑使用分页。
## 相关资源
- [Admin API](/docs/en/manage-claude/admin-api)
- [速率限制 API](/docs/en/manage-claude/rate-limits-api)
- [工作区](/docs/en/manage-claude/workspaces)