Claude APIのweb_search料金 — 1,000回10ドルと入力トークンの積み上がり

Claude APIのweb_search(Web検索ツール)は、1,000検索あたり10ドルの従量課金です。つまり1検索は0.01ドルです。ただし請求はこの検索料だけで終わりません。検索結果は入力トークンとして数えられ、会話が続けば後続ターンでも数えられます。

この記事は、検索料とトークン料の2本立てで請求が決まる仕組みを、レスポンスのusageの読み方と費用を抑える設定まで含めて解説します。Claude CodeやClaude.aiでのWeb検索の動き方はClaude Web検索の使い方が扱っています。ここで扱うのはAPIの課金です。

請求は検索料とトークン料の2本立て

料金ページは、web_searchの費用を「トークン料金に加えて課金される」ものと位置づけています。構成要素は次の2つです。

検索料は1,000検索10ドルという単価で示されており、モデル別の料金表とは別立てです。

検索1回の数え方

1回の検索は1 useと数えられます。返ってきた結果が3件でも10件でも同じです。結果件数を絞っても検索料は減りません。

1回のリクエストの中でClaudeが何度も検索することもあります。そのたびに1 useが加算されます。簡単な事実確認なら1〜3回ですが、複数の対象を比べる調査では10回以上になることもあります。

エラーになった検索は課金されない

検索中にエラーが起きた場合、その検索は課金されません。web_searchのエラーはHTTPとしては200で返り、本文のweb_search_tool_resultにエラーコードが入る形です。コード別の意味と分岐の書き方はweb_searchのエラーコード一覧にまとめています。

課金の観点で押さえたいのは、エラーが起きたこと自体はコストにならない点です。トークン料の扱いは料金ページに個別の記載がないため、見積もりでは通常どおりかかるものとして計算しておくと確実です。

検索結果は入力トークンに積まれる

検索料より効いてくるのは、多くの場合トークン料です。料金ページは、取得した検索結果が会話の途中で入力トークンとして数えられると説明しています。数えられる場面は2つです。

• 同じターンの中で実行された検索の反復
• 会話の後続ターン

2つ目が見落とされやすい点です。1ターン目で取り込んだ検索結果は、会話履歴の一部として2ターン目以降のリクエストにも含まれます。履歴が重くなるぶん、後続ターンの入力トークンも増えます。

長い会話ほど検索結果の持ち越しが効く

たとえば3ターン続く会話で、1ターン目に検索結果が約6,000トークン入ったとします。履歴をそのまま送り続ければ、2ターン目と3ターン目の入力にも同じ約6,000トークンが載ります。数値は例ですが、検索1回あたりの検索料(0.01ドル)よりも、持ち越されるトークン料のほうが大きくなる場面があります。

先ほどの例を、ターンごとの入力に載る検索結果で並べると次のようになります。ターン数以外の値はすべて仮定です。

検索1回で取り込んだ分が、3ターンで合計3回分の入力として数えられます。10ターン続けば10回分です。会話を短く区切るか、結果が不要になった時点で履歴から外す設計にすると、この積み上がりを避けられます。

プロンプトキャッシュを使うと、繰り返し送る部分の単価を下げられます。料金ページのレスポンス例にもcache_read_input_tokensとcache_creation_input_tokensが並んでいます。キャッシュの倍率はモデルの料金表に従うため、実際の金額はモデルごとに確認してください。

dynamic filteringで取り込む量を減らす

web_search_20260209以降では、Claudeが検索結果をコードで絞り込んでからコンテキストに入れる動作が既定になります。不要な内容が入らないぶん、検索の多いリクエストでトークン消費が減るとされています。

このときのコード実行に追加料金はなく、通常のトークン料金だけです。ただしdynamic filteringにはZDR(ゼロデータ保持)の扱いという別の論点があり、dynamic filteringがZDR対象外になる仕組みにまとめています。

コード実行ツールを単体で使う場合の課金は別で、実行時間が基準になります。こちらはcode executionツールの料金を参照してください。

response_inclusionでレスポンスに返す量を減らす

web_search_20260318以降にはresponse_inclusionパラメータがあります。検索結果がコード実行の呼び出しで使われ、そのターン内で完了した場合に、検索結果のブロックをレスポンスに含めるかを決めます。"excluded"にすると、入れ子のserver_tool_useと結果ブロックの組がレスポンスから丸ごと外れ、生の検索内容をクライアントに返す必要がないエージェント処理では出力トークンの費用が減ります。既定は"full"です。

{
  "type": "web_search_20260318",
  "name": "web_search",
  "response_inclusion": "excluded"
}

効くのは条件を満たした検索だけです。直接呼び出しの結果と、コード実行が完了前に一時停止した場合の結果は、次のターンで送り返すために常に全量が返ります。dynamic filteringが有効で、検索結果を受け取る必要がない処理に向く設定です。

usageで検索回数を読む

実際に何回検索されたかは、レスポンスのusage.server_tool_use.web_search_requestsで読めます。料金ページの例では次の形です。

{
  "usage": {
    "input_tokens": 105,
    "output_tokens": 6039,
    "cache_read_input_tokens": 7123,
    "cache_creation_input_tokens": 7345,
    "server_tool_use": {
      "web_search_requests": 1
    }
  }
}

この値に0.01ドルを掛ければ、そのリクエストの検索料が分かります。トークン料は別の項目から出します。Pythonで記録する場合は、次のように取り出せます(SDKのレスポンスを想定した例です)。

usage = response.usage
searches = usage.server_tool_use.web_search_requests
search_cost = searches * 0.01  # 1,000検索10ドル = 1検索0.01ドル
print(f"検索 {searches} 回 / 検索料 ${search_cost:.2f}")
print(f"入力 {usage.input_tokens} / 出力 {usage.output_tokens}")

ログにこの2行を足しておくと、月末の請求書で検索料が膨らんだ理由を、リクエスト単位まで遡れます。

max_usesで検索料の上限を決める

費用を抑える手段として、ツール定義のmax_usesがあります。1リクエストあたりの検索回数を制限するパラメータです。

{
  "type": "web_search_20250305",
  "name": "web_search",
  "max_uses": 5
}

max_usesを5にすれば、1リクエストの検索料は最大でも5回分の0.05ドルです。Claudeが上限を超えて検索しようとすると、web_search_tool_resultがmax_uses_exceededのエラーになります。前節のとおりエラーの検索は課金されないので、上限を超えた分が請求に乗ることはありません。

上のJSONはweb_search_20250305の例です。前節のdynamic filteringはweb_search_20260209以降の動作なので、そちらを使う場合はtypeを読み替えてください。max_usesは全バージョンで指定できます。

上限の決め方

上限を低くしすぎると、調査が途中で打ち切られて回答の質が落ちます。簡単な事実確認が中心なら小さめ、複数対象の比較が中心なら大きめに置くのが目安です。システムプロンプトで検索を控えるよう誘導する方法もありますが、確実な歯止めはmax_usesです。

日次の見積もり例

仮に1日500リクエスト、1リクエストあたり平均3検索とすると、検索は1日1,500回です。検索料は1日15ドル、30日で450ドルになります。max_usesを2に絞れば、同じ500リクエストでも検索料の上限は1日10ドルです。トークン料はこれとは別に加算されます。

検索そのものを使えない場合

組織の管理者がClaude Consoleでweb_searchを無効にしている場合、ツールを含むリクエストは400のinvalid_request_errorで失敗します。検索結果内のエラーコードとは別の経路で、リクエスト自体が400で失敗し、検索は実行されません。

Batches APIとManaged Agentsでの扱い

Messages Batches APIのweb_searchも、通常のMessages APIと同じ価格です。バッチだから検索料が割り引かれるわけではありません。検索が多いバッチは、組織単位の絞り込みで完了まで時間がかかることがあります。

Claude Managed Agentsのセッション内で検索した場合も、標準の1,000検索10ドルがかかります。トークン料はモデルの料金表どおりで、これに加えてセッションの稼働時間分が課金されます。二軸の見積もり方はManaged Agentsの料金で試算しています。

Claude Codeの検索回数制限との違い

Claude Codeには検索回数の上限を変える環境変数があり、CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSIONとして別記事にしています。これはClaude Code側のセッション運用の設定です。APIで自作のエージェントを組むなら、費用の歯止めはmax_usesとusageの記録で自分で用意します。

まとめ

検索料は1回0.01ドルで、結果の件数に左右されません。読むべきは、結果が入力トークンとして後続ターンにも持ち越される点です。見積もりはmax_usesで検索料の上限を決め、usageで実測を残し、長い会話ではキャッシュとdynamic filteringでトークン料を抑える、という順で組み立てられます。