Cloudflare Web Search API が beta、検索3社の課金と BYOK の条件

Cloudflare の Web Search API が 2026年10月2日に beta になった。エージェントやアプリケーションからインターネットを検索し、モデルの学習時点の知識や推測した URL に頼らずに、取得した情報を回答の根拠にするための API だ。検索プロバイダは Ceramic.ai、Exa、Linkup の3社から選ぶ。

リクエストは AI Gateway を通る。AI Gateway クレジットを使う場合は各プロバイダの API 定価で課金され、Cloudflare の上乗せはない。自分のプロバイダ API キーを使う BYOK では、プロバイダが自分の契約に従って直接請求する。課金の集約を求めるチームは、クレジット課金と BYOK を分けて選ぶ必要がある。

呼び出しは REST と AI binding の二通り

changelog には REST API と Worker の AI binding の例が載っている。どちらも検索文字列、プロバイダ、件数、使う gateway を渡す形だ。

REST API ではアカウント単位のエンドポイントに POST する。公式の利用手順では、認証トークンに Account の Workers AI と AI Gateway の両方の Read 権限が必要とされている。Worker 側は Wrangler 設定に AI binding を追加してから呼ぶ。

curl https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/websearch/ \
  --request POST \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "query": "What are some fun things to do in Salt Lake City as fall approaches?",
    "provider": "ceramic",
    "limit": 5,
    "options": { "gateway": { "id": "default" } }
  }'

Worker からは AI binding の websearch() を使う。

const response = await env.AI.websearch({
  gatewayId: "default",
  query: "What are some fun things to do in Salt Lake City as fall approaches?",
  provider: "exa",
  limit: 5,
});

const results = await response.json();

二つを並べると、gateway の指定場所が違う。REST では options.gateway.id にネストし、binding ではトップレベルの gatewayId に置く。REST で試した body をそのまま binding に移すと gateway の指定が抜けるので、移植するときはここを書き換える。

公式の利用手順にある provider の値は ceramic、exa、linkup で、省略時は Ceramic.ai になる。レスポンスは items と metadata を持ち、結果には URL、タイトル、description などが入る。任意項目はプロバイダが返す場合だけ含まれるため、整形処理ではすべてのフィールドが必ずあると仮定しない。

Zero Data Retention は公式情報が一致していない

出典欄に記載した取得時点では、公式情報に不一致がある。10月2日の changelog は Cloudflare 経由なら3社とも Zero Data Retention に対応すると書くが、リンク先のProviders 表は Ceramic.ai と Linkup が Yes、Exa が No と記載している。どちらの記述が最新の適用条件を示すかは確認できていない。Exa を含めた3社一律の対応を前提に、機密情報を含むクエリを送る判断はできない。

changelog では3社とも Cloudflare の verified bot のクロール基準に従うことを約束している。ただし、検索プロバイダの保存条件と AI Gateway のログは別の話だ。Zero Data Retention の記述を、検索経路全体でログが保存されないという意味には読めない。

費用とログは AI Gateway に寄る

Web Search API は AI Gateway 上で動くので、検索リクエストは gateway のログに出る。LLM の呼び出しと同じ gateway を指定すれば、モデル呼び出しと検索の両方を一つのログで追える。エージェントが何を検索してから回答したかを後から確かめたいとき、この並びは役に立つ。

クレジット課金は各プロバイダの API 定価で、具体的な単価は Providers 表で確認できる。BYOK の直接請求では自分とプロバイダとの契約条件が適用されるので、クレジット課金の条件と同じとは限らない。

公式の利用手順では、gateway の Provider Keys にキーを登録し、リクエストの byokAlias で alias を指定する。指定したキーが設定されていなければ、クレジット課金へ切り替わらずリクエストが失敗する。byokAlias を省略した場合も、その provider の default alias のキーが登録されていればそちらが使われ、なければ AI Gateway クレジットで課金される。AI Gateway の請求の見え方については、月次請求がモデル単位 1 行になった変更も合わせて見ておくとよい。

試す前に決めておくこと

beta の段階なので、本番のエージェントに組み込む前に次を決めておくと手戻りが少ない。

• どの gateway を通すか。例はどちらも default を使っている
• どのプロバイダから始めるか。切り替えは provider の値を変えるだけなので、同じクエリで結果を比べやすい
• 課金を AI Gateway クレジットに寄せるか、自分のキーを持ち込むか
• limit をいくつにするか。例の 5 をそのまま使う前に、公式の利用手順の Request parameters と Limits で許容範囲を確かめる

既に各プロバイダの API を直接呼んでいる場合、AI Gateway 経由で検索ログをモデル呼び出しとまとめて追える。請求を AI Gateway に集約できるのはクレジット課金を選ぶ場合で、BYOK は提供元の直接請求になる。クレジット課金は定価で上乗せがないという条件であり、自分の契約より安くなる保証ではない。保存条件は公式情報の不一致を解消してから判断する必要がある。