支出限額 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



金額與貨幣

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

amount 可為 null。在成員的有效資料列中，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}'



範例工作流程

這些工作流程結合了支出限額 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" 而非產生錯誤。請將其視為參考資訊。



另請參閱