Cloudflare announced a Web Search API on October 2, 2026. It lets an AI agent or application search the Internet and use what comes back, instead of guessing URLs or relying on what a model learned before its training cutoff. It is in beta. This article explains what it means for you, how to use it and what you can do with it, and it includes one small script of my own that checks whether your site shows up.
I am writing this three days after the announcement, from two Cloudflare pages: the announcement in the changelog and the How to use guide. I have not called the live service, because that needs a Cloudflare account and an API token. The script near the end is tested against fake responses in the format the guide documents, not against the real thing, and, as on the rest of this site, it was written by an agent, with the tests as the gate.
What is the Cloudflare Web Search API?#
The Cloudflare Web Search API is a beta service that lets an AI agent or application search the Internet through a search provider and ground its answers in live results. You send a query and get back a list of pages, each with a URL, a title and a short description. Cloudflare routes the request to one of three search providers and bills it through AI Gateway.
- Announced: October 2, 2026, in beta.
- Providers: Ceramic.ai (the default), Exa and Linkup. The changelog says all three support Zero Data Retention for requests made through Cloudflare and have committed to Cloudflare’s verified bot crawling standards.
- Runs through: AI Gateway. Each search shows up in your gateway logs and is billed to your AI Gateway credits at the provider’s list price, with no markup. You can also bring your own provider key.
- Call it from: the REST API on any backend, or from a Worker with the AI binding.
- Limits: a query of up to 1,024 characters and up to 10 results per request.
As the pages describe it, the searching is done by those providers. Cloudflare is the router and the biller.
What does it mean for you?#
It means you can give an agent a search tool with one request to your own Cloudflare account. You can use it with AI Gateway credits alone, with no account at any search provider, or store a provider key of your own on the gateway.
| If you... | What changes |
|---|
| build agents | Search becomes one request, and switching provider is one field. The guide shows a model asking for a web_search tool and getting the results back. |
| run marketing or a store | You can ask the questions your customers ask and see which pages an agent built on this API would find. The script below does that. |
| own a site | Each result is a URL, a title and a description, and sometimes a last-modified date. Those are worth getting right, and so is not blocking the bots that read your pages by accident. |
| answer to a security team | Searches appear in gateway logs, the providers support Zero Data Retention for requests made through Cloudflare, and you can bring your own key. |
I do not know how each provider picks or writes those fields, because the guide does not say. And these three providers are not Google or an AI assistant, so what you see through this API is one view, not the whole picture. For stores, the other half of the story is how AI shopping assistants send visitors, which I wrote about in the feed and GA4 article.
How do you use the Web Search API?#
Make sure you have an AI Gateway with credits or a provider key, create an API token, then send a POST request to your account’s /ai/websearch/ endpoint, or call env.AI.websearch() from a Worker.
- Have a Cloudflare account and an AI Gateway. Every account has one named
default. - Load AI Gateway credits, or store a provider key on the gateway.
- For the REST API, create an API token with two permissions: Account > Workers AI > Read and Account > AI Gateway > Read.
- Send the request, from any backend:
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 is MER in ecommerce",
"provider": "exa",
"limit": 5,
"options": { "gateway": { "id": "default" } }
}'
- Or, in a Worker, add an AI binding to your Wrangler configuration and call
env.AI.websearch(). The guide says to set the compatibility date to today’s date:
{
"name": "visibility-check",
"main": "src/index.js",
"compatibility_date": "2026-10-05",
"ai": { "binding": "AI" }
}
The request has five fields:
| Field | Required | What it does |
|---|
query | Yes | The search, 1 to 1,024 characters |
provider | No | ceramic (the default), exa or linkup |
limit | No | How many results, 1 to 10, the default is 10 |
byokAlias | No | Use the provider key stored on your gateway under this alias; the request fails instead of falling back to credits if it is not configured |
options.gateway.id | Yes | The AI Gateway to route through (gatewayId in a Worker) |
The response has items and metadata. Each item has a url, a title and a description, and may have an imageUrl, a faviconUrl and a lastModifiedDate. Optional fields appear only when the provider returns them. The metadata holds the query, a requestId and the latencyMs. In a Worker, websearch() returns a standard Response, so you read it with response.json().
To use your own provider key, add it under your gateway’s Provider Keys in the dashboard with an alias, then pass provider and byokAlias. The key is never sent in the request. If you set byokAlias and the key is missing, the request fails with a 400 error. If you leave it out and the gateway has a key with the alias default for that provider, that key is used. Otherwise the search is billed to your credits.
Define a web_search function tool, run the search when the model asks for it, and pass the results back as a tool message. The guide’s example does this with a Workers AI model in three steps: ask the model with the tool defined, call env.AI.websearch() with the query the model chose, then ask the model again with the results attached. That is the whole pattern, and it fits in one Worker.
What can you do with it?#
You can ground an agent in live pages, watch a topic over time, compare providers and check your own visibility. These are ideas, and I have built only the last one.
- Ground a support or research agent. Let the model search, then answer with the URLs it used, so a claim comes with its source.
- Watch a topic. Run the same ten questions every week and keep the dated results, so a change in who shows up is visible.
- Compare providers. The same question against
ceramic, exa and linkup shows how different their results are. The provider field is the only thing that changes. - Check freshness. When a result has a
lastModifiedDate, an agent can prefer newer pages. For your own pages, make the date honest. - Check whether your site shows up. That is the next section.
How can you check whether your own site shows up?#
Run the questions your customers ask through each provider and record where your domain appears in the results. Here is a small Worker that does it. It takes a domain and up to 10 questions, asks ceramic, exa and linkup each one, and returns where the domain first appears, from 1 for the top result to null for not there:
const PROVIDERS = ['ceramic', 'exa', 'linkup']
const MAX_QUESTIONS = 10 // 10 questions x 3 providers = 30 searches a run
// Where does the domain first show up in the results? 1 is the top result, null means it is not there.
export const position = (items, domain) => {
const at = items.findIndex(({ url }) => {
try {
const host = new URL(url).hostname
return host === domain || host.endsWith(`.${domain}`)
} catch {
return false
}
})
return at < 0 ? null : at + 1
}
// Ask every provider every question and note where the domain shows up.
export const check = async (env, domain, questions) => {
const rows = []
for (const query of questions.slice(0, MAX_QUESTIONS)) {
if (typeof query !== 'string' || query.length < 1 || query.length > 1024) {
rows.push({ query: String(query).slice(0, 60), error: 'a query must be 1 to 1,024 characters' })
continue
}
for (const provider of PROVIDERS) {
const res = await env.AI.websearch({ gatewayId: 'default', query, provider, limit: 10 })
if (!res.ok) {
rows.push({ query, provider, error: res.status })
continue
}
const { items = [] } = await res.json()
rows.push({ query, provider, results: items.length, position: position(items, domain) })
}
}
return rows
}
export default {
async fetch(request, env) {
if (!env.CHECK_TOKEN || request.headers.get('authorization') !== `Bearer ${env.CHECK_TOKEN}`) {
return new Response('Unauthorized', { status: 401 })
}
const { domain, questions } = await request.json().catch(() => ({}))
if (!domain || !Array.isArray(questions)) {
return new Response('Send a domain and a list of questions', { status: 400 })
}
return Response.json(await check(env, domain, questions))
},
}
Here is what to look at.
position. It matches the domain or any subdomain, www. included, and does not match look-alikes such as notexample.com. A URL it cannot parse is skipped, not a crash.- The guards. A query must be a string of 1 to 1,024 characters, the guide’s limit, and only the first 10 questions are asked, so one run cannot go past 30 searches.
- Errors are rows, not crashes. If a provider answers with an error, the row says which status and the loop goes on.
- The Worker checks a secret. It answers 401 unless the request carries
CHECK_TOKEN as a bearer token, and also when no token is configured. A Worker that spends your credits must not be open to anyone who finds its address.
I wrote tests that feed the script fake responses in the format the guide documents. They run with the rest of this site’s tests on every build and evaluate the code printed above, so the article and the script cannot drift apart. Then I broke the code on purpose, in copies, to see whether the tests would notice. I planted 20 mistakes, such as matching look-alike domains, skipping the secret check and asking too many questions. The tests caught all 20.
I have not run it against the live service, so I have not seen a real result, a real price or a real error. Read the numbers with care too. These are three providers, not Google and not an AI assistant. A position of 1 says an agent built on this API would see you first. It says nothing about ChatGPT.
What should you watch out for?#
Three things: it is a beta, search results are untrusted text, and a search that costs money needs a limit.
- It is a beta. Cloudflare calls it that, and the guide is dated October 2, 2026. Names, fields and limits can change, so read the guide for your date before you copy anything from here. The docs also have pages called About and Providers, which I did not use.
- Results are untrusted text. A page can say anything, including instructions aimed at your agent. Treat what comes back as data, never as instructions, and give the agent the least access that works, the same rule as in my article on read-only analytics agents.
- Every search costs something. Searches are billed at each provider’s list price, or by the provider if you bring your own key. The two pages give no prices, so look them up, set
limit, and keep test runs small. The short answer is also in the FAQ. - Keep customer data out of queries. The Zero Data Retention statement is Cloudflare’s, about requests made through Cloudflare. Read the terms yourself before a query mentions a customer.
Where this leaves me#
What I like is how small the first step is: a gateway, a token and one request, with one field to switch provider. What I would do first is not build an agent. I would run the visibility script on ten questions my customers ask and read what comes back, because what AI answers can find on your site is the question behind most of my work on this one. It is three days old, I have not called it yet, and my sources are the vendor’s own pages, so take my enthusiasm for what it is. Documentation is the kindest place to form an opinion: nothing has broken yet.
Sources: Cloudflare, Introducing Web Search API (changelog, October 2, 2026) and How to use Web Search API (documentation, last updated October 2, 2026). The service is in beta, so some details here may have changed.