Claude Spend Limits APIで支出上限と増額申請を管理する
Claude Enterprise組織向けSpend Limits APIの支出上限階層・増額申請のライフサイクル・per-user overrideの設定方法を一次ソースから解説します。
Spend Limits APIは何を解決するAPIか
Claude Enterprise組織では、メンバーごとに月々の支出上限がかかります。上限はどこかで必ず決まっていますが、管理者がその値をConsole画面でしか見られず、超過したメンバーからの増額依頼もメールや口頭のやり取りに頼っていると、組織が大きくなるほど運用が回らなくなります。Spend Limits APIは、この「誰にいくらの上限がかかっていて、それはどこから継承されているか」を読み取り、必要なら個人単位で上書きし、メンバーからの増額申請を承認・却下するためのAdmin APIです。
このAPIはClaude Enterprise組織限定で、Claude Platform(Claude Console)組織には提供されません。前提として組織がClaude Enterpriseプランであること、そして管理者がclaude.aiの請求設定で使用量クレジットを有効にしていることが要ります。認証はread:spend_limits(参照系)とwrite:spend_limits(更新・削除系)のスコープを持つAdmin API資格情報で、リクエストのたびにanthropic-versionヘッダーも必要です。
支出上限はどの階層から継承されるか
支出上限は単一の値ではなく、階層から解決される値です。メンバー個別の上書きが無ければ、そのメンバーが属するグループの上限(グループ単位の支出上限を使っている場合)、次にシートティアの上限、最後に組織全体の既定値という順で継承されます。ここで重要なのは、グループの上限はプールされた予算ではないという点です。グループに属する各メンバーは、あくまで自分自身の支出に対して個別に上限を課されます。
GET /v1/organizations/spend_limits/effectiveを呼ぶと、現在の全メンバーについて、解決済みの実効上限とsource(user・seat_tier・rbac_group・organizationのいずれか)、そして当該期間の累計支出が一括で返ります。
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"金額はすべて組織の請求通貨の最小単位(USDならセント)の文字列です。"50000"は500.00ドルを意味します。表示するときは10進数として解釈し100で割ります。大きな金額を扱うときに2進浮動小数点を使うと誤差が出るので避けます。
amountはnullを取り得るフィールドで、意味が場所によって変わります。メンバーの実効行でのnullは「上限なし(無制限)」、"0"は「プランのincluded usageを超えては使えない」ことを意味します。一方、個別に設定した支出上限の行(GET /v1/organizations/spend_limits/{id}が返す行)でのnullは「その行に数値の上限が設定されていない」ことしか意味しません。無制限なのか単に未設定なのかを区別するには、実効行の方を読む必要があります。
| フィールド | 値の例 | 意味 |
|---|---|---|
source | 値の例user / seat_tier / rbac_group / organization | 意味どの階層から上限が解決されたか |
amount(実効行) | 値の例null / "0" / "50000" | 意味無制限 / 追加利用不可 / 500.00ドル |
period | 値の例monthly | 意味現時点で唯一サポートされる期間。UTC 0時0分・毎月1日にリセット |
per-user overrideを設定するにはPOST /v1/organizations/spend_limitsを呼びます。これは(scope, period)をキーにしたupsertで、同じメンバー・同じ期間にすでに上限がある場合は上書きします。このエンドポイントが受け付けるのはscope.type: "user"のみで、シートティア・グループ・組織全体の既定値はAPIではなくclaude.aiの管理画面側で設定します。
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"}'DELETE /v1/organizations/spend_limits/{spend_limit_id}で上書きを削除すると、メンバーは階層のどこかにある値へフォールバックします。どこにも既定値が無ければ無制限に戻ります。シートティア・グループ・組織レベルの行はこのエンドポイントでは削除できません。
増額申請のライフサイクルをAPIで処理する
支出上限の増額申請は、メンバーがclaude.aiで「Request more usage」を押した瞬間に作られます。このAPI経由で新規作成することはできません。申請のstatusは3種類で、pending(管理者の判断待ち。多くの場合、判断に使えるspend_summaryが付く)、approved(承認済み。管理者の明示承認・別の管理操作による上限引き上げ・Anthropicサポートの代理対応のいずれか)、denied(却下。却下から30日間はclaude.ai上のリクエストボタンが非表示になるが、その間も管理者は上限を直接引き上げられる)です。承認・却下はどちらも終端状態で、メンバーが同時に持てるpendingは1件までです。
POST /v1/organizations/spend_limit_increase_requests/{id}/approveを呼ぶと、POST /v1/organizations/spend_limitsと同じper-user上限の行を書き込みつつ、申請をapprovedに遷移させます。ここが直感に反しやすい点で、支出上限を直接設定するだけでは保留中の申請は解決されません。申請を閉じる意図があるなら、必ずapproveエンドポイントを使います。
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}'申請そのものには「希望額」というフィールドが無く、承認時に管理者が新しい上限額を決めて渡す設計です。既定ではAnthropicが承認・却下の結果をメンバーへメール通知しますが、suppress_notification: trueを渡すと自社の通知システム側に任せられます。却下はdeniedに対して冪等で、すでに却下済みの申請を再度denyしても200が返り、承認済みの申請を却下しようとするとエラーになります。これにより、リトライと矛盾した判断を自動化側で区別できます。
エンドポイント全体は1組織あたり毎分60リクエストのレート制限を共有し、超過は429です。一覧系エンドポイントは不透明カーソルでページングし、user_ids[]やstatus[]などのフィルタをページの途中で変えると、古いカーソルは400(cursor does not match current query parameters)で拒否されます。フィルタを変えるなら最初のページからやり直します。
支出上限に近づいているメンバーを先回りで見つける
増額申請が来てから対応するのではなく、上限に近づいているメンバーを先に見つけて能動的に上げる運用も組めます。まずAnalytics APIのuser_cost_reportでメンバー別の当月コストを取得し、支出の多い順に並べます。
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"上位のメンバー、またはドル建てのしきい値を超えたメンバーについて、spend_limits/effectiveをuser_ids[]でバッチ指定して現在の上限を取得します。各行のamount(nullは無制限、"0"はincluded usageのみ)とperiod_to_date_spendを突き合わせ、比率が80%のようなしきい値を超えていれば上限引き上げの候補として扱います。この比率を計算するサーバー側のフィルタは無いため、判定はクライアント側で行います。"0"のキャップはすでに上限に達している扱いにします。
インシデント対応中だけ一時的に上限を引き上げる運用も同じ部品で組めます。インシデント開始時に現在の上限を記録してから引き上げ、インシデントがクローズしたら記録しておいた値に戻すか、上書きが無かったメンバーならDELETEで上書き自体を消します。承認・却下・引き上げのいずれもsuppress_notification: trueを活用すれば、自社のインシデント管理システム側の通知と二重に送られることを避けられます。
apps gatewayやAnalytics APIとは何が違うか
支出上限という言葉は、Claudeのエコシステム内で複数のレイヤーに登場するため混同しやすい言葉です。本記事のSpend Limits APIは、組織全体を対象にしたAdmin APIで、Claude Enterpriseのメンバー単位の月次上限を扱います。一方、Claude apps gatewayの支出上限は、セルフホストのゲートウェイが自前のPostgresで管理する別実装で、ワイヤ形式こそAnthropic公式に似せていますが同一のAPIではありません。ゲートウェイ側は日/週/月の3期間に対応しグループ・組織のscopeも書き込めるのに対し、本APIの書き込み系はuserスコープしか受け付けません。
同様に、Claude Enterpriseのグループ支出上限をConsole画面で設定する運用と、本APIで個人の上書きを読み書きする運用は補完関係にあります。グループ単位の既定値は管理画面で決め、個別対応が必要なメンバーだけをAPIで上書きする、という役割分担が実務的です。上限がどのワークスペースのメンバーに効いているかを把握したい場合は、Claude Workspacesの仕組みを先に押さえておくとrbac_groupの単位が見えやすくなります。支出のレポーティング自体は本APIの対象外で、期間集計や時系列の推移を見たいときはAnalytics APIのコストエンドポイントを併用します。Claude Platform(Claude Console)組織向けのUsage and Cost APIとは対象組織のタイプが異なる別物のAPIキーが要る点は、レポーティング用のAPIを選ぶ際に取り違えやすいので注意します。Analytics APIで支出の多いメンバーを洗い出し、その一覧をSpend Limits APIの/effectiveに渡して現在の上限と突き合わせる、という2段構えのワークフローが典型です。
バージョニングとエラーハンドリング
すべてのリクエストでanthropic-versionヘッダーの送信が必須です。利用可能なバージョンはAPIバージョニングのドキュメントに一覧があります。エラーレスポンスはAnthropicの標準エラー形式に従うため、サポートへ問い合わせる際はレスポンス本文のrequest_idをそのまま伝えると調査が早くなります。リスト系パラメータはブラケット記法で複数値を渡します。たとえばuser_ids[]=user_01AbCdEfGh&user_ids[]=user_01JkLmNoPqのように、同じキー名を値の数だけ繰り返します。クエリ文字列を組み立てるライブラリによっては、この記法が既定で使えない場合もあるため、生成されたリクエストURLを一度目視で確認しておくと事故を防げます。
まとめ
Spend Limits APIは、Claude Enterprise組織のメンバー単位の支出上限を「どこから継承されているか」まで含めて可視化し、個人単位の上書きと増額申請の承認・却下を1本のAPIでまとめて扱う仕組みです。グループ上限が共有プールではなく個人ごとのゲート値である点、申請の承認には専用エンドポイントが要る点、Claude apps gatewayの支出上限とは別レイヤーの仕組みである点は、実装前に取り違えやすいので特に確認しておく価値があります。