支出限额 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 中点击 Request more usage（请求更多使用量）时，会创建一个支出限额提升请求。请求不能通过此 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}'



示例工作流

这些工作流将支出限额 API 与 Analytics API 的成本端点结合使用。Analytics 成本端点专为跨日期范围的组织范围支出报告而设计。GET /spend_limits/effective 返回当前适用于每位成员的上限。先使用 Analytics 进行扫描以发现需要关注的成员，然后使用 /effective 读取他们当前的上限。

支出限额端点需要 spend_limits 作用域，Analytics 成本端点需要 read:analytics；请参阅 Analytics API 了解如何配置访问权限。两者的所有货币值均为最小单位（美分）的十进制字符串。两个 API 都使用不透明游标进行分页。设置明确的 limit 并通过 next_page 翻页直到其为 null，以覆盖整个组织。



自动化提升请求审核流程

运行一个定时任务，获取待处理请求，应用您组织的审批策略，并解决每个请求。

1. 列出待处理请求：

   cURL

   

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

   每个请求都带有请求者的 actor.user_id 和实时的 spend_summary，其中包含他们当前的有效 amount 和 period_to_date_spend，足以在无需单独查询的情况下做出决策。

2. 应用您的策略。例如，当成员当前的 amount 低于某个阈值时自动批准，并将较大的上限转交人工审核。

3. 解决每个请求。要批准，请提供新的上限：

   cURL

   

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

   要拒绝，请改为向 .../{id}/deny 发送 POST 请求。当您自己的系统会通知请求者时，传递 suppress_notification: true。



识别接近支出限额的成员

找出接近上限的成员，以便在他们被阻止之前提高限额。

1. 从 Analytics API 拉取每位成员的月度至今支出（每位成员一行，默认按支出从高到低排序）：

   cURL

   

   curl "https://api.anthropic.com/v1/organizations/analytics/user_cost_report?starting_at=2026-06-01T00:00:00Z&limit=1000" \
     --header "x-api-key: $ANALYTICS_API_KEY"

   每行包含 actor.user_id、actor.email 和 amount（成员的支出，以美分为单位）。通过 next_page 翻页以覆盖整个组织。

2. 对于支出最高的成员（或所有超过某个美元阈值的成员），批量获取有效上限：

   cURL

   

   curl "https://api.anthropic.com/v1/organizations/spend_limits/effective?user_ids[]=user_01Ab...&user_ids[]=user_01Cd...&limit=100" \
     --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

   每行返回的上限为 amount（null = 无限制，"0" = 仅限包含的使用量）以及 period_to_date_spend。

3. 对于每位具有正数上限的成员，计算 period_to_date_spend / amount 并标记达到或超过您的阈值（例如 80%）的成员。将 "0" 上限视为已达到限额。此比率没有服务器端过滤器。

4. 对标记的成员采取行动：使用 POST /v1/organizations/spend_limits 提高上限，批准待处理的提升请求（如果存在），或联系该成员。



查找使用量快速变化的成员

发现支出周环比大幅增长的成员。

1. 从 Analytics API 拉取过去两周的按成员每日成本：

   cURL

   

   curl "https://api.anthropic.com/v1/organizations/analytics/user_cost_report?starting_at=2026-06-09T00:00:00Z&ending_at=2026-06-23T00:00:00Z&bucket_width=1d&limit=1000" \
     --header "x-api-key: $ANALYTICS_API_KEY"

   设置 bucket_width 后，每位成员每天有使用量时对应一行；通过 next_page 翻页以收集每位成员的完整序列。

2. 按 actor.user_id 对行进行分组。对于每位成员，分别汇总最近七天和之前七天的数据。标记最近一周超过前一周达到您选定倍数（例如三倍）的成员。最近几天的成本是临时性的，可能会向上修正；为了获得可重复的比较结果，请将 ending_at 设置为不晚于先前返回的 data_refreshed_at（参见数据可用性和新鲜度）。

3. 对标记的成员采取行动：使用 POST /v1/organizations/spend_limits 调整上限，或联系该成员。



常见问题



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

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



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

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



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

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



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

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



另请参阅