Cloudflare Web Search API: choose a provider by privacy, cost, and result quality

Author: Ahab · Date: October 3, 2026

Quick answer

Cloudflare Web Search API gives an agent one interface for Ceramic.ai, Exa, and Linkup. Do not treat them as interchangeable. Pin the provider, classify query sensitivity, measure accepted-answer cost, and keep a tested fallback. For sensitive searches, use the stricter documentation: Cloudflare's provider table marks Ceramic and Linkup as Zero Data Retention, but Exa as not ZDR.

Who this is for

This guide is for developers adding live web grounding to an agent, chatbot, research workflow, or automation, especially on Workers or AI Gateway.

If you are also routing model inference through AI Gateway, pair this checklist with the AI Gateway model-routing validation guide.

What changed and why it matters

Cloudflare launched Web Search API in open beta on October 2, 2026. A backend can call a REST endpoint, while a Worker can call env.AI.websearch(). Every request passes through an AI Gateway and returns a normalized list containing URLs, titles, and provider-dependent descriptions plus request metadata.

The API supports Ceramic, Exa, and Linkup. ceramic is the default. Queries can contain up to 1,024 characters and return at most ten results. Payment uses AI Gateway credits or a stored BYOK provider key.

The normalized schema does not equalize privacy, price, coverage, freshness, or relevance. Those differences belong in the routing policy.

Provider contract and evidence boundary

Provider	Current documented route	ZDR in provider table	Published list price	Documented result behavior
Ceramic.ai	Default; independent web index	Yes	$0.25 / 1,000 requests	Long descriptions, up to 8,000 characters
Exa	`provider: "exa"`	No	$7.00 / 1,000 requests	`auto` search with query-relevant highlights
Linkup	`provider: "linkup"`	Yes	$5.00 / 1,000 requests	`fast` depth with raw search results

These are Cloudflare's terms, not IndieSeek tests. Verify the live documentation, account terms, billing, and result quality before production use.

There is also a documentation conflict worth treating as a release gate: the launch changelog says all three providers support Zero Data Retention through Cloudflare, while the detailed provider page says Exa does not. Until Cloudflare reconciles those pages or confirms your account terms, keep sensitive queries away from Exa and record the source used for the decision.

A seven-step rollout workflow

1. Classify the query before search

Separate public research from customer data, credentials, private repository text, internal URLs, and personal data. Redact or refuse sensitive input before search. ZDR is not permission to disclose data.

2. Pin the provider and credential path

Always set provider; do not let a future default change cost or handling. Decide whether each route uses Gateway credits or a named BYOK alias. A missing byokAlias fails with 400 rather than falling back to credits—use that fail-closed behavior for cost ownership.

3. Normalize only the transport

Map the response into your schema, but preserve provider, query, request ID, latency, URL, title, description presence, and retrieval time. Never turn a missing field into an empty-but-trusted fact.

4. Build a frozen query canary

Test navigational queries, exact docs, recent announcements, obscure entities, non-English queries, ambiguity, and zero-result cases. Keep expected domains and freshness windows, not one fragile ranking.

5. Measure accepted-answer cost

Search price is only one term:

accepted-answer cost =
  (search requests + model tokens + retries + review + correction)
  / accepted grounded answers

A cheap provider can become expensive if long descriptions inflate context or weak results trigger repeats. Cap result count and description bytes before the model.

6. Verify citations and freshness

Require the answer to cite returned URLs. Re-fetch or reject high-impact claims when a date is missing, the source is secondary, or the page no longer supports the statement. A successful call proves retrieval, not truth.

7. Canary one low-risk workflow

Start with read-only public research. Track no-result rate, expected-domain hits, citation support, latency, accepted-answer cost, and privacy violations. Your application must implement provider fallback. Roll back when any gate fails.

Provider decision tree

Does the query contain non-public or sensitive data?
  yes -> redact or refuse; if search remains necessary, require a verified ZDR route
  no  -> Is low request price the main constraint?
          yes -> canary Ceramic first
          no  -> Do you need concise query-relevant highlights?
                  yes -> evaluate Exa only if its privacy terms fit
                  no  -> compare Linkup fast results with Ceramic

Did the selected provider miss the quality or freshness gate?
  yes -> retry once with a pre-approved fallback and record both attempts
  no  -> pass bounded results to the model and verify citations

Search receipt template

policy_version: web-search-v1
query_class: public-release-check
provider: ceramic
credential_path: ai-gateway-credits
result_limit: 5
request_id: <gateway-request-id>
latency_ms: 612
returned_urls: 5
expected_domain_hit: true
freshness_gate: passed
context_bytes: 9400
model_answer_accepted: true
fallback_used: false

Common mistakes

Omitting provider and accidentally making the current default a permanent policy.
Treating one normalized response schema as equal privacy, quality, or freshness.
Repeating the launch post's ZDR statement without checking the conflicting provider table.
Comparing request prices while ignoring description size and model-token cost.
Logging sensitive raw queries merely because AI Gateway provides observability.
Calling URLs citations without checking that they support the generated claim.
Retrying across providers without a budget, privacy gate, or deduplication key.

Make your Mac notch useful with SuperNotch—more than 20 native tools for music, clipboard, focus, screenshots, system controls, and more.

FAQ

Is Cloudflare Web Search API generally available?

No. Cloudflare labels it open beta. Keep a versioned adapter and rollback for changing request shape, providers, pricing, and behavior.

Which provider should I use by default?

There is no universal winner. Ceramic is Cloudflare's current default and cheapest published option, but your choice should come from sensitivity, query mix, result quality, context cost, and fallback tests.

Does the API fetch full pages?

The response contains titles, URLs, and optional descriptions and metadata. For page evidence, fetch and validate the selected source separately under its access rules.

Can AI Gateway automatically fail over between search providers?

The Web Search request selects one provider. Implement and test search-provider fallback in your application unless Cloudflare documents a native mechanism later.