# 速率限制 API

使用速率限制 API 以编程方式查询您组织的 API 速率限制。

---

<Tip>
**Admin API 不适用于个人账户。** 要与团队成员协作和添加成员，请在**控制台 → 设置 → 组织**中设置您的组织。
</Tip>

速率限制 API 提供对您组织及其工作区配置的速率限制的编程访问。这与 [Claude 控制台](/settings/limits)页面上显示的信息相同。

使用此 API：

- **保持网关和代理同步：** 在启动时和定期读取当前限制，而不是硬编码当 Anthropic 调整时会漂移的值。
- **驱动内部警报：** 将[使用量和成本 API](/docs/en/manage-claude/usage-cost-api) 的使用量数据与配置的限制进行比较。
- **审核工作区配置：** 验证工作区覆盖是否与配置自动化预期匹配。

<Check>
  **需要 Admin API 密钥**

  此 API 是 [Admin API](/docs/en/manage-claude/admin-api) 的一部分。这些端点需要一个 Admin API 密钥（以 `sk-ant-admin...` 开头），它与标准 API 密钥不同。只有具有管理员角色的组织成员才能通过 [Claude 控制台](/settings/admin-keys)配置 Admin API 密钥。
</Check>

## 快速开始

列出为您的组织配置的速率限制：

```bash cURL
curl "https://api.anthropic.com/v1/organizations/rate_limits" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"
```

## 组织速率限制

`/v1/organizations/rate_limits` 端点返回在组织级别应用于 Messages API 及其支持资源的速率限制。不包括其他产品的限制，如 [Claude 托管智能体](/docs/en/managed-agents/overview)。

### 核心概念

- **速率限制组：** 响应中的每个条目代表一个速率限制组。模型速率限制被分组，以便多个模型版本共享一组限制，其他组涵盖资源，如 Message Batches API、Files API、Token Counting API、智能体技能和网络搜索工具。
- **`group_type`：** 标识条目涵盖的限制类别。有关值列表，请参阅[按组类型过滤](#按组类型过滤)。
- **`models` 列表：** 对于 `model_group` 条目，`models` 字段列出每个计入该组限制的模型 ID 和别名。使用此列表查找任何模型字符串属于哪个组。对于其他组类型，`models` 为 `null`。
- **`limits` 列表：** 每个组携带一个 `{type, value}` 对列表。`type` 字段标识限制器（如 `requests_per_minute`、`input_tokens_per_minute` 或 `output_tokens_per_minute`），`value` 是配置的限制。有关每个限制器的测量和执行方式，请参阅[速率限制](/docs/en/api/rate-limits)。

有关完整的参数详细信息和响应架构，请参阅[组织速率限制 API 参考](/docs/en/api/admin/rate_limits/list)。

### 列出所有组织速率限制

```bash cURL
curl "https://api.anthropic.com/v1/organizations/rate_limits" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"
```

```json
{
  "data": [
    {
      "type": "rate_limit",
      "group_type": "model_group",
      "models": [
        "claude-opus-4-5",
        "claude-opus-4-5-20251101",
        "claude-opus-4-6",
        "claude-opus-4-7"
      ],
      "limits": [
        { "type": "requests_per_minute", "value": 4000 },
        { "type": "input_tokens_per_minute", "value": 10000000 },
        { "type": "output_tokens_per_minute", "value": 800000 }
      ]
    },
    {
      "type": "rate_limit",
      "group_type": "batch",
      "models": null,
      "limits": [{ "type": "enqueued_batch_requests", "value": 500000 }]
    }
  ],
  "next_page": null
}
```

### 查找特定模型的限制

将任何模型 ID 或别名作为 `model` 查询参数传递，以仅返回包含它的条目：

```bash cURL
curl "https://api.anthropic.com/v1/organizations/rate_limits?model=claude-opus-4-7" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"
```

如果模型字符串与任何组不匹配，端点返回 404 错误。`model` 参数仅在组织端点上受支持；工作区端点不接受它。

## 工作区速率限制

`/v1/organizations/workspaces/{workspace_id}/rate_limits` 端点返回为单个工作区配置的速率限制覆盖。

响应仅包含覆盖，因此缺少的内容从组织继承：

- `data` 中不存在的组完全没有工作区覆盖。工作区继承该组的组织级别限制（不是无限制）。
- 在存在的组中，`limits[]` 中不存在的限制器类型没有该限制器的工作区覆盖。工作区继承其组织值。
- 对于存在的每个限制器，`org_limit` 是同一限制器的组织级别值，如果组织没有为该限制器类型配置限制，则为 `null`。

有关完整的参数详细信息和响应架构，请参阅[工作区速率限制 API 参考](/docs/en/api/admin/workspaces/rate_limits/list)。

<Tip>
要检索您组织的工作区 ID，请使用[列出工作区](/docs/en/api/admin/workspaces/list)端点，或在 [Claude 控制台](/settings/workspaces)中找到它们。默认工作区不能有速率限制覆盖，因此在此端点上没有条目；使用组织端点读取其限制。
</Tip>

```bash cURL
curl "https://api.anthropic.com/v1/organizations/workspaces/wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ/rate_limits" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"
```

```json
{
  "data": [
    {
      "type": "workspace_rate_limit",
      "group_type": "model_group",
      "models": [
        "claude-opus-4-5",
        "claude-opus-4-5-20251101",
        "claude-opus-4-6",
        "claude-opus-4-7"
      ],
      "limits": [
        { "type": "requests_per_minute", "value": 1000, "org_limit": 4000 },
        { "type": "input_tokens_per_minute", "value": 500000, "org_limit": 10000000 }
      ]
    }
  ],
  "next_page": null
}
```

## 按组类型过滤

两个端点都接受可选的 `group_type` 查询参数，将响应限制为单个类别：

```bash cURL
curl "https://api.anthropic.com/v1/organizations/rate_limits?group_type=batch" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"
```

有效值为 `model_group`、`batch`、`token_count`、`files`、`skills` 和 `web_search`。

## 分页

两个端点都接受 `page` 查询参数并返回 `next_page` 字段。响应目前始终是单页，因此 `next_page` 为 `null`。在 `next_page` 上循环，以便您的客户端在响应增长时无需更改即可正确分页。

## 常见问题

### 哪些模型字符串出现在 `models` 列表中？

每个计入该组的模型 ID 和别名，包括带日期的 ID（如 `claude-sonnet-4-5-20250929`）和不带日期的别名（如 `claude-sonnet-4-5`）。查找您传递给 Messages API 的任何模型字符串，您会在恰好一个 `model_group` 条目中找到它。

### 如果组在工作区响应中缺失意味着什么？

工作区没有该组的覆盖，并继承组织级别的限制。查询组织端点以查看继承的值。

### 我可以使用此 API 更新速率限制吗？

不可以。要设置工作区速率限制，请在 [Claude 控制台](/settings/workspaces)中打开工作区并使用**限制**选项卡。

## 另请参阅

- [速率限制](/docs/en/api/rate-limits)
- [Admin API](/docs/en/manage-claude/admin-api)
- [Admin API 参考](/docs/en/api/admin)
- [工作区](/docs/en/manage-claude/workspaces)
- [使用量和成本 API](/docs/en/manage-claude/usage-cost-api)