Claude API advisorツールの課金構造 — usage.iterationsの読み方

advisorの呼び出しはexecutorとは別料金の推論として課金される

Claude APIのadvisorツールは、executorモデルとは別に、advisorモデルへのサブ推論を1回ごとに走らせます。このサブ推論はadvisorに指定したモデルのレートで独立に課金され、executorのモデル料金には合算されません。executorがSonnet 5でadvisorがOpus 5なら、Sonnet 5の単価で課金される部分とOpus 5の単価で課金される部分が別々に発生する、という構造です。

この内訳はレスポンスのusageオブジェクト内、usage.iterationsという配列にそのまま記録されます。

{
  "usage": {
    "input_tokens": 1760,
    "cache_read_input_tokens": 412,
    "cache_creation_input_tokens": 0,
    "output_tokens": 531,
    "iterations": [
      { "type": "message", "input_tokens": 412, "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0, "output_tokens": 89 },
      { "type": "advisor_message", "model": "claude-opus-5", "input_tokens": 823, "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0, "output_tokens": 1612 },
      { "type": "message", "input_tokens": 1348, "cache_read_input_tokens": 412, "cache_creation_input_tokens": 0, "output_tokens": 442 }
    ]
  }
}

iterationsの各要素はtypeで2種類に分かれます。"message"はexecutor自身のターンで、executorモデルのレートで課金されます。"advisor_message"はadvisor呼び出しで、modelフィールドに使われたadvisorモデル名が入り、そのモデルのレートで課金されます。

トップレベルusageにadvisorの分が入らない理由

上の例でトップレベルのinput_tokens(1760)とoutput_tokens(531)は、2つの"message"イテレーションだけを合計した値です(412+1348=1760、89+442=531)。中間の"advisor_message"イテレーション(input 823・output 1612)はこの合計に含まれていません。

公式ドキュメントは、これを「executor分とadvisor分は異なるレートで課金されるため」と説明しています。もし両方を単純合算すると、合計トークン数だけを見た金額試算が実際の請求額とずれてしまいます。executorのコストを追いたいならトップレベルのusage、advisorを含めた総費用を追いたいならusage.iterationsを自前で集計する、という役割分担です。

executorが複数ターンにわたって会話を継続する構成では、後続のイテレーションのinput_tokensにそれ以前のイテレーションの出力が積み上がっていくため、トップレベルのinput_tokensは単一のプロンプトサイズより大きくなります。上の例でも2つ目の"message"イテレーションのinput_tokens(1348)には、直前までの会話とadvisorの助言が反映された文脈が含まれています。コスト集計用のログを組むなら、トップレベルの合計値だけでなくusage.iterationsを1件ずつ見る実装にしておいたほうが、あとから「advisor分だけ抜き出す」といった分析がしやすくなります。

実例のJSONから実際の費用を計算する

公式のJSON例にexecutorモデルの記載はないため、ここではexecutorをSonnet 5と仮定して、Claude APIの標準料金(Sonnet 5: 入力$2/出力$10 per MTok、Opus 5: 入力$5/出力$25 per MTok)に当てはめます。3つ目の"message"イテレーションが持つcache_read_input_tokens: 412は、トップレベルのinput_tokensに含まれた通常入力ではなく別枠のキャッシュ読み取りなので、試算表でも行を分けます。

この試算では、リクエスト全体の費用のうち約83%をadvisorのサブ推論が占めています。advisorの出力トークン(1,612)がexecutorの出力トークン(531)より大きいうえ、Opus 5の出力単価がSonnet 5の2.5倍あるためです。ただしこの比率だけを見ると、advisorパターンそのものが高コストであるかのように見えてしまいます。実際のコスト削減効果は、advisorの出力量そのものではなく「最終出力を低レートのexecutorが生成する」構成から来ます。公式ドキュメントによれば、advisorの出力は典型的には本文400〜700トークン、思考ブロックを含めても1,400〜1,800トークン程度で収まり、この規模に収まっている限り、advisorを使わずexecutor(より高レートのモデルであることが多い)だけで同等の品質を出す構成と比べて総費用は下がるという設計です。executorだけの単価感覚でコストを見積もると、advisor呼び出しが増えるほど実際の請求額との乖離が大きくなります。advisorの出力トークン数を抑える具体策はClaude API advisorツールのコスト削減にまとめています。

トップレベルmax_tokensとtask budgetは及ばない

executorのリクエストに設定するmax_tokensは、あくまでexecutor自身の出力に対する上限です。advisorのサブ推論の出力トークン数を制限する効果はありません。advisorの出力を制限したい場合は、ツール定義側のmax_tokensを別途設定する必要があります(設定方法と実測の削減率は前段のリンク先にまとめています)。同様に、executorに適用したtask budgetも、advisorのトークン消費には影響しません。executorの予算管理とadvisorのコスト管理は別の設定として扱う必要があります。

advisor側のキャッシュを有効にすると請求はどう変わるか

ツール定義にcachingを設定すると、advisor自身のトランスクリプト(会話全体の引用コンテキスト)を会話内でキャッシュできます。仕組みはプロンプトキャッシュと同じで、N回目のadvisor呼び出しのプロンプトは(N-1)回目のプロンプトに1セグメント追記しただけの形になるため、接頭辞が安定して再利用できます。cachingを有効にすると、advisor呼び出しのたびにキャッシュへの書き込みが発生し、次の呼び出しはそこまでの内容をキャッシュ読み取りとして扱い、差分だけを新規入力として支払います。この挙動はusage.iterationsにもそのまま現れ、2回目以降の"advisor_message"イテレーションでcache_read_input_tokensが0でない値になります。プロンプトキャッシュ全般の仕組みはAnthropic APIのPrompt Cachingを理解するで扱っています。

キャッシュ書き込みのコストは、読み取りで節約できる分より高くつくことがあります。会話内でのadvisor呼び出しが2回以下なら、書き込みコストが読み取りの節約分を上回るため、cachingは有効にしないほうが安く済みます。損益分岐点はおおよそ3回で、それ以上呼ぶ長いエージェントループでは有効化するほど得になります。設定は会話の最初から最後まで一貫させる必要があり、途中でオン・オフを切り替えるとキャッシュミスが発生してその回だけ余計な費用がかかります。

もう1点、思考ブロックの保持設定(clear_thinking)でkeepの値を"all"以外にしていると、advisorに渡すトランスクリプトの内容がターンごとに変わり、advisor側のキャッシュが毎回ミスします。これは助言の質そのものには影響しませんが、コストだけが余計にかかる状態です。拡張思考を有効にしていてclear_thinkingを明示していない場合、既定値はkeep: {type: "thinking_turns", value: 1}(思考ターンを1つしか保持しない設定)になります。この既定値が適用されるのはOpus 4.5より前のOpusモデル・Sonnet 4.6より前のSonnetモデル、およびHaiku 4.5を含む全Haikuモデルで、Opus 4.5以降・Sonnet 4.6以降では既定で全ターンを保持するため、この挙動にはなりません。旧世代のOpus/Sonnetやいずれかの世代のHaikuをexecutorに使っていて、かつclear_thinkingを明示していない場合は、意図せずこのコスト劣化を踏んでいることがあります。advisorのキャッシュを効かせたい場合はkeep: "all"を明示しておくと安全です。

Priority Tierはモデルごとに個別適用される

Priority Tier(優先処理の容量コミットメント)を契約している場合も、executorモデルへのコミットメントはadvisorモデルには自動的に及びません。advisor呼び出しがPriority Tierで処理されるのは、組織がadvisorに指定したモデル自体についても別途コミットメントを持っている場合だけです。executorだけPriority Tierを契約し、advisorには契約していない構成では、advisor呼び出しは標準ティアで処理されます。

なおPriority Tierの容量コミットメントは新規購入が終了しており、既存のコミットメントを持つ組織のみ契約期間内で利用を継続できます。新規に容量保証を検討する場合は、公式サポート窓口への問い合わせが必要です。

advisorのレート制限も、advisorに指定したモデルへの直接呼び出しと同じ枠を共有します。advisor側がレート制限に達すると、リクエスト全体は失敗せずadvisor_tool_resultの中にtoo_many_requestsエラーとして現れます。一方、executor自身がレート制限を受けた場合はツール結果の中ではなく、リクエスト全体がHTTP 429で失敗します。この違いは、コスト管理の実装でリトライ戦略を分けるときに影響します。

Priority Tierの容量は、input・outputそれぞれについてトークン種別ごとに異なる倍率で消費されます。キャッシュ読み取りは1トークンあたり0.1トークン分、5分TTLのキャッシュ書き込みは1.25トークン分、1時間TTLのキャッシュ書き込みは2.0トークン分としてカウントされ、通常の入力トークンは等倍です。advisor呼び出しでキャッシュを有効化している場合、この倍率はadvisorモデル自身のPriority Tier容量に対して適用され、executor側の容量とは別枠で消費されます。executorとadvisorの両方でPriority Tierを契約している構成では、容量の消費ペースをモデルごとに別々に監視する必要があります。

コスト集計の実装方針

会話単位・組織単位でadvisorのコストを追跡したい場合、usage.iterationsをtypeで振り分けて自前集計するのが確実な方法です。"advisor_message"のイテレーションだけを取り出し、modelフィールドの値に応じたレートを掛ける処理を1か所に集約しておけば、advisorモデルを途中で切り替えても計算ロジックを変えずに済みます。

集計ロジックの骨格は、モデル名からレートを引く辞書を1つ持ち、iterationsを1件ずつ走査してtypeに応じて足し込むだけのシンプルな形で実装できます。

RATES = {
    "claude-sonnet-5": {"input": 2.0, "output": 10.0},
    "claude-opus-5": {"input": 5.0, "output": 25.0},
    "claude-opus-4-8": {"input": 5.0, "output": 25.0},
}
 
def calc_cost(usage, executor_model):
    total = 0.0
    for it in usage["iterations"]:
        model = it.get("model", executor_model)  # "message" 型は executor 自身のモデル
        rate = RATES[model]
        total += it["input_tokens"] / 1_000_000 * rate["input"]
        total += it["output_tokens"] / 1_000_000 * rate["output"]
    return total

"message"型のイテレーションにはmodelフィールドが無いため、executorのモデル名をリクエスト側から渡す必要があります。"advisor_message"型はmodelフィールドを自身で持つので、advisorを会話の途中で切り替えても、このロジックを変更せずに正しいレートを適用できます。

なお、ツール定義側のmax_usesは1リクエストあたりのadvisor呼び出し数の上限であり、会話全体を通じた上限ではありません。会話単位でadvisorのコストに予算を設けたい場合は、この集計ロジックでクライアント側の呼び出し回数をカウントし、上限に達した時点で次のリクエストのtoolsからadvisorを外す運用にします。履歴に残ったadvisor_tool_resultブロックを削る必要はありません。

最小構成の実装とツール定義の書き方は別記事にある

tools配列へのadvisor_20260301エントリの書き方や、executorとadvisorの組み合わせ制約そのものはClaude APIのadvisor toolを実装する最小構成にまとめています。advisor_tool_resultの中身が平文になるか暗号化されるかの分岐条件はClaude API advisorツールの結果が暗号化される条件で扱っており、本記事は料金とusage.iterationsの読み方に絞っています。

まとめ

advisorツールの料金は、executorとは別レートのサブ推論としてusage.iterations配列に個別記録されます。トップレベルのusageはexecutor分だけの合計で、advisor分を含めた総費用を知るにはiterationsをtypeで振り分けて自前集計する必要があります。実例のJSONを実際の単価に当てはめると、advisorの出力コストがリクエスト全体の大半を占めることがあり、トップレベルのmax_tokensやtask budgetはadvisorには及ばず、Priority Tierもモデルごとに独立して適用される点は、コスト設計の前提として押さえておく必要があります。