支出限額 API

Spend Limits API（支出限額 API）讓您可以為每位 Claude Enterprise 成員設定支出限額、查看每位成員的支出限額繼承自何處，並審查或處理成員提出的提高限額請求。

如需依使用者及依時間區段的用量與成本報告，請參閱 Analytics APIs。

概覽

此 API 在兩種資源上公開八個端點：

使用支出限額端點來回答「每位成員適用的支出限額是多少、來自何處，以及他們距離限額還有多遠？」並設定個別使用者的覆寫值。使用支出限額提高請求端點來處理成員提交的請求佇列。

先決條件

• 您的組織必須使用 Claude Enterprise 方案。
• 您的組織必須已開啟使用額度（usage credits）。您的主要擁有者可以在 claude.ai 帳單設定中開啟。

快速開始

列出每位成員的有效每月支出限額與本期累計支出：

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

關鍵概念

支出限額階層

每位成員的支出都適用一個 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:00 UTC 重設。請將 period 視為開放集合。

金額與幣別

所有貨幣值皆為字串，以組織帳單幣別的最小單位表示（美元為美分）。例如，"50000" 代表 500.00 USD。請以十進位數解析並除以 100 來顯示美元金額；對於大數值請避免使用二進位浮點數。

amount 可為 null。在成員的有效資料列中，null 表示無限制（沒有支出限額），而 "0" 表示該成員無法在其方案所含用量之外使用 Claude。在已設定的支出限額資料列上（如 GET /v1/organizations/spend_limits/{id} 所傳回），null 僅表示未設定數值支出限額；請讀取成員的有效資料列以區分無限制與僅限所含用量。

period_to_date_spend 是成員自目前 period 開始以來累計的支出，採用相同的最小單位格式；它可能包含小數部分（例如 "41280.125"）。若支出讀數暫時無法取得，它可能顯示為 "0"；請將其視為參考資訊，而非交易資料。

提高請求的生命週期

當成員在 claude.ai 中點擊 Request more usage 時，會建立一個 spend limit increase request（支出限額提高請求）。請求不會透過此 API 建立。請求的 status 為下列其中之一：

approved 與 denied 皆為終止狀態。一位成員同一時間最多只有一個 pending 請求。

使用 POST /v1/organizations/spend_limit_increase_requests/{id}/approve 核准時，會寫入與 POST /v1/organizations/spend_limits 相同的個別使用者支出限額資料列。直接設定支出限額不會轉換待處理請求的狀態；請使用核准端點來解決請求。

預設情況下，當成員的請求被核准或拒絕時，Anthropic 會寄送電子郵件通知該成員。在核准或拒絕時傳遞 suppress_notification: true 可抑制該電子郵件（例如，當您自己的系統會通知成員時）。

版本控制

請在每個請求中傳送 anthropic-version 標頭；如需可用版本，請參閱 API 版本。

速率限制

所有八個端點共用單一的每組織 rate limit（速率限制），為每分鐘 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" \
  --header "anthropic-version: 2023-06-01"

{
  "data": [
    {
      "scope": { "type": "user", "user_id": "user_01AbCdEfGh" },
      "actor": {
        "type": "user_actor",
        "user_id": "user_01AbCdEfGh",
        "name": "Jane Smith",
        "email_address": "jane@example.com",
        "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" \
  --header "anthropic-version: 2023-06-01"

設定個別使用者覆寫值

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" \
  --header "anthropic-version: 2023-06-01" \
  --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" \
  --header "anthropic-version: 2023-06-01"

支出限額提高請求

列出提高請求

GET /v1/organizations/spend_limit_increase_requests 列出請求，最新的排在最前。可依 status[]（pending、approved、denied）與 actor_ids[] 篩選。清單會排除請求者已不再是組織成員的請求。需要 read:spend_limits 範圍。

如需完整的參數詳細資訊與回應結構描述，請參閱 API 參考中的列出支出限額提高請求。

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

每個待處理請求都附帶即時的 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" \
  --header "anthropic-version: 2023-06-01"

核准提高請求

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" \
  --header "anthropic-version: 2023-06-01" \
  --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" \
  --header "anthropic-version: 2023-06-01" \
  --data '{"suppress_notification": true}'

範例工作流程

其中部分工作流程將 Spend Limits API 與 Analytics APIs 的成本端點結合使用。Analytics 成本端點是為跨日期範圍的全組織支出報告而設計。GET /spend_limits/effective 傳回目前適用於每位成員的上限。先以 Analytics 進行掃描以找出需要關注的成員，然後以 /effective 讀取他們目前的上限。

Spend Limits 端點需要 spend_limits 範圍，而 Analytics 成本端點需要 read:analytics；請參閱 Analytics APIs 了解如何佈建存取權限。兩者的所有貨幣值皆為以最小單位（美分）表示的十進位字串。兩個 API 皆以不透明游標分頁。請設定明確的 limit 並透過 next_page 逐頁讀取直到其為 null，以涵蓋整個組織。

自動化提高請求審查流程

執行排程工作，擷取待處理請求、套用您組織的核准政策，並解決每個請求。

1. 列出待處理請求：

   cURL

   

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

   每個請求都附帶請求者的 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" \
     --header "anthropic-version: 2023-06-01" \
     --data '{"amount": "75000", "suppress_notification": true}'

   若要拒絕，請改為 POST 至 .../{id}/deny。當您自己的系統會通知請求者時，請傳遞 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" \
     --header "anthropic-version: 2023-06-01"

   每筆資料列附帶 actor.user_id、actor.email 與 amount（成員的支出，以美分計）。透過 next_page 逐頁讀取以涵蓋整個組織。

2. 針對支出最高的成員（或所有超過某個金額門檻的成員），分批擷取有效上限：

   cURL

   

   curl --globoff "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" \
     --header "anthropic-version: 2023-06-01"

   每筆資料列以 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" \
     --header "anthropic-version: 2023-06-01"

   設定 bucket_width 後，每位成員在有用量的每一天各佔一筆資料列；透過 next_page 逐頁讀取以收集每位成員的完整序列。

2. 依 actor.user_id 將資料列分組。對每位成員，加總最近七天與前七天的數值。標記最近一週超過前一週達您所選倍數（例如三倍）的成員。近期的每日成本為暫定值，可能會向上修正；若要進行可重複的比較，請將 ending_at 設定為先前傳回的 data_refreshed_at 或更早（請參閱資料可用性與新鮮度）。

3. 對被標記的成員採取行動：以 POST /v1/organizations/spend_limits 調整上限，或聯繫該成員。

在事件期間暫時提高成員的支出限額

在事件處理期間給予事件回應人員工作空間：在事件開始時提高其支出上限，並在事件結束後回復。請以您的事件管理系統作為提高上限的管控條件，例如要求提供一個該成員被指派的進行中事件 ID。

1. 讀取成員目前的上限，並記錄下來以供回復：

   cURL

   

   curl --globoff "https://api.anthropic.com/v1/organizations/spend_limits/effective?user_ids[]=user_01AbCdEfGh&period[]=monthly" \
     --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
     --header "anthropic-version: 2023-06-01"

2. 提高上限：

   cURL

   

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

3. 若回應人員在事件期間需要更廣泛的存取權限，請預先佈建一個事件回應人員群組，其自訂角色授予該權限，並在事件期間將成員加入：

   cURL

   

   curl --request POST "https://api.anthropic.com/v1/organizations/rbac_groups/rbac_group_01UvWxYzAbCdEfGhIjKlMn/members" \
     --header "content-type: application/json" \
     --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --data '{"user_id": "user_01AbCdEfGh"}'

   請參閱使用者管理了解群組端點。

4. 當您的事件系統將事件標記為已結束時，請恢復這兩項變更：還原您在步驟 1 中記錄的支出限額（如果該成員原本沒有覆寫值，則使用 DELETE /v1/organizations/spend_limits/{spend_limit_id} 刪除覆寫值），並使用 DELETE /v1/organizations/rbac_groups/{rbac_group_id}/members/{user_id} 將該成員從群組中移除。

常見問題

直接設定支出限額是否會解決成員的待處理提高請求？

不會。POST /v1/organizations/spend_limits 會寫入覆寫值，但不會變動待處理請求。請使用 POST /v1/organizations/spend_limit_increase_requests/{id}/approve 在一次呼叫中解決請求並寫入覆寫值。

刪除個別使用者覆寫值時會發生什麼事？

該成員會回退至他們從階層中繼承的任何值：其群組、席位層級或組織預設值。若任何層級都不存在預設值，該成員即為無限制。

我可以透過此 API 設定席位層級或全組織預設值嗎？

不行。只有個別使用者覆寫值可以透過此 API 寫入。席位層級、群組與組織層級的預設值需在 claude.ai 組織設定中配置。

為什麼活躍成員的 period_to_date_spend 有時會顯示為 "0"？

支出讀數可能暫時無法取得，在此情況下該欄位會顯示 "0" 而非回報錯誤。請將其視為參考資訊。

另請參閱