Cloudflare Web Search API: Open Beta, Provider Costs and BYOK

Cloudflare announced Web Search API through AI Gateway on October 2, 2026. Available in open beta, it gives agent builders one interface for searching the public web through Ceramic.ai, Exa or Linkup. Applications receive structured results to supply to a model, with search requests passing through Gateway logging, billing and access controls.

Choose public-web search or an indexed corpus

Use Web Search API for public-web evidence; use AI Search for a defined corpus. The former queries a selected search provider; the latter indexes connected or uploaded content and supports hybrid keyword and semantic retrieval. For that separate architecture and its pricing, see our Cloudflare AI Search guide.

This is a scope decision, not simply fresh versus stale: AI Search also refreshes its connected sources. An application could retrieve internal policy from an authorized corpus and public release notes through web search. Keep those evidence sources distinguishable in the answer. A web result does not establish that a page was fetched anew for that query.

Start with a bounded request

Create a gateway and arrange credits or a stored provider key. The REST endpoint is POST https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/websearch/. Its Cloudflare token needs both Account > Workers AI > Read and Account > AI Gateway > Read. Keep authentication on the backend.

Request body adapted from the documentation, not executed:

{
  "query": "Cloudflare Web Search API request limits",
  "provider": "ceramic",
  "limit": 5,
  "options": {
    "gateway": {
      "id": "default"
    }
  }
}

The request contract accepts 1–1,024 query characters and an integer result limit of 1–10. Defaults are ceramic and 10 results. For Workers, use env.AI.websearch() with an AI binding, replacing REST’s options.gateway.id with gatewayId; read its Response with response.json().

The normalized results include URL and title; descriptions and last-modified dates are optional. Validate items before using it. Preserve each source URL with its excerpt, and check the supporting page when a snippet is insufficient. Last-modified metadata is not a verified announcement date.

Compare the modes and the funded cost

Cloudflare’s October 2 provider table lists the following USD usage rates. These are the modes exposed by its integration, not each provider’s complete API. The final column is a calculation for 100,000 billable requests, including the separate 5% Unified Billing credit-purchase fee.

Calculation: requests ÷ 1,000 × list rate × 1.05. Before the funding fee, those requests consume $25, $700 or $500 in credits, respectively. This assumes unchanged rates, newly purchased credits fully allocated to this usage, and no discounts, free balances or taxes. It excludes model inference, Workers execution, logging and extra page fetches. Top-up sizes and unused balances can change the cash actually paid; BYOK follows your provider contract instead.

The same parser does not make the providers interchangeable in answer quality or context size. Longer descriptions can increase model input; snippets can leave a claim needing another fetch. Compare cost per adequately supported answer using the same queries, result limit and answer model. The documentation alone cannot identify a winner. Provider-specific filters and deeper modes are not documented controls in the shared request schema.

Make the billing route explicit

For BYOK, store the provider key on the gateway and pass byokAlias. A missing provider configuration or alias returns HTTP 400, without credit fallback. Omit the alias and the provider’s stored default key takes precedence; if absent, Gateway credits pay. BYOK is billed by the provider. See credential selection.

Implementation implication: specify both provider and alias when provider billing is required. Otherwise, changing a gateway’s default stored key can change the payer without changing application code. Surface a missing-alias error for configuration correction; do not silently reroute it to credits. The documented missing-key behavior does not establish what happens with an existing but expired key.

Check retention separately from logging

Cloudflare labels all three providers as supporting Zero Data Retention. Its general Unified Billing policy scopes managed-credential ZDR to that billing path, excludes BYOK, and says it does not control Gateway logging. For direct accounts, Exa and Linkup describe ZDR as Enterprise-scoped; check your own agreement before assuming BYOK has the same terms.

Gateway logs are enabled by default and can store request and response content. Review payload collection, access and retention independently of the provider’s policy. Cloudflare also distinguishes Workers Logs from Legacy Logs based on when a customer first created a gateway. Your application’s telemetry is a third storage decision; disabling Gateway logs does not disable that.

Connect the search to an answer model

Native AI Gateway Server Tools remain coming soon, with no release date stated. Today, the application must execute model-requested searches and return results through the selected model’s tool-response protocol. The REST endpoint is available; a complete tool loop is still your integration work.

• Bound the work: validate queries, cap searches per task, and set timeouts and retry budgets. Failed-call charging and retry accounting were not established by the reviewed sources.

• Keep evidence separate from instructions: public-web excerpts are source data, not permission to execute tools. Preserve required tool-call IDs and history, and allow an answer to report insufficient evidence.

• Evaluate before expanding: use representative questions to compare citation support, source dates, end-to-end latency, model input size and requests per completed answer. This is a proposed evaluation, not a reported test.

For capacity planning, Cloudflare’s general Gateway limits specify 200 requests per 60 seconds per gateway for Unified Billing with managed credentials. BYOK is exempt from that particular limit, not from every provider or account quota. This is a documented allowance, not measured Web Search throughput.

Methodology: AI-assisted reporting and analysis of Cloudflare and provider documentation, checked October 2, 2026. Pricing examples are arithmetic, not invoices. No live search API, relevance, latency or privacy tests were performed.