約 4 分で読めます

Usage and Cost Analytics API移行の配賦設計

部門別・利用者別のチャージバックを 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 と ant CLI は自動で付与します。
  • 行の形: 旧 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つです。

  1. 社内の利用者別配賦は group_by[]=actor を使う。Claude Code のサインイン時に作られるキーは Claude Code ワークスペースにあり、利用はそのメンバーに帰属する
  2. 自社サービスの顧客別配賦は、リクエストに付けた User Profiles の ID を user_profile_id で集計する。詳細はエンドユーザー帰属と enforcement の設計で扱った
  3. 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 で相談できます。

参考

まとめ

新 API への移行は、エンドポイントの差し替えではなく、次元・鮮度・認証の3点を作り直す作業です。description 依存を捨てて actor と構造化次元で配賦し、4時間の遅延を前提に日次突合と月次確定の二層で運用し、収集サービスの認証は短命トークンに寄せてください。Claude の利用統制と FinOps 基盤の設計は、Kuu 株式会社の RDE からご相談ください。

関連記事

Linked billingでエンドカスタマーに課金する設計Claude on Google Cloud 2方式の選定設計:統制と機能差Claude API 2026-10-21移行のゲートウェイ設計Claude APIユーザープロファイルの設計と統制