支出限額 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 中點擊 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 使用不透明游標（opaque cursor）進行分頁。第一個請求會傳回最多 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" 而非傳回錯誤。請將其視為參考資訊。



另請參閱