Claude APIのweb fetch料金は追加なし — max_content_tokensで絞る

Claude APIのweb_fetchツールに、呼び出し回数ごとの追加料金はありません。かかるのは、取得した内容がやり取りの文脈に入った分の標準トークン料金だけです。だから料金を左右するのは「何回取るか」より「どれだけ取り込むか」で、その手綱が max_content_tokens です。ただしこの上限はテキストにだけ効き、PDFには効きません。

web_fetchの料金は標準トークンだけ

web_fetchはClaude APIで追加費用なしに使えるツールです。公式ドキュメントの「Usage and pricing」節は、取得内容が会話の文脈に入る分の標準トークン料金だけを払うと説明しています。ツール使用料のような別建ての項目はありません。

レスポンスの usage には、トークン数と並んで server_tool_use.web_fetch_requests が入ります。ドキュメントの例では次の形です。

{
  "usage": {
    "input_tokens": 25039,
    "output_tokens": 931,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "server_tool_use": {
      "web_fetch_requests": 1
    }
  }
}

fetchが1回で、入力が約25,000トークン。この例では、増えた入力のほとんどが取得した1ページ分と読めます。web_fetch_requests は回数の記録で、課金の単位は input_tokens 側です。

Messages Batches APIでも考え方は同じです。バッチ経由のweb_fetch呼び出しは、通常のMessages APIと同じ価格で課金されます。

取り込み量はサイズから見積もる

冒頭の3点の目安は、どれも1 kBあたり約250トークンの比率に乗っています。ファイルサイズが分かれば、取り込み量はおおまかに掛け算で出せます。

実際の請求額は、この見積もりに使うモデルの入力単価を掛けて求めます。単価はモデルごとに違うので、数字は料金ページで確かめられます。

手元でサイズから見積もるなら、次のような小さな関数で足ります。係数は目安の比率から逆算した値で、あくまで概算です。

def estimate_fetch_tokens(size_bytes: int) -> int:
    # 公式の目安(10 kBで約2,500トークン)の比率
    return round(size_bytes * 0.25)
 
print(estimate_fetch_tokens(10_000))   # 2500
print(estimate_fetch_tokens(500_000))  # 125000

HTMLの装飾が多いページや日本語が中心のページでは、実際の値がずれることがあります。確かな数字が要るときは、実リクエストの usage.input_tokens を見るのが確実です。

同じページを複数ターンで使い回すと、取り込んだ内容は以降の入力にも残ります。1回の取得で125,000トークン入った会話は、次のターン以降もその分を抱えたまま進みます。長い会話でPDFを取るときは、この累積も頭に入れておく必要があります。

max_content_tokensで取り込み量に上限を置く

意図せず巨大なページを取って、トークンを使い切ることを防ぐための設定が max_content_tokens です。ツール定義の任意パラメータで、文脈に入れる内容の長さをトークン数で指定します。取得内容が上限を超えると、ツールが切り詰めます。

{
  "type": "web_fetch_20250910",
  "name": "web_fetch",
  "max_uses": 10,
  "max_content_tokens": 20000
}

20000は例示用の値です。公式のサンプルでは100000が使われています。用途に合わせて決める値で、冒頭の目安と突き合わせると考えやすくなります。20,000なら、100 kBのドキュメントページ(約25,000トークン)は途中で切られ、10 kBのページ(約2,500トークン)はそのまま入ります。

押さえておくべき点は2つあります。

• 上限は近似です。実際の入力トークン数は、上限から少しずれることがあります。ぴったり20,000で止まるとは限らないので、予算には余裕を見ておく必要があります。
• 上限は切り詰めます。長いページの後半に必要な情報があると、Claudeはそこを読めないまま答えます。切り詰めを避けたいときは、上限を引き上げるか、必要な部分だけを指すURLを渡します。

PDFにはmax_content_tokensが効かない

この上限はテキスト内容にだけ効き、PDFのようなバイナリには効きません。PDFを取得すると、APIはbase64のデータとして返し、直接添付したPDFと同じ扱いで処理します。上限で切る仕組みの外にあります。

つまり max_content_tokens: 20000 を設定していても、500 kBのPDFを取れば目安では約125,000トークンが入りえます。上限を置いたから安心、とは言えません。

PDFを含む取得で取り込み量を抑える手段は、max_content_tokens 以外にあります。

回数を超えた取得は、max_uses_exceeded のエラー結果になります。動的フィルタリングはClaude 4.6以降のモデルが対象で、この機能に関わる詳細は公式の「Dynamic filtering」節にあります。

web_fetch_20260318 には response_inclusion もあり、コード実行の中で使い終えた取得結果をレスポンスから落とせます。生のページ内容をクライアントに返す必要がないエージェント処理で、出力トークンのコストを減らすための設定です。コード実行ツール側の料金条件はコード実行ツールが無料になる条件にまとめています。

Managed Agentsのweb_fetchでも指定できる

Claude Managed Agentsでは、エージェントのツールセットにある web_fetch の設定に max_content_tokens を書けます。値は正の整数です。Messages APIと同じく、取得内容を文脈に入れる量の上限として働きます。

例えば次の形になります(公式のサンプルに沿った形です)。

tools:
  - type: agent_toolset_20260401
    configs:
      - type: web_fetch
        name: web_fetch
        blocked_domains: [ads.example.com]
        max_content_tokens: 50000

Claude Consoleでは、エージェントのフォームの「Built-in tools」カードに web_fetch の行があり、ドメインの許可・ブロックはここで設定できます。max_content_tokens は同じ画面の「Raw」ビューで書きます。

Messages APIのツールとは違う点もあります。

• Consoleにある組織単位のweb search・web fetch設定は、Managed Agentsのセッションには適用されません
• max_uses、citations、cache_control はツールセットで使えません
• web_fetch のドメインにはパスを含められません

max_uses が使えないので、Managed Agentsでは回数の上限を置けません。取り込み量の管理は max_content_tokens とドメイン制限が頼りになります。エージェント全体の課金はClaude Managed Agentsの料金で扱っています。

想定外に増えたときの確認手順

web_fetchを入れてから入力トークンが想定より増えたときは、次の順で原因を切り分けられます。

PDFの取得自体が失敗するときは、料金の前にエラーの確認が先です。「Could not process PDF」400エラーの原因と対処法に原因の切り分けがあります。

よくある疑問

取得に失敗したら課金されますか

取得に失敗すると、APIは200でエラー結果を返し、Claudeがそれを見て続きを進めます。失敗した取得は max_uses の回数には数えられます。料金の説明は、文脈に入った内容の標準トークンが課金対象という書き方です。失敗時に返るのはエラーコードを含む小さな結果ブロックで、ページ本文は入りません。そのため取り込み量は、成功時に比べるとごくわずかです。

キャッシュ済みの結果でもトークンはかかりますか

公式の料金節は、キャッシュの有無による価格差を説明していません。取得結果が文脈に入る限り、トークンとして数えられると考えておくのが安全です。キャッシュを避けて最新の内容を取る方法はWeb Fetchツールのuse_cacheでキャッシュを回避する方法にあります。

URLを渡しても取得されないときは

料金以前に、URLの検証で止まっている可能性があります。会話に一度も出ていないURLは取得できません。理由はurl_not_in_prior_contextエラーの原因で説明しています。

まとめ

web_fetchの追加料金はなく、払うのは文脈に入った内容の標準トークンです。トークン量はサイズからおおまかに見積もれ、テキストなら max_content_tokens で上限を置けます。PDFだけは例外で、上限の外にあります。PDFを扱うエージェントでは、取得先のドメインと回数の制限、動的フィルタリングを組み合わせて取り込み量を管理します。