Usage and Cost Analytics APIへの移行 — 旧APIとの対応表と変更点

Usage and Cost Analytics APIは、組織のトークン使用量と費用を取得する新しいベータ版のAPIです。/v1/organizations/analytics/usage と /v1/organizations/analytics/cost の2本で、ConsoleとEnterpriseの両方の組織を同じ形で扱えます。

旧Usage and Cost APIは止まったわけではありません。ただし、パラメータ名もレスポンスの形も変わるので、既存のスクリプトはそのままでは動きません。この記事は、何がどう変わるかを対応表で押さえ、旧APIと同じ日次レポートを作り直すところまで進めます。

2026年10月29日に何が変わったか

プラットフォームのリリースノートによると、2026年10月29日にこのAPIがベータとして公開されました。同じ日に、次のAPIが「legacy(旧式)」の扱いになっています。

• Usage and Cost API(/v1/organizations/usage_report/messages と /v1/organizations/cost_report)
• Claude Enterprise Analytics APIの usage_report、cost_report、user_usage_report、user_cost_report

リリースノートは、これらが「引き続きサポートされる」とも書いています。廃止日は示されていません。つまり、今日から乗り換えを迫られる話ではなく、新しい機能が新APIにだけ載っていく移行期にあたります。

旧APIの使い方そのものはClaude Usage APIとCost APIで利用量とコストを取得するにあります。Enterprise側の三つのAPIの違いはClaude Analytics APIの使い分けで確認できます。

新APIの呼び方 — ヘッダーとエンドポイント

エンドポイントは2本です。

どちらにも anthropic-version と anthropic-beta: analytics-usage-cost-2026-08-24 が必要です。SDKと ant CLIは両方のヘッダーを自動で付け、続きのページも読み進めるので、limit はページサイズだけを決めます。

1週間分のトークン使用量を、モデルと日ごとに取る例です。

curl --globoff "https://api.anthropic.com/v1/organizations/analytics/usage?\
starting_at=2026-09-01T00:00:00Z&\
ending_at=2026-09-08T00:00:00Z&\
time_bucket_width=1d&\
group_by[]=model&\
limit=10" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: analytics-usage-cost-2026-08-24" \
  -H "x-api-key: $ANTHROPIC_API_KEY"

ConsoleならAdminキーか、org:admin スコープのOAuthトークンなど、Admin APIの資格情報で呼びます。個人アカウントではAdmin APIを使えないため、先にConsoleの組織設定が要ります。Enterpriseの組織は、Analytics APIを有効にしたあとにprimary ownerがclaude.aiで作る read:analytics スコープのキーを使います。

クラウド経由の利用にも対応しています。Claude Platform on AWSでは両エンドポイントが使え、認可はAWS IAMの ListAccountUsage と ListAccountCost で行います。Claude Models on Google Cloud(Anthropic managed)でも両方使え、/usage には usageAnalytics.list のIAM権限が要ります。

返ってくるデータの形はこう変わる

旧APIの data は、時間バケットの配列でした。空のバケットも含み、各バケットの results に、ディメンション(モデルなど)とメトリクスが並びます。

新APIの data は行の配列です。各行は3つの部分でできています。

使用量・費用のある組み合わせだけが行になり、空のバケットは出ません。並びは order_by の指標の大きい順が既定です。group_by[] は5つまで、フィルターの値は1つにつき100個までです。

時系列として使うなら、time_bucket_width と order_by=time を付けます。すると、新しいバケットから順に返ります。古い順にしたいときは order=asc を足します。

旧Usage and Cost APIからの対応表

Console組織で旧Usage and Cost APIを使っている場合の変更点です。Adminキー、anthropic-version ヘッダー、starting_at と ending_at、バケット幅の値(1m・1h・1d)、ブラケット表記、ページネーションの項目名、トークンと費用の項目名は引き継がれます。

そのほか、地味ですが影響の出やすい違いが4つあります。

• 存在しないAPIキーやワークスペースのIDを渡すと、旧APIはエラーを返しました。新APIは何にも一致せず、空の結果になります。models[] のスペルミスも同じです
• 地理指定やティアのない使用量は、旧APIでは inference_geo: "not_available"、service_tier: "standard" でした。新APIはどちらも null です。inference_geos[]=not_available というフィルターは、引き続き該当の行に一致します
• 費用の service_tier は、旧APIでは standard か batch でした。新APIは実際のティアが入ります
• amount はセント単位の文字列です。公式の例では "41280.000000" が412.80ドルにあたります

特に1つ目は、移行後に気づきにくい挙動です。IDを打ち間違えると、エラーではなく「使用量ゼロ」に見えます。

旧APIと同じ日次レポートを作り直す

旧APIの日次レポートを再現する手順は、公式ドキュメントに次のとおり書かれています。

1週間分のモデル別・日次の使用量で、前後を比べます。移行前はこうでした。

curl --globoff "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-09-01T00:00:00Z&\
ending_at=2026-09-08T00:00:00Z&\
group_by[]=model&\
bucket_width=1d" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_API_KEY"

移行後は、先に示した新APIの例から limit を1000に変えた形になります。

移行でつまずきやすい4つの制約

対応表に出てこない制約も、移行先で確認が必要です。

旧APIにあった期間の制限は、新APIでは厳しくなっています。31日より長い期間は、31日以内に区切って複数回呼びます。

鮮度の差は、アラート用途に響きます。使用量の急増を数分で検知していた仕組みは、新APIでは遅れが出ます。応答にある data_refreshed_at の時刻より後の使用量は、欠けているか途中の値です。

移行の確認は、締め終わった月で新旧の合計を突き合わせるのが手堅い方法です。月が変わってから約7日待てば、値の改訂も落ち着きます。Claude Codeに移行を任せる場合も、パラメータの書き換えだけを頼むのでなく、同じ期間の新旧の合計を並べて出させると、IDの打ち間違いによる「ゼロ行」を見逃しません。

Enterpriseのusage・cost系レポートからの移行

Claude Enterpriseの usage_report、cost_report、user_usage_report、user_cost_report も、新APIへの移行先が用意されています。これらはlegacyですが、引き続き使えます。

移行する利点として、公式ドキュメントは次の4点を挙げています。

• 各バケットの上位100グループではなく、すべてのグループが全バケットで得られる
• actor や actor_type を、他のディメンションと組み合わせてグループ化できる(使用量と費用の両方)
• 期間全体で任意の指標で順位づけするか、時間バケット順に並べられる
• Consoleの組織にも同じ連携を使い回せる

キー、日付の下限、365日・31日の制限、フィルター名、data_refreshed_at、組織単位のレート制限は引き継がれます。変わる点は次のとおりです。

ユーザー別の費用は、それぞれ別のエンドポイントでしたが、新APIではcostエンドポイント1本に集まります。月次のユーザー別コストに、プロダクトの内訳を足した例です。

curl --globoff "https://api.anthropic.com/v1/organizations/analytics/cost?\
starting_at=2026-09-01T00:00:00Z&\
ending_at=2026-10-01T00:00:00Z&\
group_by[]=actor&\
group_by[]=product&\
actor_types[]=user_actor&\
limit=100" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: analytics-usage-cost-2026-08-24" \
  -H "x-api-key: $ANTHROPIC_API_KEY"

actor_types[]=user_actor を外すと、サービスアカウントなどユーザー以外の行と、帰属先のない使用量を示す actor: null の行も返ります。

旧レポートの使い方は、ユーザー別コストを取得する方法とuser_usage_reportでユーザー別トークン使用量を取得する手順にあります。

Claude Codeのユーザー別コストはどう取るか

新APIでは、costエンドポイントに products[]=claude_code&group_by[]=actor を付けます。これでClaude Codeの利用者ごとの費用が出ます。

Consoleの組織なら、別の選択肢としてClaude Code Analytics APIもあります。こちらはユーザーごとのClaude Codeの活動と、推定の費用を報告します。

費用の内訳を分けて見る

costエンドポイントには、usageエンドポイントにないディメンションが2つあります。cost_type と token_type です。どちらも5つの上限には数えられません。

cost_type を付けると、費用の種類ごとに行が分かれます。token_type を付けると、トークン費用が種類ごとに分かれます。公式の例では、モデルごとに5つのトークン種別の行と、web_search、code_execution、session_usage の行が1つずつ返ります。

この2つを使うと、旧APIの description で文字列を見て切り分けていた処理を、構造化された値で置き換えられます。limit はこの2つには効かないため、1ページが limit 行より増えることがあります。

また cost には、割引後で、クレジット適用前の amount と、定価ベースの list_amount が入ります。2つの差は、割引の効果を測る目安になります。group_by[]=cost_type か token_type を使う場合、requests は全行で null です。

移行の判断材料

旧APIはサポートが続くので、動いている連携を急いで書き換える必要はありません。新APIへ移る理由が生じるのは、次のような場面です。

• 上位100グループの打ち切りで、費用の集計が合わなくなっている
• ユーザー別とモデル別など、actor を含む切り口を1リクエストで取りたい
• ConsoleとEnterpriseの両方の組織を、同じコードで扱いたい

逆に、数分単位の鮮度が必要な監視や、31日を超える期間を1回で取る処理は、新APIで条件が厳しくなります。新APIがベータである点も、本番の集計に載せるかどうかの判断に入れておきたい点です。