部門別・利用者別のチャージバックを Claude の利用に載せるとき、旧 Usage and Cost API の description 文字列に頼った集計は、新規の組み込みでは推奨されなくなりました。公式ドキュメントは、新規連携には Usage and Cost Analytics API を使うよう案内しています。2026年10月29日に beta として公開されたこの API は、データの形と鮮度が旧 API と異なるため、単純な置き換えでは配賦基盤が壊れます。この記事は、大企業の基盤チームが移行時に決めるべき設計点を整理します。
Usage and Cost Analytics API は旧 API と何が違うのか
新 API は
/v1/organizations/analytics/usageと/costの2本で、actor・user_profile_id 等の構造化された次元で集計します。リリースは2026年10月29日です。
旧 API は /v1/organizations/usage_report/messages と /v1/organizations/cost_report で、現在は legacy 扱いですがサポートは続きます。新 API の主な差分は次のとおりです。
- beta ヘッダー: すべてのリクエストに
anthropic-beta: analytics-usage-cost-2026-08-24が必要です。SDK とantCLI は自動で付与します。 - 行の形: 旧 API は空のバケットを含む時間バケットの配列を返します。新 API は
order_byで並ぶ行の配列で、各行にstarting_at・ending_at・group・usage(cost ではcost)を持ち、利用のない組み合わせは行になりません。 - 次元:
group_by[]は最大5次元です。descriptionはなくなり、model・cost_type・token_type・service_tier・inference_geo・speedなどの構造化された次元に置き換わります。 - アカウント系:
account_ids[]とservice_account_ids[]はactor_ids[]に、group_by[]=account_idはgroup_by[]=actorまたはactor_typeに変わります。 - 組織の対応範囲: Claude Console と Claude Enterprise の両方で、同じエンドポイントとパラメータが使えます。
配賦キーは actor・workspace・user_profile_id のどれにすべきか
配賦キーは「誰の費用か」で選びます。社内利用者は actor、システム単位は workspace_id、自社顧客単位は user_profile_id が候補です。
actor は、リクエストの帰属先(ユーザー、サービスアカウント、フェデレーションされたクラウド ID、それらが無い場合は API キー自体)を表します。個人キーやサービスアカウントキーは紐づく ID として記録され、api_key_id にはキーが入ります。レガシーなワークスペースキーは ID に紐づかないため、キーが actor と api_key_id の両方に出ます。
運用上の判断基準は3つです。
- 社内の利用者別配賦は
group_by[]=actorを使う。Claude Code のサインイン時に作られるキーは Claude Code ワークスペースにあり、利用はそのメンバーに帰属する - 自社サービスの顧客別配賦は、リクエストに付けた User Profiles の ID を
user_profile_idで集計する。詳細はエンドユーザー帰属と enforcement の設計で扱った api_key_ids[]とactor_ids[]は別の問いに答える。前者はキーが認証した全リクエスト、後者はそのキー自身に帰属するリクエストだけを返す
4時間の遅延と値の改訂をどう吸収するか
データは通常4時間以内、最大24時間で反映されます。月次の確定値は、月末から約7日後まで改訂される可能性があります。
旧 API は通常5分以内に反映されましたが、新 API は通常4時間以内、最大24時間です。リアルタイムの予算ガードには使えません。リアルタイム側はリクエスト時点のトークン数や OpenTelemetry のトレースで補い、本 API は日次の突合と月次の確定に使う二層構成が現実的です。
設計上の要点は次のとおりです。
- 全レスポンスの
data_refreshed_atを保存し、その時刻より後の利用は欠落または部分値として扱う - 再取得の結果を安定させたいときは、すでに観測した
data_refreshed_at以前にending_atを置く - 確定値は、月末から7日以上経った月だけを対象にする。例えば10月1日の値は11月7日ごろまで変わりうる
- 1リクエストの範囲は最大31日、
starting_atは2026年1月1日以降かつ直近365日以内。1mバケットは1リクエスト24時間まで - コストの
amountは割引後・クレジット適用前、list_amountは定価で、6桁小数のセント単位の文字列。Priority Tier の約定内リクエストはトークン費用が0になり、約定料金はデータに含まれない
収集サービスの認証はどう固めるべきか
収集サービスには専用キーを発行して期限を設定するか、Workload Identity Federation で短命トークンを使います。長期キーは極力持たせません。
公式は、Admin API キーで呼ぶ場合に、収集サービス専用のキーをシークレットマネージャーに置き、定期的にローテーションし、作成時に有効期限を設定することを求めています。可能なら org:admin スコープの Workload Identity Federation ルールを使い、短命トークンで呼び出す構成が推奨されます。Claude Enterprise 組織では、read:analytics スコープのキーを primary owner が claude.ai で作成します。
移行の手順は、(1) 新 API を旧 API と並行稼働させ、同じ期間・同じ次元で合計を突合する、(2) description 依存のダッシュボードを構造化次元に書き換える、(3) 取得ジョブを日次バッチと月次確定に分ける、(4) 旧 API を止める、の順です。Claude Platform on AWS では両エンドポイントが使えますが、リージョンごとのエンドポイントを呼ぶ必要があり、Google Cloud の Anthropic managed では usageAnalytics.list などの IAM 権限が要ります。
大規模な配賦基盤の設計や、基盤チームの運用体制づくりは Kuu の RDE で相談できます。
参考
- Usage and Cost Analytics API - Claude Platform Docs
- Usage and Cost API(legacy) - Claude Platform Docs
- Release notes - Claude Platform Docs
まとめ
新 API への移行は、エンドポイントの差し替えではなく、次元・鮮度・認証の3点を作り直す作業です。description 依存を捨てて actor と構造化次元で配賦し、4時間の遅延を前提に日次突合と月次確定の二層で運用し、収集サービスの認証は短命トークンに寄せてください。Claude の利用統制と FinOps 基盤の設計は、Kuu 株式会社の RDE からご相談ください。
