Claude Spend Limits APIで支出上限と増額申請を管理する

Spend Limits APIは何を解決するAPIか

Claude Enterprise組織では、メンバーごとに月々の支出上限がかかります。管理者がその値を画面でしか見られず、超過したメンバーからの増額依頼もメールや口頭に頼っていると、組織が大きくなるほど運用が回らなくなります。Spend Limits APIは、「誰にいくらの上限がかかっていて、それはどこから継承されているか」を読み取り、個人単位で上書きし、増額申請を承認・却下するためのAdmin APIです。

このAPIはClaude Enterprise組織限定で、Claude Platform(Claude Console)組織には提供されません。前提は2つあり、組織がClaude Enterpriseプランであること、そしてプライマリオーナーがclaude.aiの請求設定で使用量クレジットを有効にしていることです。認証にはread:spend_limits(GET系)とwrite:spend_limits(POST・DELETE系)のスコープを持つAdminキーを使い、リクエストのたびにanthropic-versionヘッダーも送ります。

上限はAPIと管理画面のどちらで決めるか

支出上限という言葉は、Claudeのエコシステムで複数のレイヤーに登場します。本記事のSpend Limits APIは、Claude Enterprise組織のメンバー単位の月次上限を扱う公式のAdmin APIです。

Claude apps gatewayの支出上限は、セルフホストのゲートウェイが自前のPostgresで管理する別実装です。ワイヤ形式は公式に揃えてあり、ベースURLを変えれば同じHTTPクライアントを向けられますが、同一のAPIではありません。ゲートウェイは日・週・月の3期間に対応し、ユーザー・グループ・組織の3種のscopeを書き込めます。本APIの書き込みはuserスコープと月次だけです。

Claude Enterpriseのグループ支出上限を管理画面で設定する運用とは補完関係にあります。グループ単位の既定値は画面で決め、個別対応が必要なメンバーだけをAPIで上書きします。rbac_groupが指すグループの権限まわりは、Claude Workspacesの仕組みも参照してください。

支出の期間集計や時系列の推移は、本APIの対象外です。Analytics APIのコストエンドポイントで見ます。Claude Platform(Claude Console)組織向けのUsage and Cost APIとは対象組織の種類が違います。ConsoleはUsage and Cost API、EnterpriseはAnalytics APIのコスト系を使うので、組織のタイプから選びます。

メンバーの上限がどこから来ているかを読む

メンバーに個人の上書きが無いとき、上限はグループ(グループ単位の上限を使っている場合)、シートティア、組織全体の既定値のいずれかから継承されます。グループの上限はプールされた予算ではありません。継承する各メンバーが、自分自身の支出に対して個別に上限を課されます。似た階層の考え方はレート制限にもあり、Claude APIでWorkspace単位のレート制限を設定する手順で扱っています。

GET /v1/organizations/spend_limits/effectiveは、現在の全メンバーについて実効上限・継承元(source)・当月の累計支出(period_to_date_spend)を1行ずつ返します。

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"

返る行のsourceは、上限の出どころを示します。

sourceは将来値が増えうる開いた集合として扱われています。知らない値が来たときに失敗させず、読み飛ばす実装にしておきます。periodも同じで、現在はmonthlyだけが指定でき、UTCの毎月1日0時0分にリセットされます。

金額はすべて組織の請求通貨の最小単位(USDならセント)の文字列です。"50000"は500.00ドルです。表示するときは10進数として解釈して100で割り、大きな金額で2進浮動小数点を使うのは避けます。period_to_date_spendは"41280.125"のように小数部を持つことがあり、一時的に値が取れないときはエラーではなく"0"が返ります。「0だから使っていない」と決めつけず、参考値として扱います。

nullと"0"の読み分け

amountがnullの意味は、読む行で変わります。取り違えると、無制限のメンバーを「未設定」と誤認します。

例外のメンバーだけ上限を上書きする

個人の上書きはPOST /v1/organizations/spend_limitsで作ります。(scope, period)をキーにしたupsertで、同じメンバー・同じ期間の上限が既にあれば上書きします。受け付けるのはscope.type: "user"だけで、シートティア・グループ・組織全体の既定値は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}で上書きを削除すると、メンバーは階層のどこかにある既定値へ戻ります。どのレベルにも既定値が無ければ無制限です。シートティア・グループ・組織レベルの行は、このエンドポイントでは削除できません。

メンバーから増額申請が届いたとき

増額申請は、メンバーがclaude.aiでRequest more usageを押したときに作られます。APIから新規作成はできません。申請のstatusは3種類です。

approvedとdeniedはどちらも終端状態で、メンバーが同時に持てるpendingは1件までです。

承認はPOST /v1/organizations/spend_limit_increase_requests/{id}/approveで行います。POST /v1/organizations/spend_limitsと同じ個人上限の行を書き込みつつ、申請を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で既存のリソースが返ります。一方、承認済みの申請を却下しようとすると拒否されます。この差で、自動化側はリトライと矛盾した判断を区別できます。

一覧はstatus[]とactor_ids[]で絞り込めます。申請者が既に組織を抜けている申請は一覧に出ません。

呼び出しで引っかかりやすい点

エンドポイント全体は1組織あたり毎分60リクエストのレート制限を共有し、超過は429です。レート制限ヘッダーの読み方はClaude APIレート制限ヘッダー13種の読み方と分岐ロジックで扱っています。

一覧系は不透明カーソルでページングします。user_ids[]やstatus[]などのフィルタをページの途中で変えて古いカーソルを渡すと、400(cursor does not match current query parameters)で拒否されます。フィルタを変えるときは最初のページからやり直します。ページを進めるには、next_pageの値をそのまま次のpageパラメータに渡し、next_pageがnullになるまで繰り返します。

リスト系パラメータは、同じキー名に[]を付けて値の数だけ繰り返します。たとえばuser_ids[]=user_01AbCdEfGh&user_ids[]=user_01JkLmNoPqの形です。curlでこのURLを直接書くときは、[]がglobとして解釈されないよう--globoffが要ります。公式の例も、ブラケット入りのリクエストには--globoffを付けています。

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"

エラーレスポンスはAnthropicの標準形式です。サポートへ問い合わせるときは、本文のrequest_idをそのまま伝えます。

承認ポリシーを定期ジョブで回す

spend_summaryには申請者の現在の上限と当月の支出が入っているので、別途問い合わせなくても判断できます。たとえば現在のamountが一定額未満なら自動承認し、より大きな上限への引き上げは人の確認に回す、といった分岐です。自動承認する場合は、承認の呼び出しで新しい上限をamountとして渡します。却下するときは同じ形で/denyを呼びます。自社の通知システムでメンバーへ連絡するなら、どちらにもsuppress_notification: trueを付けて二重送信を避けます。

申請が来る前に、上限間近のメンバーを見つける

申請が来る前に、上限間近のメンバーを見つけて能動的に上げる運用も組めます。支出の多い順にメンバーを拾うのはAnalytics APIのuser_cost_reportで、各行にはメンバーの当月の支出がセント単位で入ります。このエンドポイントの仕様はユーザー別コストの取得方法にあります。

ここでスコープが2種類になります。Spend Limits APIはread:spend_limits・write:spend_limits、Analytics APIはread:analyticsが要ります。プライマリオーナーが作る鍵には、複数APIのスコープを1本にまとめて付けられます。以下のcurlは、Analytics用の鍵を$ANALYTICS_API_KEYとして分けて書いた例です。

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[]をまとめて(公式の例はlimit=100)バッチ指定して現在の上限を引きます。上限が正の値のメンバーは、period_to_date_spend / amountを計算し、80%のようなしきい値以上なら引き上げ候補にします。"0"の上限は、すでに上限に達している扱いです。この比率を計算するサーバー側のフィルタは無いので、判定はクライアントで行います。

同じ当月の支出でも、period_to_date_spendとAnalyticsのコスト値は別系統です。Analyticsのコスト値は利用から通常4時間以内(最大24時間)に反映され、30日間は後から改訂されます。公式の手順も、順位付けにAnalytics、比率の計算にeffectiveの値を使う分担です。

候補が決まったら、POST /v1/organizations/spend_limitsで上限を上げる、保留中の申請があれば承認する、本人に連絡する、のいずれかに進みます。

週次の急増を拾う

user_cost_reportにbucket_width=1dを付けると、メンバーごとに日別の行が返ります。直近7日と、その前の7日の合計をactor.user_idごとに比べ、倍率が一定を超えたメンバーを候補にします。直近の日のコストは暫定値で、後から上方修正されることがあります。繰り返し比較するときは、返ってきたdata_refreshed_at以前の値をending_atに指定します。

インシデント対応中だけ上限を上げ下げする

インシデントの対応者に作業の余裕を持たせるため、開始時に上限を上げ、終了時に戻す運用も組めます。上げるかどうかは、インシデント管理システムの状態(進行中のインシデントIDに、そのメンバーが割り当てられているか)で判定します。

まとめ

書き込みをAPIに寄せるのは個人単位の上書きと増額申請の処理までで、シートティア・グループ・組織の既定値は画面で決めるのが運用の分担です。