用量和成本分析 API

用量和成本分析 API 报告您组织的历史令牌用量和成本，并按您选择的维度进行细分，例如模型、工作区、API 密钥，或每个请求背后的用户或服务账户。对于 Claude Console 组织，这些数据与 Claude Console 的用量和成本页面所显示的内容类似。

该 API 有两个端点：

• GET /v1/organizations/analytics/usage 报告令牌数和请求数。
• GET /v1/organizations/analytics/cost 报告以美元计的成本。

用量和成本分析 API 目前处于 beta 阶段。请在每个请求中发送 anthropic-beta: analytics-usage-cost-2026-08-24 标头和 anthropic-version 标头。SDK 和 ant CLI 会为您发送这两个标头，并在您读取结果时获取剩余页面，因此 limit 仅设置页面大小。

使用此 API 可以：

• 归因支出： 按工作区、API 密钥、模型、服务层级或发出每个请求的身份细分成本和令牌用量。
• 找出最大消耗者： 按令牌数、请求数或成本对结果排序，以回答诸如"本月哪些 API 密钥支出最多？"之类的问题。
• 构建时间序列： 将结果拆分为每日、每小时或每分钟的时间桶，用于仪表板和财务报告。
• 一次集成： 相同的端点、参数和响应字段同时适用于 Claude Console 和 Claude Enterprise 组织。

快速入门

获取 9 月第一周的每日令牌用量，每个模型每天一行：

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.usage.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-09-08T00:00:00Z",
    time_bucket_width="1d",
    group_by=["model"],
    limit=10,
)

for row in rows:
    print(f"{row.starting_at} {row.group.model}: {row.usage.total_tokens}")

响应中每个有用量的模型每天一行，total_tokens 最大的排在最前。此示例显示单行：

{
  "data": [
    {
      "starting_at": "2026-09-03T00:00:00Z",
      "ending_at": "2026-09-04T00:00:00Z",
      "group": {
        "product": null,
        "model": "claude-sonnet-5",
        "context_window": null,
        "inference_geo": null,
        "speed": null,
        "slack_channel_id": null,
        "claude_tag_category": null,
        "claude_tag_user_id": null,
        "rbac_group_id": null,
        "workspace_id": null,
        "service_tier": null,
        "user_profile_id": null,
        "agent_id": null,
        "environment_id": null,
        "deployment_id": null,
        "session_id": null,
        "actor": null,
        "actor_type": null,
        "api_key_id": null
      },
      "usage": {
        "uncached_input_tokens": 1284500,
        "cache_creation": {
          "ephemeral_1h_input_tokens": 0,
          "ephemeral_5m_input_tokens": 215300
        },
        "cache_read_input_tokens": 3200000,
        "output_tokens": 891000,
        "total_tokens": 5590800,
        "server_tool_use": {
          "web_search_requests": 12
        },
        "requests": 4210
      }
    }
  ],
  "has_more": true,
  "next_page": "page_V2mQ4dkt9HcbX3pLr...",
  "data_refreshed_at": "2026-09-18T16:02:11Z"
}

结果的结构

• 每一行都有三个部分： starting_at 和 ending_at 给出该行涵盖的时间段，group 包含所有维度，usage（在成本端点上为 cost）包含指标。
• 未分组的维度为 null： group 中的维度为 null，除非您在 group_by[] 中列出它。对于没有该维度值的行，已分组的维度也为 null，例如代码执行用量中的 model。group_by[] 最多接受五个维度。
• 每种组合一行： 每一行是已分组维度的一种组合，每个有用量或成本的组合在一次查询的所有页面中恰好出现一次。如果没有 group_by[] 且没有 time_bucket_width，响应将是汇总整个范围的单行。
• 时间桶是可选的： 将 time_bucket_width 设置为 1m、1h 或 1d，即可按 UTC 时间桶拆分每种组合；此时每行的 starting_at 和 ending_at 即为其时间桶的边界。没有用量或成本的时间桶不会产生任何行。
• 默认按排名排序：行按 order_by 指标在整个时间范围内排序，默认从大到小（order=asc 可反转顺序）。要构建时间序列，请设置 time_bucket_width 和 order_by=time。此时行将按时间桶依次返回，默认最新的时间桶在前（order=asc 会将最早的放在前面），每个时间桶内数值最大的行在前。请用零填充空的时间桶。
• 筛选器可与分组配合使用： 大多数可用于分组的维度都有对应的方括号表示法列表筛选器，例如 models[]=claude-opus-5-5。重复该参数即可传递多个值，最多 100 个。同一筛选器的多个值以 OR 组合，不同筛选器以 AND 组合。筛选器和 group_by[] 相互独立；您可以按任何维度进行筛选，无论是否按其分组，反之亦然。

model 和 actor 等维度适用于所有组织。有些维度（例如 api_key_id）仅适用于 Claude Console 组织，另一些（例如 slack_channel_id）仅适用于 Claude Enterprise 组织。不适用于您组织的维度在每一行中都为 null，其筛选器不匹配任何内容；例外是 rbac_group_id，当您的组织无法使用团队功能时，它会返回错误。用量 和 成本 的 API 参考列出了所有维度、筛选器和值。

操作者

actor 维度表示请求归属于谁：用户、服务账户、联合云身份（对于通过其云平台访问 Claude 的组织，即 AWS 或 Google Cloud 主体），或者当请求背后没有上述任何身份时，即 API 密钥本身。当您按 actor 分组时，每行的 actor 是一个对象，其 type 表明它属于哪种类型。无法归属于任何身份的用量具有 actor: null。

个人密钥和服务账户密钥以其关联的用户或服务账户身份运行，因此它们的请求会将该身份显示为 actor，并将密钥显示在 api_key_id 中。旧版工作区密钥未关联任何身份，因此该密钥同时显示为 actor 和 api_key_id。例外情况是成员使用其 Claude Console 账户登录时 Claude Code 创建的密钥：它位于 Claude Code 工作区中，其用量归属于该成员。不使用 API 密钥发出的请求（例如来自 Claude Console 或使用 Workload Identity Federation 令牌的请求）具有 api_key_id: null；联合工作负载的 actor 是其服务账户。要在 api_key_ids[] 筛选器中包含没有 API 密钥的用量，请添加一个空条目：api_key_ids[]=。

api_key_ids[] 和 actor_ids[] 筛选器回答的是不同的问题。api_key_ids[]=apikey_... 匹配该密钥认证的所有请求，无论其归属于谁。actor_ids[]=apikey_... 仅匹配归属于该密钥本身的请求。

用量端点

GET /v1/organizations/analytics/usage 按类型返回令牌计数。order_by 接受 total_tokens（默认值）、output_tokens、uncached_input_tokens、requests 或 time。

例如，要查看某个工作区和某个 API 密钥一周的用量，并按服务层级细分（每个层级一行，涵盖整周）：

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.usage.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-09-08T00:00:00Z",
    workspace_ids=["wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"],
    api_key_ids=["apikey_01Rj2N8SVvo6BePZj99NhmiT"],
    group_by=["service_tier"],
)

for row in rows:
    print(f"{row.group.service_tier}: {row.usage.total_tokens}")

要查找 API 密钥和工作区 ID，请使用 List API Keys 和 List Workspaces 端点或 Claude Console。

要找出一个月内发出请求最多的用户、服务账户和 API 密钥：

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.usage.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-10-01T00:00:00Z",
    group_by=["actor"],
    order_by="requests",
    limit=25,
)

for row in rows:
    print(f"{row.group.actor}: {row.usage.requests}")

成本端点

GET /v1/organizations/analytics/cost 接受与 /usage 端点相同的筛选器、维度和时间桶。每行的 cost 对象包含 amount（折扣后、应用任何抵扣额度之前的成本）、list_amount（按标价计算的成本）、currency（始终为 "USD"）以及 requests。金额是以美分为单位、保留六位小数的十进制字符串："41280.000000" 即 412.80 美元。order_by 接受 amount（默认值）、list_amount 或 time。

有两个额外维度仅存在于此端点上，且不计入五个维度的限制：group_by[]=cost_type 将每一行拆分为每种成本类型各一行，group_by[]=token_type 将令牌成本拆分为每种令牌类型各一行。limit 同样不适用于这两个维度，因此一个页面可以包含超过 limit 的行数。例如，按模型、成本类型和令牌类型查看一个月的成本：

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.cost.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-10-01T00:00:00Z",
    group_by=["model", "cost_type", "token_type"],
)

for row in rows:
    print(
        f"{row.group.model} {row.group.cost_type} {row.group.token_type}: {row.cost.amount}"
    )

对于每个模型，响应包含五个 tokens 行（每种令牌类型一行），外加 web_search、code_execution 和 session_usage 各一行。其中一行如下：

{
  "starting_at": "2026-09-01T00:00:00Z",
  "ending_at": "2026-10-01T00:00:00Z",
  "group": {
    "model": "claude-opus-5",
    ...,
    "cost_type": "tokens",
    "token_type": "cache_read_input_tokens"
  },
  "cost": {
    "currency": "USD",
    "amount": "41280.000000",
    "list_amount": "51600.000000",
    "requests": null
  }
}

group 对象包含所有维度，此处已省略部分内容。指定 group_by[]=cost_type 或 token_type 时，每行的 requests 均为 null。

日期范围和时间桶

• 时间戳采用带 UTC 偏移量的 RFC 3339 格式，例如 2026-09-01T00:00:00Z。starting_at 包含在内，ending_at 不包含在内。
• starting_at 必须在 2026 年 1 月 1 日或之后，且在过去 365 天内。单个请求最多可跨越 31 天；ending_at 默认为 starting_at 之后 31 天或当前时间，以较早者为准。
• 只要设置了 time_bucket_width，就必须提供 ending_at；使用 time_bucket_width=1m 时，单个请求最多可跨越 24 小时。
• 范围的两端都会向下取整到 UTC 时间桶边界，未设置 time_bucket_width 时则取整到整点。例如，使用 time_bucket_width=1h 时，2026-09-01T10:43:00Z 的 starting_at 会被视为 2026-09-01T10:00:00Z，2026-09-01T15:43:00Z 的 ending_at 会被视为 2026-09-01T15:00:00Z，因此响应覆盖 UTC 时间 10:00 至 15:00。

数据新鲜度

每个响应都包含一个 data_refreshed_at 时间戳，该时间之后的用量数据缺失或不完整。当请求范围的任何部分都尚无可用数据时，data_refreshed_at 为 null，data 为空。数据通常在底层用量发生后 4 小时内刷新，最长可能需要 24 小时。随着延迟事件的到达和对账的运行，数值可能会被修订，直到日历月结束后约 7 天为止。例如，10 月 1 日的数值可能会变化到 11 月 7 日左右。为了在重复调用中获得稳定的结果，请将 ending_at 设置为不晚于您已看到的某个 data_refreshed_at；如需最终总计，请仅查询至少 7 天前已结束的月份。分页查询的每一页都读取相同的数据快照，因此 data_refreshed_at 在各页之间完全相同。

从用量和成本 API 迁移

本节适用于调用旧版用量和成本 API（/v1/organizations/usage_report/messages 和 /v1/organizations/cost_report）的 Claude Console 组织。您的 Admin API 密钥、anthropic-version 标头、starting_at 和 ending_at、时间桶宽度值（1m、1h、1d）、方括号表示法、分页字段名称以及令牌和成本字段名称均保持不变。变化如下：

要重现旧版每日报告，请使用相同的 group_by[] 请求 time_bucket_width=1d，使用 limit=1000 逐页获取，然后按 starting_at 对行进行分组，并用零填充缺失的日期。添加 order_by=time&order=asc 可按顺序获取各天数据。以下是按模型统计 1 周每日用量的旧写法：

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

迁移后：

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.usage.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-09-08T00:00:00Z",
    time_bucket_width="1d",
    group_by=["model"],
    limit=1000,
)

for row in rows:
    print(f"{row.starting_at} {row.group.model}: {row.usage.total_tokens}")

按工作区、模型、服务层级、上下文窗口和推理地理位置划分的每日成本，并按成本类型和令牌类型拆分：

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.cost.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-09-08T00:00:00Z",
    time_bucket_width="1d",
    group_by=[
        "workspace_id",
        "model",
        "service_tier",
        "context_window",
        "inference_geo",
        "cost_type",
        "token_type",
    ],
    limit=1000,
)

for row in rows:
    group = row.group
    print(
        f"{row.starting_at} {group.workspace_id} {group.model} {group.service_tier} "
        f"{group.context_window} {group.inference_geo} {group.cost_type} {group.token_type}: "
        f"{row.cost.amount}"
    )

从 Claude Enterprise 用量和成本报告迁移

本节适用于调用 Claude Enterprise Analytics API 中 /v1/organizations/analytics/ 下的报告端点 usage_report、cost_report、user_usage_report 和 user_cost_report 的 Claude Enterprise 组织。这些端点为旧版，仍受支持。当您需要以下任一功能时，请迁移到 /analytics/usage 和 /analytics/cost：

• 每个时间桶中的每个分组，而不是每个时间桶中的前 100 个分组
• 在用量和成本上，均可将 actor 或 actor_type 与其他维度一起分组
• 按您选择的指标在整个时间范围内对行进行排名，或按时间桶排序
• 一次集成即可同时服务 Claude Console 组织

您的密钥、最早日期、365 天回溯期和 31 天跨度、筛选器和维度的名称及值（user_ids[] 和 Claude Tag 产品值除外）、用户 actor 字段、指标和金额字段、data_refreshed_at、游标规则以及组织级速率限制均保持不变。唯一新增的标头是 analytics-usage-cost-2026-08-24 beta 标头。变化如下：

一个月的每用户成本，迁移前：

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.user_cost_report.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-10-01T00:00:00Z",
    limit=100,
)

for row in rows:
    print(f"{row.actor.user_id}: {row.amount}")

迁移后，并增加按产品的细分：

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.cost.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-10-01T00:00:00Z",
    actor_types=["user_actor"],
    group_by=["actor", "product"],
    limit=100,
)

for row in rows:
    actor = row.group.actor
    if actor is not None and actor.type == "user_actor":
        print(f"{actor.user_id} {row.group.product}: {row.cost.amount}")

常见问题

默认工作区如何表示？

与其他所有工作区一样，Claude Console 组织的默认工作区也有自己的 wrkspc_ ID。默认工作区的行在 workspace_id 中包含该 ID，您可以使用 workspace_ids[] 按其进行筛选。除非您传递 include_default=true，否则 List Workspaces 不会包含默认工作区。要检查某个不熟悉的 workspace_id 是否为默认工作区，请将其传递给 Get Workspace：默认工作区会返回 "name": "Default"。

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

使用 products[]=claude_code&group_by[]=actor 调用成本端点。Claude Console 组织还可以使用 Claude Code Analytics API，它报告每用户的 Claude Code 活动和估算成本。

另请参阅

• 用量和成本 API（旧版）
• Analytics API：您的组织需要哪种分析 API 和密钥类型
• Claude Code Analytics API
• Admin API 参考
• 定价