支出限额 API

支出限额 API 允许您为每位 Claude Enterprise 成员设置支出限额，查看每位成员的支出限额继承来源，并审核或处理成员提出的提高限额请求。

如需按用户和按时间段的使用量及成本报告，请参阅 Analytics API。



概述

该 API 在两个资源上公开了八个端点：

使用支出限额端点来回答"每位成员适用什么支出限额、该限额来自何处、他们距离限额还有多远？"，以及设置按用户的覆盖设置。使用支出限额提升请求端点来处理成员提交的请求队列。



前提条件

• 您的组织必须使用 Claude Enterprise 计划。
• 您的组织必须已启用使用额度。您的主要所有者可以在 claude.ai 的账单设置中启用它们。



快速开始

列出每位成员的有效月度支出限额和当前周期至今的支出：

curl "https://api.anthropic.com/v1/organizations/spend_limits/effective?limit=20" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"



关键概念



支出限额层级

有效支出限额（effective spend limit）适用于每位成员的支出，它从作用域级别的层级结构中解析得出。当成员没有按用户的覆盖设置时，他们将继承为其群组配置的支出限额（如果您的组织使用基于群组的限额）、其席位层级的限额或组织范围的默认限额。群组支出限额是按成员的默认值：继承该限额的每位成员都根据其自身的支出进行限制，而非共享的群组预算池。

读取 GET /v1/organizations/spend_limits/effective 会返回每位当前成员及其解析出的有效支出限额、该限额的解析来源（source）以及他们当前周期至今的支出。使用 POST /v1/organizations/spend_limits 设置按用户的覆盖设置会将成员固定到特定的支出限额，而不管他们原本会继承什么限额。删除该覆盖设置会使他们回退到继承的支出限额（如果不存在继承限额，则变为无限制）。

每位成员行上的 source 字段告诉您其支出限额解析自哪个级别：user（按用户的覆盖设置）、seat_tier、rbac_group 或 organization。请将作用域类型视为开放集合；对于未知值应直接跳过而非报错。



周期

period 是支出限额生效和支出重置的循环时间窗口。支出限额由其 (scope, period) 对标识。目前 monthly 是唯一支持的周期；月度支出在每个日历月第一天的 00



金额和货币

所有货币值均为字符串，以组织账单货币的最小单位表示（对于 USD 为美分）。例如，"50000" 表示 500.00 美元。解析为十进制数并除以 100 以显示美元金额；对于较大的值，请避免使用二进制浮点数。

amount 可为空。在成员的有效行中，null 表示无限制（无支出限额），而 "0" 表示该成员无法使用超出其计划所含用量的 Claude 服务。在已配置的支出限额行上（由 GET /v1/organizations/spend_limits/{id} 返回），null 仅表示未设置数值型支出限额；请读取该成员的有效行以区分无限制和仅限所含用量。

period_to_date_spend 是成员自当前 period 开始以来累计的支出，采用相同的最小单位格式；它可能包含小数部分（例如 "41280.125"）。如果支出读数暂时不可用，它可能显示为 "0"；请将其视为参考信息，而非事务性数据。



提升请求生命周期

当成员在 claude.ai 中点击请求更多用量时，会创建一个支出限额提升请求。请求不能通过此 API 创建。请求的 status 为以下之一：

approved 和 denied 均为终态。每位成员同一时间最多有一个 pending 请求。

使用 POST /v1/organizations/spend_limit_increase_requests/{id}/approve 批准请求会写入与 POST /v1/organizations/spend_limits 相同的按用户支出限额行。直接设置支出限额不会转换待处理请求的状态；请使用批准端点来解决请求。

默认情况下，当成员的请求被批准或拒绝时，Anthropic 会向该成员发送电子邮件。在批准或拒绝时传递 suppress_notification: true 可禁止发送该电子邮件（例如，当您自己的系统会通知该成员时）。



速率限制

所有八个端点共享一个按组织计算的限制，即每分钟 60 个请求。超出限制的请求将返回 429 Too Many Requests。



分页

GET /v1/organizations/spend_limits/effective 和 GET /v1/organizations/spend_limit_increase_requests 使用不透明游标进行分页。第一个请求返回最多 limit 行以及一个 next_page 游标；将该游标原样作为下一个请求的 page 参数传递，重复此过程直到 next_page 为 null。

**不要在分页序列中途更改查询参数。**游标与发出它们的过滤条件绑定。如果您更改了 user_ids[]、period[]、status[] 或 actor_ids[] 并传递旧游标，您将收到 400 错误，提示 "cursor does not match current query parameters"（游标与当前查询参数不匹配）。请改为从第一页开始新的序列。



序列化列表参数

列表参数使用方括号表示法：为每个值重复带 [] 的参数名。

user_ids[]=user_01AbCdEfGh&user_ids[]=user_01JkLmNoPq



错误响应

错误响应遵循错误中记录的标准格式。联系支持团队时，请引用响应正文中的 request_id。



支出限额



列出每位成员的有效支出限额

GET /v1/organizations/spend_limits/effective 为每位当前成员返回一行，反映每位成员的有效支出限额、其在作用域层级中的 source 以及他们的 period_to_date_spend。需要 read:spend_limits 作用域。

有关完整的参数详情和响应架构，请参阅 API 参考中的列出有效支出限额。

curl "https://api.anthropic.com/v1/organizations/spend_limits/effective?limit=20" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

{
  "data": [
    {
      "scope": { "type": "user", "user_id": "user_01AbCdEfGh" },
      "actor": {
        "type": "user_actor",
        "user_id": "user_01AbCdEfGh",
        "name": "Jane Smith",
        "email_address": "[email protected]",
        "deleted": false
      },
      "amount": "50000",
      "currency": "USD",
      "period": "monthly",
      "source": { "type": "seat_tier", "seat_tier": "enterprise_standard" },
      "spend_limit_id": "spl_01XyZaBcDeFgHiJkLmNoPq",
      "period_to_date_spend": "31402.5"
    }
  ],
  "next_page": "page_..."
}



获取单个支出限额

GET /v1/organizations/spend_limits/{spend_limit_id} 按 ID 返回一个已配置的支出限额。使用它来检查 spend_limit_id 字段所引用的行。需要 read:spend_limits 作用域。

有关完整的参数详情和响应架构，请参阅 API 参考中的检索支出限额。

curl "https://api.anthropic.com/v1/organizations/spend_limits/spl_01AbCdEfGhIjKlMnOpQrSt" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"



设置按用户的覆盖设置

POST /v1/organizations/spend_limits 设置按用户的支出限额覆盖。这是一个以 (scope, period) 为键的 upsert 操作：为已有限额的用户和周期设置限额会原地覆盖它。此端点仅接受 scope.type: "user"；席位层级、群组和组织级别的默认值在 claude.ai 设置中配置。需要 write:spend_limits 作用域。

有关完整的参数详情和响应架构，请参阅 API 参考中的创建支出限额。

curl --request POST "https://api.anthropic.com/v1/organizations/spend_limits" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --data '{"scope": {"type": "user", "user_id": "user_01AbCdEfGh"}, "amount": "75000"}'

{
  "type": "spend_limit",
  "id": "spl_01RsTuVwXyZaBcDeFgHiJk",
  "created_at": "2026-05-11T10:02:44Z",
  "updated_at": "2026-05-11T10:02:44Z",
  "scope": { "type": "user", "user_id": "user_01AbCdEfGh" },
  "amount": "75000",
  "currency": "USD",
  "period": "monthly"
}



移除按用户的覆盖设置

DELETE /v1/organizations/spend_limits/{spend_limit_id} 移除按用户的覆盖设置，之后该成员将回退到任何继承的席位层级、群组或组织默认值。席位层级、群组和组织级别的行无法通过此端点删除。需要 write:spend_limits 作用域。

有关完整的参数详情和响应架构，请参阅 API 参考中的删除支出限额。

curl --request DELETE "https://api.anthropic.com/v1/organizations/spend_limits/spl_01RsTuVwXyZaBcDeFgHiJk" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"



支出限额提升请求



列出提升请求

GET /v1/organizations/spend_limit_increase_requests 列出请求，按最新优先排序。可按 status[]（pending、approved、denied）和 actor_ids[] 过滤。该列表不包括请求者已不再是组织成员的请求。需要 read:spend_limits 作用域。

有关完整的参数详情和响应架构，请参阅 API 参考中的列出支出限额提升请求。

curl "https://api.anthropic.com/v1/organizations/spend_limit_increase_requests?status[]=pending&limit=50" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

每个待处理请求都带有实时的 spend_summary，显示请求者当前的有效支出限额和当前周期至今的支出，足以让您无需单独查询即可做出决策。



获取单个提升请求

GET /v1/organizations/spend_limit_increase_requests/{id} 按 ID 返回一个请求。需要 read:spend_limits 作用域。

有关完整的参数详情和响应架构，请参阅 API 参考中的检索支出限额提升请求。

curl "https://api.anthropic.com/v1/organizations/spend_limit_increase_requests/slir_01AbCdEfGhIjKlMnOpQrSt" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"



批准提升请求

POST /v1/organizations/spend_limit_increase_requests/{id}/approve 批准待处理的请求：它为请求者写入一个按用户的支出限额，金额为管理员提供的 amount，并将请求转换为 approved 状态。请求本身不携带请求的金额；您在批准时提供新的支出限额。需要 write:spend_limits 作用域。

有关完整的参数详情和响应架构，请参阅 API 参考中的批准支出限额提升请求。

curl --request POST "https://api.anthropic.com/v1/organizations/spend_limit_increase_requests/slir_01AbCdEfGhIjKlMnOpQrSt/approve" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --data '{"amount": "75000", "suppress_notification": true}'



拒绝提升请求

POST /v1/organizations/spend_limit_increase_requests/{id}/deny 拒绝待处理的请求。对 denied 状态具有幂等性：拒绝已被拒绝的请求会返回 200 及现有资源。该端点会拒绝对已批准请求的拒绝尝试，以便自动化系统能够区分重试和冲突的决策。需要 write:spend_limits 作用域。

有关完整的参数详情和响应架构，请参阅 API 参考中的拒绝支出限额提升请求。

curl --request POST "https://api.anthropic.com/v1/organizations/spend_limit_increase_requests/slir_01AbCdEfGhIjKlMnOpQrSt/deny" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --data '{"suppress_notification": true}'



常见问题



直接设置支出限额是否会解决成员的待处理提升请求？

不会。POST /v1/organizations/spend_limits 会写入覆盖设置，但不会触及待处理的请求。请使用 POST /v1/organizations/spend_limit_increase_requests/{id}/approve 在一次调用中解决请求并写入覆盖设置。



删除按用户的覆盖设置后会发生什么？

该成员会回退到他们从层级中继承的任何限额：其群组、席位层级或组织默认值。如果任何级别都不存在默认值，则该成员为无限制。



我可以通过此 API 设置席位层级或组织范围的默认值吗？

不可以。通过此 API 只能写入按用户的覆盖设置。席位层级、群组和组织级别的默认值在 claude.ai 的组织设置中配置。



为什么活跃成员的 period_to_date_spend 有时显示为 "0"？

支出读数可能暂时不可用，在这种情况下该字段显示为 "0" 而不是报错。请将其视为参考信息。



另请参阅