Claude Usage APIとCost APIで利用量とコストを取得する

Usage APIとCost APIは何を返すのか

Usage APIとCost APIは、組織のAPI利用状況をプログラムから取得するための2本のAdmin APIエンドポイントです。Consoleの「Usage」「Cost」ページと同じデータを、時間粒度・モデル・ワークスペースなどで絞り込みながら取得できます。用途は明確です。内部の使用量記録とAnthropicの請求を突き合わせる、レート制限の余力を見ながらプロンプトキャッシュの効果を測る、自社のダッシュボードに組み込む。いずれもConsole画面の手動確認では追いつきません。

Usage APIは/v1/organizations/usage_report/messagesで、モデル・ワークスペース・サービスティア別のトークン消費を返します。Cost APIは/v1/organizations/cost_reportで、USD建てのコスト内訳をサービスレベルで返します。両者は別のエンドポイントで、返す単位も粒度も違います。混同するとコスト集計とトークン集計が食い違う原因になります。

claude.ai側の管理画面から使用状況を見る場合の操作はTeam/Enterpriseの利用状況分析ダッシュボードで扱っており、本記事はそれとは別物のプログラム経由の取得方法です。利用にはAdmin API資格情報が必須です。Admin APIキー(sk-ant-admin01-で始まる)、org:adminスコープ付きのOAuthトークン、またはワークスペースに紐づかない個人・サービスアカウントキーのいずれかが要ります。ワークスペースキーではアクセスできません。個人アカウントでは組織自体を作れないため、これらのAPIはそもそも使えません。

Usage APIでトークン消費を取得する手順

直近7日間の日次利用量を取得する最小の呼び出しです。

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

bucket_widthは1m(分)・1h(時)・1d(日)の3種類で、取得できる件数には既定と上限があります。

group_by[]でモデル・ワークスペース・APIキー・サービスティア・データレジデンシー・コンテキストウィンドウ帯ごとに集計できます。長コンテキストは課金レートが変わるため、context_window[]=0-200kのようにフィルタ値を指定して集計できる点も押さえておく必要があります。APIキーIDやワークスペースIDが分からない場合は、それぞれList API KeysエンドポイントとList Workspacesエンドポイント、またはConsole画面から調べられます。

トークン以外にも押さえておくべき集計軸が2つあります。1つはfast mode(研究プレビュー)の利用状況で、speedディメンションでstandardとfastを区別できますが、fast-mode-2026-02-01のbetaヘッダーが必須です。もう1つはデータレジデンシーで、inference_geoディメンションがglobal・us・not_availableを返します。2026年2月より前(Opus 4.6・Sonnet 4.6より前)にリリースされたモデルはこのパラメータに未対応で、常にnot_availableが返ります。

Cost APIでUSDのコスト内訳を取得する手順

Cost APIは日次粒度(1d)のみで、USD建てのコストをセント単位の10進数文字列で返します。

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

group_by[]=descriptionを指定すると、レスポンスの各行にmodelやinference_geoが解析済みで含まれます。コスト対象はトークン利用に加え、Web検索やコード実行などサーバー側ツールの費用も含みます。Priority Tierだけは例外で、課金モデルが異なるためCost APIには含まれません。Priority Tierのコストを追いたい場合は、Usage APIのservice_tierでpriorityを絞り込んでトークン量を代理指標として見ます。同じ理由で、コード実行の費用はCost APIのdescriptionにCode Execution Usageとして現れる一方、Usage APIの集計には含まれません。目的によって見るべきAPIが変わる点に注意が要ります。

ページネーションと更新頻度の落とし穴

両エンドポイントともlimitとオフセット無しのカーソル方式でページングします。レスポンスのhas_moreがtrueならnext_pageの値を次のリクエストのpageパラメータへそのまま渡し、falseになるまで繰り返します。

データの反映は速く、API呼び出しの完了から通常5分以内に取得できるようになりますが、遅延が長引くこともあります。ポーリングは1分に1回までが推奨頻度で、ページ取得のような短時間の連続呼び出しはより頻繁でも許容されます。ダッシュボード用途では、この推奨頻度を超えないようレスポンスをキャッシュする設計が要ります。

レスポンスの構造や集計軸そのものはUsage APIとCost APIで共通する部分が多いため、片方を実装すればもう片方への横展開は容易です。見落としやすい挙動が2つあります。1つ目はデフォルトワークスペースの扱いで、workspace_idがnullとして返ります。2つ目はプレイグラウンド(旧Workbenchを含む)経由の利用で、APIキーに紐づかないためapi_key_idがnullになります。集計結果のnullを「データが無い」と早合点すると、実際には計上されている利用を見落とします。

自前実装の前にパートナー連携を検討する余地はあるか

Usage/Cost APIを直接叩いてダッシュボードを内製する前に、既存の可観測性プラットフォームとの連携で足りないかを確認する価値があります。CloudZero・Datadog・Grafana Cloud・Harness・Honeycomb・Vantageはいずれも、コード無しでClaude APIの利用量とコストを可視化する統合を公式に提供しています。

すでに社内でこれらのいずれかを使っているなら、Usage/Cost APIを直接叩く前に既存の連携先へ繋ぎ込む方が実装コストは低くなります。逆に既存の可観測性基盤が無く、集計軸を細かく自社の業務ロジックに合わせたい場合は、本記事の直接呼び出しが向いています。

Claude Codeの1人あたりコストはこのAPIで足りるか

Usage/Cost APIはAPIキー単位の集計が基本です。Claude Codeを組織で使っていて「誰がいくら使ったか」を人単位で見たい場合、APIキーが多いと処理が重くなり、実用的な粒度で出てきません。この用途にはClaude Code Analytics APIを使う方が、パフォーマンス上の制約なく人単位の推定コストと生産性指標を得られます。汎用的なAPI利用をキー横断で見たいだけなら、Usage APIのトークン消費をコストの代理指標として使う選択肢もあります。

組織のコストを部門やプロジェクト単位で切り分けたいケースでは、Claudeのワークスペースの仕組みを先に把握しておくと、group_by[]=workspace_idの集計がどう対応するかが読みやすくなります。ワークスペースごとに支出上限まで管理したいなら、Spend Limits APIが個人・グループ・組織の階層で上限を扱う別のAPIです。Usage/Cost APIは「見る」ためのAPI、Spend Limits APIは「止める」ためのAPIという役割分担になっています。

財務チームの突き合わせ作業にどう使うか

Usage/Cost APIの典型的な使われ方の1つが、社内記録とAnthropicの請求書を突き合わせる作業です。Cost APIから月次のコストをCSVに落とし込み、社内のコスト配賦システムへ流し込めば、部門やプロダクトごとのチャージバックが自動化できます。予算超過のアラートを組みたい場合も、Usage APIの1h粒度でポーリングし、しきい値を超えた時点で通知を出す構成が典型です。プロンプトキャッシュの効果測定にも同じデータが使えます。Usage APIのレスポンスは未キャッシュ入力・キャッシュ済み入力・キャッシュ作成・出力のトークンを分けて返すため、キャッシュ導入前後の差を数値で示せます。

これらの用途に共通するのは、Consoleの画面を毎回開いて手動で数字を拾う運用から、定期実行のジョブに置き換えるという発想です。Usage APIとCost APIはどちらもレスポンスがJSONで構造化されているため、BIツールへの取り込みや社内ダッシュボードへの組み込みも素直に行えます。実装の初期段階では、まずbucket_width=1dの粗い粒度で全体像を掴み、異常が見えた期間だけ1hや1mに絞り込んで原因を追う、という2段階のクエリ設計にしておくと、日々のポーリング量を抑えながら必要なときだけ細かい粒度を取りに行けます。

まとめ

Usage APIとCost APIは、Claude Console組織のAPI利用を時間粒度・モデル・ワークスペース単位で追うための2本立てのAdmin APIです。Claude Enterprise組織は別物のAnalytics APIを使う点、AWS上のClaude Platformではプログラム取得に対応していない点は、実装前に必ず確認しておく価値があります。ポーリングは1分に1回を目安にキャッシュを挟み、Priority Tierやコード実行のようにAPIをまたいで扱いが分かれる項目は、どちらの数字を見ているかを常に意識すると集計のズレを避けられます。