ホーム / チュートリアル / 使用量とコストのAPI

使用量とコストのAPI

Claude API エンジニアリング 9分で読めます

Claude API の利用量と請求額を、コンソールの画面ではなくプログラムから取得したい。組織全体のトークン消費をワークスペースごとに配賦したい。こうした要求に応えるのが Usage & Cost Admin API です。この記事では公式ドキュメントの内容を日本語で整理します。

概要

Usage & Cost Admin API は、組織の 過去の API 利用量と費用データにプログラムから細かくアクセスするための API です。取得できる情報は、Claude Console の Usage ページと Cost ページに表示されるものと同等です。

公式ドキュメントは、この API を使う目的として次の5つを挙げています。

Admin API キーが必要です

ここが最初の関門です。これらのエンドポイントには Admin API キーが必要で、通常の Claude API キーでは呼べません。 Admin API キーは sk-ant-admin01- で始まる別種のキーです。

加えて、Admin API は個人アカウントでは使えません。チームで使うには Console の Settings → Organization で組織を設定する必要があります。

どちらの API を使うのか

Anthropic は、組織が管理している Claude 製品によって2つの API を用意しています。ここを取り違えると、キーの種類から間違えることになります。

組織の種別使う APIキーの種類
Claude Console（Claude Platform）この記事で扱う Usage and Cost Admin APIAdmin API キー（sk-ant-admin01-...）
Claude Enterprise（claude.ai）Claude Enterprise Analytics API の費用・利用量エンドポイントAnalytics API キー

Claude Enterprise の親組織は Claude Console に現れず、Admin API キーを持ちません。そのため、これらの組織にとっては Analytics API キーが唯一の経路になります。

もう1つ注意点があります。AWS 上の Claude Platform では、この Usage / Cost API のエンドポイントは現在利用できません。 その場合は Claude Console の Usage ページと Cost ページで確認します。

基本概念

Usage API — トークン消費を追う

エンドポイントは /v1/organizations/usage_report/messages です。モデル別・ワークスペース別・サービスティア別の内訳つきで、組織全体のトークン消費を追えます。

押さえるべき概念は4つです。

トークン種別が分かれているのは、費用の内訳を理解するうえで重要です。プロンプトキャッシュを使っている場合、キャッシュ作成時と読み出し時で単価が違うため、まとめて「入力トークン」として数えると最適化の効果が見えません。

Cost API — 費用を追う

エンドポイントは /v1/organizations/cost_report です。サービス単位の費用内訳を USD で取得します。

Priority Tier の費用はこのエンドポイントに含まれません。 課金モデルが異なるためで、Priority Tier の利用は Usage 側のエンドポイントで追います。

時間粒度の上限

Usage API の粒度には、既定値と最大値が決められています。ここを知らないと「1分粒度で1か月ぶん取りたい」といった要求が通らない理由が分かりません。

粒度既定の上限最大の上限想定用途
1m60 バケット1,440 バケットリアルタイム監視
1h24 バケット168 バケット1日の傾向
1d7 バケット31 バケット週次・月次のレポート

最大値を見ると、1m なら24時間ぶん、1h なら7日ぶん、1d なら31日ぶんが1回で取れる範囲だと分かります。それより長い期間は、期間を分けて複数回呼ぶことになります。

使い方

最短の例

直近7日ぶんの日次利用量を取得します。

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-08T00:00:00Z&\
ending_at=2025-01-15T00:00:00Z&\
bucket_width=1d" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

連携（インテグレーション）を作る場合は、User-Agent ヘッダを設定することが推奨されています。利用パターンの把握に使われます。

User-Agent: YourApp/1.0.0 (https://yourapp.com)

モデル別の日次利用量

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

絞り込みを効かせた時間別の利用量

モデル・サービスティア・コンテキストウィンドウで絞り込む例です。

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-15T00:00:00Z&\
ending_at=2025-01-15T23:59:59Z&\
models[]=claude-opus-5&\
service_tiers[]=batch&\
context_window[]=0-200k&\
bucket_width=1h" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

API キー・ワークスペースで絞り込む

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-08T00:00:00Z&\
api_key_ids[]=apikey_01Rj2N8SVvo6BePZj99NhmiT&\
workspace_ids[]=wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ&\
bucket_width=1d" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

API キーの ID は List API Keys エンドポイントで、ワークスペースの ID は List Workspaces エンドポイント（または Claude Console）で確認できます。

データレジデンシー（inference_geo）

inference_geo の軸でグルーピング・絞り込みを行うと、地理的なルーティングが組織全体で意図どおりかを確認できます。有効な値は global、us、not_available の3つです。

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

注意点があります。2026年2月より前にリリースされたモデル（Claude Opus 4.6 と Claude Sonnet 4.6 より前）は inference_geo リクエストパラメータに対応していません。 それらの利用量レポートはこの軸で "not_available" を返します。逆に言えば、inference_geos[]=not_available を指定すると、そうした古いモデルの利用だけを取り出せます。

Fast mode（リサーチプレビュー）

speed の軸で、通常モードと fast mode の利用を分けて追えます。有効な値は standard と fast です。

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

speeds[] の絞り込みも speed のグルーピングも、fast-mode-2026-02-01 ベータヘッダが必要です。 付け忘れると使えません。

費用の取得

ワークスペースと description でグルーピングした費用レポートの例です。

curl "https://api.anthropic.com/v1/organizations/cost_report?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-31T00:00:00Z&\
group_by[]=workspace_id&\
group_by[]=description" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

ページネーション

どちらのエンドポイントも、大きなデータセットに対してページネーションに対応しています。手順は3段階です。

  1. 最初のリクエストを送る
  2. レスポンスの has_more が true なら、next_page の値を次のリクエストの page パラメータに渡す
  3. has_more が false になるまで繰り返す
# 1回目
curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-31T00:00:00Z&\
limit=7" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

# レスポンスに "has_more": true, "next_page": "page_xyz..." が含まれる

# 2回目
curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-31T00:00:00Z&\
limit=7&\
page=page_xyz..." \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

よくある質問

公式ドキュメントの FAQ から、実装時に効くものを挙げます。

パートナーの監視ツール

自前でコードを書かずに済ませたい場合、主要な可観測性プラットフォームが既製の連携を提供しています。ダッシュボード・アラート・分析が用意されています。

まとめ

この API を使い始めるときに、順番に確認すべき点を整理します。

  1. 組織の種別を確認する … Claude Console（Claude Platform）なら Admin API キー、Claude Enterprise なら Analytics API キーです。ここを取り違えると認証で止まります
  2. Admin API キーを用意する … 通常の API キーでは呼べません。個人アカウントでは使えません
  3. 取りたい粒度と期間を決める … 1m は最大24時間ぶん、1h は最大7日ぶん、1d は最大31日ぶんです。これを超える期間は分割して呼びます
  4. 利用量と費用を使い分ける … コード実行は Cost 側にしか出ず、Priority Tier は Usage 側にしか出ません。両方を突き合わせないと全体像になりません
  5. ポーリングは1分に1回まで … データの反映も通常5分以内なので、それより短い間隔で叩いても新しい値は返りません

プロンプトキャッシュやバッチ処理でコストを下げたい場合は、まずこの API で現状のトークン内訳（キャッシュ作成・キャッシュ読み出し・非キャッシュ入力・出力）を測るところから始めるのが確実です。推測ではなく実測から入れます。

本記事は Anthropic の公式ドキュメント「Usage and Cost API」に基づく非公式の日本語解説です。仕様は変更される場合があります。最新の内容は公式ドキュメントをご確認ください。

関連チュートリアル / 次に読む

コストを効果的に管理する Claude APIのプロンプトキャッシュで入力コストを削減する Message Batches でリクエストをまとめて処理する Claude呼び出し前にトークン数を数える OpenTelemetry で Claude Code を監視する
← チュートリアル一覧へ戻る カテゴリで探す