When an agent is asked, “What happened today?”, the model’s training cutoff cannot help. The hard part is not simply adding a search box: you have to integrate provider APIs, handle live results, log requests, control costs, and show the model which pages support its answer.
Cloudflare is now putting that whole set of engineering tasks behind one entry point. On October 2, 2026, Cloudflare announced that Web Search API had entered beta: developers can send a search request through AI Gateway, choose among Ceramic.ai, Exa, and Linkup, and give the agent results from the live internet. It addresses integration and governance, not the creation of another search engine.
That is practical for teams building web-connected agents: providers can be swapped without rewriting the call site and part of the surrounding governance logic. But a “unified API” does not mean that “the three providers return the same search results.” Before going to production, you still need to examine the shape of the results, the cost of each request, and whether the data-retention policy meets your requirements.
It turns search into a tool call for agents
Cloudflare’s official positioning for Web Search API is clear: let AI agents and applications search the internet and use real-time information to support their answers, without guessing URLs or relying only on the model’s training cutoff. Requests pass through AI Gateway, so search calls appear in gateway logs and are charged against AI Gateway credits at the selected provider’s listed API price, with no additional markup.
For developers, the change is not the search action itself but the consolidation of its boundaries. Previously, you might have had to manage the SDKs, keys, error handling, and billing for Ceramic.ai, Exa, or Linkup separately. Now provider selection can become a request parameter, and search calls can be observed through one gateway.
The abstraction is like installing a switchboard for the team: callers dial one number, while the line behind it can be changed. But the switchboard cannot decide which line is best, and it cannot turn search results into facts automatically. Cloudflare’s official announcement describes a unified entry point, not unified search quality.
That distinction matters. The product is still in beta, and Cloudflare has not published metrics for search quality, ranking stability, or answer accuracy. Connecting an agent to the live internet therefore cannot be translated directly into “the agent now verifies facts reliably.”
REST and Workers are both supported, but setup matters more than code
If your agent runs on your own backend, you can call the REST API directly. The endpoint is POST /client/v4/accounts/{account_id}/ai/websearch/. The request body requires at least query and can also specify provider, limit, and an AI Gateway ID.
Cloudflare’s documented parameter limits are explicit: query must be 1 to 1024 characters; limit defaults to 10 and accepts values from 1 to 10; and provider can be ceramic, exa, or linkup, defaulting to Ceramic.ai when omitted.
Permissions are an easy place to get stuck. The Cloudflare API token used for the REST request needs both Workers AI Read and AI Gateway Read permissions at the account level. The account also needs a gateway named default, or a gateway you created yourself, plus AI Gateway credits or a provider key. See How to use Web Search API for the full parameter and response definitions.
If the agent already runs in a Cloudflare Worker, the integration path is shorter: configure an AI binding for the Worker and call env.AI.websearch(). It returns a standard Response object, which you can read with response.json(). The main difference between REST and Workers is where they run, not two different search capabilities.
A minimal call looks like this:
const response = await env.AI.websearch({
gatewayId: "default",
query: "本周影响供应链的最新事件有哪些？",
provider: "exa",
limit: 5,
});
const results = await response.json();
The response does not contain a mysterious “final answer.” Its core fields are items and metadata: each result generally includes url, title, and description, while the metadata may include the query, request ID, and latency. Deciding how to filter sources, pass results to the model, and preserve citations in the answer remains application logic.
The differences between providers show up in what you feed the model
The shared parameters are simple, but the providers are not interchangeable equivalents. The differences listed in Cloudflare’s provider documentation begin with indexing, returned text, search method, and price.
| Provider | Result characteristics | Best suited to | List price / 1,000 requests | Zero Data Retention |
|---|---|---|---|---|
| Ceramic.ai | Page descriptions up to 8,000 characters | High-volume, low-cost search | $0.25 | Yes |
| Exa | Keyword and embedding search; returns highlights | Putting relevant passages directly into context | $7.00 | No |
| Linkup | fast search; returns raw results and text snippets |
Quickly obtaining results with sources | $5.00 | Yes |
Ceramic.ai is the default provider. Cloudflare’s documentation says it maintains an independent web index of more than 40 billion pages for agent and large-language-model applications, with an emphasis on low latency, low cost, and relatively long page descriptions. For an agent that searches repeatedly during a task, choosing it by default offers a clear budget advantage, but that does not mean it is necessarily the best fit for your domain.
Exa is oriented more toward “giving the model the most relevant passages.” It combines traditional keyword search with embedding search. Web Search API uses Exa’s auto search type and returns the page’s most relevant highlights as the description. When the context window is tight, relevant passages may be more convenient than a long page description. The trade-off is a considerably higher listed price, and the provider documentation marks Zero Data Retention as No.
Linkup uses the fast search depth and returns raw search results and text snippets instead of generating an answer for you. It is closer to a fast agent tool call: retrieve results, preserve the sources, and let your own toolchain handle post-processing. Its list price is lower than Exa’s and higher than Ceramic.ai’s, and Cloudflare marks it as supporting Zero Data Retention.
One common misreading deserves special attention: the prices in the table are provider list API prices, not your complete bill. When you pay with AI Gateway credits, Cloudflare says it adds no markup. With BYOK, meaning you store an existing provider API key in the gateway, the provider charges you directly under your agreement with it. Plans, taxes, retries, the upstream model, and application runtime costs cannot be inferred from this table.
A unified entry point does not verify sources for you
Web Search API returns a list of search results, not conclusions that have already been verified. If an agent takes an outdated page, marketing copy, or contradictory reports and generates an answer directly from them, the unified gateway will not turn that answer into a reliable fact automatically.
So integration should treat “search” and “answer” as separate steps. The search tool retrieves URLs, titles, descriptions, and request metadata. Your application still needs to decide whether to fetch the original text, require corroboration from multiple sources, designate high-trust domains, and show citations in the final answer.
Logging is one of the more useful layers of this design. Once a request passes through AI Gateway, the search call appears in gateway logs, while the returned requestId and latency information can help trace an agent task. But logs only tell you what happened to the request; they do not replace application-level evaluation, such as determining how many useful sources a question produced or whether the model used the results correctly.
Data policy also cannot be reduced to the phrase “Cloudflare provides unified access.” Cloudflare’s announcement says all three providers support Zero Data Retention for requests made through Cloudflare. The provider page’s table lists their statuses separately, with Exa currently marked No and Ceramic.ai and Linkup marked Yes. For your account, request path, and agreement, review the latest terms before production use.
BYOK has another easy-to-miss key-management behavior: if a request specifies byokAlias and that alias is not configured in the gateway, the call fails directly. It does not fall back automatically to AI Gateway credits. That prevents an invalid key from silently switching the billing method, but you need clear alerts for configuration errors.
Choose a provider by task before deciding whether to switch
A cautious trial sequence is to get the pipeline working with the default Ceramic.ai first, then compare all three providers using the same set of real questions. Do not compare only whether they found something. Also record whether the results can be passed directly to the model, whether the sources are suitable for display, whether latency affects the user experience, and whether logging and costs are transparent enough.
If an agent frequently checks the web during a task, low price and low latency will matter more. If you need to fit short, relevant source passages into the context, Exa’s highlights may be more convenient. If you want fast, sourced results and plan to handle post-processing in your own toolchain, Linkup’s response format is closer to that workflow. These are matching considerations, not guarantees from Cloudflare about performance.
Before integration, put three questions into the review checklist:
- Do we need long page descriptions, relevant highlights, or raw results with snippets?
- Will this request use AI Gateway credits or BYOK? What application-layer costs exist beyond the list price?
- Which data-retention policy applies to the agent’s queries and returned content, and who will periodically review the provider terms?
The value of Cloudflare’s release is that it reduces the engineering friction of switching providers and connecting a gateway. It is better understood as observable, switchable search infrastructure than as an answer machine that becomes reliable as soon as it is connected. Put provider differences, billing boundaries, and source verification into the system design first, then test the beta API against real traffic. That is the more dependable way to use this capability today.
Sources
- Introducing Web Search API: Cloudflare’s official announcement, October 2, 2026
- How to use Web Search API: Cloudflare’s official usage documentation
- Providers: Cloudflare’s official provider, pricing, and data-retention documentation
- AI Gateway unified billing: Cloudflare AI Gateway unified billing documentation
