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

> 2026年10月29日公開のUsage and Cost Analytics APIは、actor別集計と最大4時間の遅延を前提に設計します。旧APIとの差分と配賦基盤の作り方を整理します。

- Canonical: https://kuucorp.com/blog/claude-usage-cost-analytics-api-migration-attribution-design/
- Date: 2026-10-30
- Last modified: 2026-10-30
- Publisher: Kuu株式会社 (https://kuucorp.com)

---
部門別・利用者別のチャージバックを 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 の設計](/blog/claude-user-profiles-end-customer-attribution-enforcement-design/)で扱った
3. `api_key_ids[]` と `actor_ids[]` は別の問いに答える。前者はキーが認証した全リクエスト、後者はそのキー自身に帰属するリクエストだけを返す

## 4時間の遅延と値の改訂をどう吸収するか

> データは通常4時間以内、最大24時間で反映されます。月次の確定値は、月末から約7日後まで改訂される可能性があります。

旧 API は通常5分以内に反映されましたが、新 API は通常4時間以内、最大24時間です。リアルタイムの予算ガードには使えません。リアルタイム側はリクエスト時点のトークン数や [OpenTelemetry のトレース](/blog/claude-api-opentelemetry-export-destination-governance-design/)で補い、本 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](https://kuucorp.com/services/rde/) で相談できます。

## 参考

- [Usage and Cost Analytics API - Claude Platform Docs](https://platform.claude.com/docs/en/manage-claude/usage-cost-analytics-api)
- [Usage and Cost API（legacy） - Claude Platform Docs](https://platform.claude.com/docs/en/manage-claude/usage-cost-api)
- [Release notes - Claude Platform Docs](https://platform.claude.com/docs/en/release-notes/overview)

## まとめ

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