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

Claudeの使用量はどこで見るか

「Claude usage」で探しているものは、利用形態によって見る場所が違います。プログラムから取れるのは、API組織の利用量とコストです。

Claude Codeの/usageが出すドル額は、トークン量から標準単価で計算した推定値です。請求の根拠にはならず、請求額はConsoleのUsageページで確認します。サブスクのプラン利用内訳(直近24時間・7日)は、そのマシンのセッション履歴から集計されるため、ほかの端末やclaude.aiでの利用は含みません。サブスクの上限を超えて使う追加分の管理は、/usage-creditsコマンドから開く画面で行います。Team・Enterpriseの利用量の見方は、Team/Enterpriseの利用状況分析ダッシュボードにまとまっています。

まず確認したいのは自分の組織がどのAPIの対象か

Usage APIとCost APIは、組織のAPI利用状況をプログラムから取得するAdmin APIのエンドポイントです。Consoleの「Usage」「Cost」ページと似たデータを、時間粒度・モデル・ワークスペースで絞り込みながら取り出せます。用途は、内部の使用量記録とAnthropicの請求の突き合わせ、プロンプトキャッシュの効果測定、自社ダッシュボードへの組み込みなどです。レート制限の余力を見ながらキャッシュを調整したいときは、設定値そのものを組織・ワークスペースのレート制限を確認するRate Limits APIで確認します。日本語コンテンツの費用感を先に見積もる場合はToken Count APIで日本語コストを事前に見積もる方法が参考になります。

最初の分かれ道は、組織のタイプです。同じ「Anthropicの管理者」でも、使うAPIも鍵も変わります。

claude.ai側の管理画面の使用状況は冒頭の表のとおり別の画面にあり、ここではプログラム経由の取得を扱います。

401や403で止まるときのAdminキーと資格情報

呼び出せる資格情報は3種類です。Adminキー、org:adminスコープ付きのOAuthトークン、そしてワークスペースに紐づかない個人・サービスアカウントキーです。ワークスペースキーでは呼べません。普段のアプリ開発で使うキーを流用すると、権限不足で弾かれます。

Consoleの場合、Adminキーを作れるのは組織のadminロールを持つメンバーだけです。作成画面は「Claude Console > Settings > Admin keys」にあります。「Create key」で名前と有効期限(key expiration)を決めると、秘密値が1回だけ表示されます。後から見直せないので、シークレット管理ツールへそのまま保存します。

Consoleのキーにはスコープを選ぶ画面がありません。作ったキーは、Adminキーを受け付けるすべてのエンドポイントに対して全権を持ちます。Usage/Cost APIを読むだけの用途でも、渡す相手や置き場所は慎重に決める必要があります。

また、個人アカウントではAdmin API自体が使えません。使うには「Console → Settings → Organization」で組織を設定します。ConsoleとEnterpriseの両方を持つ会社では、鍵は組織ごとに別々に作ります。ある組織のキーで別の組織は管理できません。

二つのAPIは何を返し、どこで食い違うのか

Usage APIは/v1/organizations/usage_report/messagesで、モデル・ワークスペース・サービスティア別のトークン消費を返します。Cost APIは/v1/organizations/cost_reportで、USD建てのコスト内訳をサービスレベルで返します。

合計が食い違う原因は、この対応が裏返しになっていることです。Cost APIでは、コード実行の費用がdescriptionにCode Execution Usageとして現れます。両方の合計が合わなくても、どちらかが壊れているとは限りません。

直近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種類で、1回に取れるバケット数には既定と上限があります。

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ヘッダーが必須で、speeds[]フィルタも同じです。もう1つはデータレジデンシーのinference_geoで、global・us・not_availableを返します。2026年2月より前(Opus 4.6・Sonnet 4.6より前)のモデルはこのパラメータに未対応で、常にnot_availableが返ります。

400エラーになる指定と、実装で報告されているつまずき

公式ページは正しいリクエストの形を示しますが、エラーになる指定の境界までは書いていません。GitHubで公開されている不具合報告から、実際に踏まれた例を3つ拾います。いずれも各リポジトリで報告されている内容で、Anthropic側の仕様として確認できた部分と、報告者の見立てに留まる部分を分けて書きます。

group_by[]は5個までです。PostHogのAnthropic連携で、usage_reportの同期が毎回400で失敗した報告があります(PostHog #72556)。コネクタがaccount_id・api_key_id・service_account_id・workspace_id・model・service_tier・context_window・inference_geoの8個を同時に指定していました。報告者が手元で同じ要求を再現すると、Cannot specify more than 5 group_by[] dimensions.というエラーが返ったとあります。集計軸を増やしたいときは、軸の組み合わせを変えて複数回に分けます。

Cost APIは1日に満たない範囲を渡すと弾かれたという報告があります。別のデータ連携では、bucket_width=1dのcost_reportに00:00:00Zから23:59:59Zの範囲を渡すと、Invalid date range: ending date must be after starting dateの400が返り、取り込みが0行になったとされています(insight #1901)。同じ範囲でもUsage APIは通ったとの記述です。ここは1つのissueと追加の再現コメントに基づく報告で、公式ページに日次境界の記述はありません。ただ、日次の範囲は翌日0時をending_atにする書き方が無難だと読めます。

セント単位の端数は、行ごとに切り捨てない方が合います。Cost APIはセント単位の10進数文字列を返します。group_by[]=descriptionで行が増えると、各行の端数を個別に切り捨ててから足すと、合計が過少になるおそれがあります。あるトークン追跡アプリの課題では、端数のまま合算して最後に1回だけ丸める修正が検討されていました(token-tracker #45)。最後の変換を切り捨てにするか四捨五入にするかは、その課題でも未決のままでした。

Cost APIでUSDの内訳を日次で取る

ワークスペースとdescriptionで束ねる呼び出しは次のとおりです。

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が解析済みで含まれます。Priority Tierの金額を追いたいときは、Usage APIのservice_tierでpriorityを絞り込み、トークン量を代理指標にします。

取得が空に見えるときの3つの理由

has_moreがtrueの間は、next_pageの値を次のリクエストのpageへそのまま渡します。両エンドポイントともカーソル方式で、limitでバケット数を指定できます。falseになるまで繰り返さないと、期間の後半が抜けます。

データは、API呼び出しの完了から通常5分以内に取得できます。遅れが長引くこともあるので、直前の利用が出ないからといって失敗とは限りません。ポーリングは持続的な利用で1分に1回が上限の目安です。ページ取得のような短時間の連続呼び出しなら、それより頻繁でも構いません。ダッシュボードにはキャッシュを挟みます。

集計結果のnullにも意味があります。デフォルトワークスペースの利用は、workspace_idがnullで返ります。プレイグラウンド(旧Workbenchを含む)の利用はAPIキーに紐づかないため、api_key_idでグループ化してもnullのままです。nullを「データ無し」と読むと、実際に計上されている利用を見落とします。

自前で作る前に、既存の連携で足りるか

Usage/Cost APIでダッシュボードを内製する前に、可観測性プラットフォームの連携で足りないかを確認します。コード無しでClaude APIの利用量とコストを見られる統合が、公式にまとまっています。

CloudZeroは、コストの予測まで含めたクラウド全体の管理です。TempoはJiraの作業項目ごとに利用量とコストを紐づけます。DatadogはLLM可観測性で、自動トレーシングが付きます。Grafana Cloudはエージェントレスの連携で、ダッシュボードとアラートが最初から用意されています。HarnessはクラウドとAIコストのFinOps、HoneycombはOpenTelemetry経由の詳細なクエリ、VantageはLLMのコストと利用状況に特化したFinOpsです。

すでに社内でどれかを使っているなら、既存の連携先へ繋ぐ方が実装コストは低く済みます。既存の基盤が無く、集計軸を自社の業務に合わせたい場合に、この記事の直接呼び出しが向きます。

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

Usage/Cost APIはAPIキー単位の集計が基本です。Claude Codeを組織で使い、「誰がいくら使ったか」を人単位で見たい場合は、Claude Code Analytics API(/v1/organizations/usage_report/claude_code)が向いています。キーを細かく分けて集計する方法の性能上の制約を避けられる、というのが公式の説明です。

形はUsage APIと違います。starting_atはUTCの日付(YYYY-MM-DD)で、その1日分だけを返します。1件が「1人×1日」の記録で、実行したのがメールアドレスを持つユーザーか、APIキーかをactorで区別します。limitの既定は20、最大は1,000です。ページ送りはpageにnext_pageの値を渡すカーソル方式です。集計の切り口には、契約の種類を示すcustomer_type(apiかsubscription)とterminal_typeがあります。

返る値は、セッション数、追加・削除した行数、Claude Codeによるコミットとプルリクエストの数、Edit・Write系ツールの承認と拒否の数です。モデルごとのトークンと推定コスト(セント単位のUSD)も付きます。データの遅れは最大1時間とされ、Usage APIの目安である5分より長めです。推定コストは請求額そのものではない点に注意が要ります。

Claude Enterpriseの組織ではClaude Codeの利用がEnterprise Analytics APIの側に出ます。AWS上のClaude PlatformではClaude Code Analytics APIも未対応で、Consoleの「Usage」ページを見ます。キー横断のAPI利用をざっと見たいだけなら、Usage APIのトークン消費をコストの代理指標にする手もあります。

部門やプロジェクト単位で切り分けたいときは、Claudeのワークスペースの仕組みを先に把握しておくと、group_by[]=workspace_idの集計の読み方が決まります。Claude Enterprise組織でメンバーごとの支出上限を設定するのはSpend Limits APIで、Console組織では使えません。Usage/Cost APIは「見る」ためのAPI、Spend Limits APIはEnterpriseで「止める」ためのAPIです。

月次の突き合わせとキャッシュ測定の組み立て方

Cost APIから月次のコストをCSVに出し、社内のコスト配賦システムへ流し込めば、部門やプロダクトごとのチャージバックが組めます。予算超過のアラートなら、Usage APIの1h粒度で定期的に取り、しきい値を超えた時点で通知する構成が考えられます。プロンプトキャッシュの効果も同じデータで測れます。キャッシュ導入の前後で、キャッシュ済み入力とキャッシュ作成のトークン量を比べます。

細かい粒度を常時ポーリングすると、バケット数の上限とポーリング頻度の両方に近づきます。そこで、粗く取ってから絞り込む手順にします。

まとめ

請求と数字が合わないときは、まずPriority Tierとコード実行がどちらのAPIに載るかを疑います。壊れているのではなく、集計の対象が違うだけという場合が多いはずです。人単位のClaude Codeコストだけは、別のClaude Code Analytics APIで取ります。