## 获取 Messages 用量报告

**get** `/v1/organizations/usage_report/messages`

获取 Messages 用量报告

### 查询参数

- `starting_at: string`

  将返回在此 RFC 3339 时间戳之后（含）开始的时间桶。
  每个时间桶将对齐到 UTC 的分钟/小时/日起始时刻。

- `account_ids: optional array of string`

  将返回的用量限制为指定的用户账户 ID。

- `api_key_ids: optional array of string`

  将返回的用量限制为指定的 API 密钥 ID。

- `bucket_width: optional "1d" or "1m" or "1h"`

  响应数据的时间粒度。

  - `"1d"`

  - `"1m"`

  - `"1h"`

- `context_window: optional array of "0-200k" or "200k-1M"`

  将返回的用量限制为指定的上下文窗口。

  - `"0-200k"`

  - `"200k-1M"`

- `ending_at: optional string`

  将返回在此 RFC 3339 时间戳之前结束的时间桶。

- `group_by: optional array of "api_key_id" or "workspace_id" or "model" or 6 more`

  按可用选项的任意子集进行分组。按 `speed` 分组需要 `fast-mode-2026-02-01` beta 请求头。

  - `"api_key_id"`

  - `"workspace_id"`

  - `"model"`

  - `"service_tier"`

  - `"context_window"`

  - `"inference_geo"`

  - `"speed"`

  - `"account_id"`

  - `"service_account_id"`

- `inference_geos: optional array of "global" or "us" or "not_available"`

  将返回的用量限制为指定的推理地理位置。对于不支持指定 `inference_geo` 的模型，使用 `not_available`。

  - `"global"`

  - `"us"`

  - `"not_available"`

- `limit: optional number`

  响应中返回的最大时间桶数量。

  默认值和最大值取决于 `bucket_width`：
  - `"1d"`：默认 7 天，最大 31 天
  - `"1h"`：默认 24 小时，最大 168 小时
  - `"1m"`：默认 60 分钟，最大 1440 分钟

- `models: optional array of string`

  将返回的用量限制为指定的模型。

- `page: optional string`

  可选设置为上一次响应中的 `next_page` 令牌。

- `service_account_ids: optional array of string`

  将返回的用量限制为指定的服务账户 ID。

- `service_tiers: optional array of "standard" or "batch" or "priority" or 3 more`

  将返回的用量限制为指定的服务层级。

  - `"standard"`

  - `"batch"`

  - `"priority"`

  - `"priority_on_demand"`

  - `"flex"`

  - `"flex_discount"`

- `speeds: optional array of "standard" or "fast"`

  将返回的用量限制为指定的速度（Claude Code 研究预览版）。
  需要 `fast-mode-2026-02-01` beta 请求头。

  - `"standard"`

  - `"fast"`

- `workspace_ids: optional array of string`

  将返回的用量限制为指定的工作区 ID。

### 请求头参数

- `"anthropic-beta": optional array of string`

  可选请求头，用于指定要使用的 beta 版本。

  要使用多个 beta，请使用逗号分隔的列表，如 `beta1,beta2`，或为每个 beta 多次指定该请求头。

### 返回值

- `MessagesUsageReport object { data, has_more, next_page }`

  - `data: array of object { ending_at, results, starting_at }`

    - `ending_at: string`

      时间桶的结束时间（不包含），RFC 3339 格式。

    - `results: array of object { account_id, api_key_id, cache_creation, 10 more }`

      此时间桶的用量项目列表。如果指定了一个或多个 `group_by[]` 参数，可能会有多个项目。

      - `account_id: string`

        发起请求的用户账户 ID。如果未按账户分组或非 OAuth 请求则为 `null`。

      - `api_key_id: string`

        使用的 API 密钥 ID。如果未按 API 密钥分组或在 Anthropic Console 中的用量则为 `null`。

      - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }`

        缓存创建的输入 token 数量。

        - `ephemeral_1h_input_tokens: number`

          用于创建 1 小时缓存条目的输入 token 数量。

        - `ephemeral_5m_input_tokens: number`

          用于创建 5 分钟缓存条目的输入 token 数量。

      - `cache_read_input_tokens: number`

        从缓存中读取的输入 token 数量。

      - `context_window: "0-200k" or "200k-1M"`

        使用的上下文窗口。如果未按上下文窗口分组则为 `null`。

        - `"0-200k"`

        - `"200k-1M"`

      - `inference_geo: string`

        使用的推理地理位置，如果设置了请求的 `inference_geo` 参数则与之匹配，否则使用工作区的 `default_inference_geo`。
        对于不支持指定 `inference_geo` 的模型，值为 `"not_available"`。如果未按推理地理位置分组则始终为 `null`。

      - `model: string`

        使用的模型。如果未按模型分组则为 `null`。

      - `output_tokens: number`

        生成的输出 token 数量。

      - `server_tool_use: object { web_search_requests }`

        服务端工具使用指标。

        - `web_search_requests: number`

          发出的网络搜索请求数量。

      - `service_account_id: string`

        发起请求的服务账户 ID。如果未按服务账户分组或非 OIDC 联合请求则为 `null`。

      - `service_tier: "standard" or "batch" or "priority" or 3 more`

        使用的服务层级。如果未按服务层级分组则为 `null`。

        - `"standard"`

        - `"batch"`

        - `"priority"`

        - `"priority_on_demand"`

        - `"flex"`

        - `"flex_discount"`

      - `uncached_input_tokens: number`

        处理的未缓存输入 token 数量。

      - `workspace_id: string`

        使用的工作区 ID。如果未按工作区分组或为默认工作区则为 `null`。

    - `starting_at: string`

      时间桶的开始时间（包含），RFC 3339 格式。

  - `has_more: boolean`

    指示是否还有更多结果。

  - `next_page: string`

    在后续请求中作为 `page` 提供的令牌，用于检索下一页数据。

### 示例

```http
curl https://api.anthropic.com/v1/organizations/usage_report/messages \
    -H 'anthropic-version: 2023-06-01' \
    -H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```

#### 响应

```json
{
  "data": [
    {
      "ending_at": "2025-08-02T00:00:00Z",
      "results": [
        {
          "account_id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
          "api_key_id": "apikey_01Rj2N8SVvo6BePZj99NhmiT",
          "cache_creation": {
            "ephemeral_1h_input_tokens": 1000,
            "ephemeral_5m_input_tokens": 500
          },
          "cache_read_input_tokens": 200,
          "context_window": "0-200k",
          "inference_geo": "global",
          "model": "claude-opus-4-6",
          "output_tokens": 500,
          "server_tool_use": {
            "web_search_requests": 10
          },
          "service_account_id": "svac_01Hk3R9TWxq7CfQak00OiVw4",
          "service_tier": "standard",
          "uncached_input_tokens": 1500,
          "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
        }
      ],
      "starting_at": "2025-08-01T00:00:00Z"
    }
  ],
  "has_more": true,
  "next_page": "2019-12-27T18:11:19.117Z"
}
```