Web Search About Web Search API AI models are only as good as the context you give them. Models are trained and then frozen at a point in time, so they only know about information that existed before their knowledge cutoff date. This makes it difficult to work with models on recent events, changing APIs, or fast-moving news. Without web search, an agent that needs live information usually guesses the URL of a page and fetches it directly. When the guess is wrong, the request returns a 404 Not Found and the agent has to try again. Web Search API gives your agents a better option. Like a person starting with a search engine, your agent sends a query and receives a list of relevant, up-to-date results. You can inject those results into the model's context so its response is grounded in live information. How it works When you send a search request, Web Search API: Routes the request through the AI Gateway you specify. Forwards the query to the search provider you choose — Ceramic.ai, Exa, or Linkup. If you do not set a provider, Web Search API uses Ceramic.ai as default. Normalizes the provider's response into a consistent format, with a URL, title, and optional description, image, favicon, and last-modified date for each result. Records the request in your AI Gateway logs and bills it to your account. Because every provider returns the same result format, you can switch providers by changing a single parameter. AI Gateway integration Web Search API is built on AI Gateway, which acts as the control plane for your AI applications. Every search request goes through a gateway, which gives you: Observability — Search requests appear in your gateway's logs and analytics alongside your model inference requests. Unified Billing — Searches draw down from your AI Gateway credit balance. You pay each provider's list API price, with no additional markup. For rates, refer to Providers. Bring your own key (BYOK) — If you already have an account with a search provider, you can store your provider API key on your gateway. The provider bills you directly. Access control — Control which providers your gateway can use and who can send requests. Crawler standards Cloudflare believes that crawlers should be honest and transparent, and should respect the rules and preferences that site owners set. Site owners should have meaningful visibility into and control over how their content is used. Every Web Search API provider has committed to meet the following standards: Verified bot compliance — The crawler the provider uses must meet Cloudflare's published requirements for verified bots. This includes identifying the crawler and respecting robots.txt. Source attribution — Every search result must include a link to the location of the crawled content. When you use Web Search API, your agents consume search results from operators that give site owners transparency, control, and visibility over how their content is crawled. Related resources How to use Web Search API Providers and pricing AI Gateway How to use Web Search API import { DashButton, Steps, TabItem, Tabs, WranglerConfig } from " /components"; import SchemaDisplay from "/components/models/SchemaDisplay.astro"; export const sharedInputProperties = { query: { type: "string", description: "The search query.", minLength: 1, maxLength: 1024, }, provider: { type: "string", description: "The search provider to use.", enum: ["ceramic", "exa", "linkup"], default: "ceramic", }, limit: { type: "integer", description: "The maximum number of search results to return.", minimum: 1, maximum: 10, default: 10, }, byokAlias: { type: "string", description: "The alias of a provider API key stored on your gateway. If set, the request fails instead of falling back to AI Gateway credits when the key is not configured.", pattern: "^[A-Za-z0-9_-]{1,64}$", }, }; export const restInputSchema = { type: "object", properties: { query: sharedInputProperties.query, provider: sharedInputProperties.provider, limit: sharedInputProperties.limit, byokAlias: sharedInputProperties.byokAlias, options: { type: "object", description: "Request options.", properties: { gateway: { type: "object", description: "The AI Gateway to route the request through.", properties: { id: { type: "string", description: "The ID of the AI Gateway.", }, }, required: ["id"], }, }, required: ["gateway"], }, }, required: ["query", "options"], }; export const bindingInputSchema = { type: "object", properties: { gatewayId: { type: "string", description: "The ID of the AI Gateway to route the request through.", }, query: sharedInputProperties.query, provider: sharedInputProperties.provider, limit: sharedInputProperties.limit, byokAlias: sharedInputProperties.byokAlias, }, required: ["gatewayId", "query"], }; export const outputSchema = { type: "object", properties: { items: { type: "array", description: "The search results.", items: { type: "object", properties: { url: { type: "string", description: "The URL of the result." }, title: { type: "string", description: "The title of the page." }, description: { type: "string", description: "A description or excerpt of the page.", }, imageUrl: { type: "string", description: "An image associated with the page.", }, faviconUrl: { type: "string", description: "The favicon of the site.", }, lastModifiedDate: { type: "string", format: "date-time", description: "The date the page was last modified.", }, }, required: ["url", "title"], }, }, metadata: { type: "object", description: "Information about the request.", properties: { query: { type: "string", description: "The search query." }, requestId: { type: "string", description: "A unique identifier for the request.", }, latencyMs: { type: "number", description: "The request latency in milliseconds.", }, }, }, }, }; You can call Web Search API from any backend with the REST API, or from a Worker with the AI binding. Both methods route requests through an AI Gateway. Prerequisites A Cloudflare account. If you do not have one, sign up. An AI Gateway. Every account has a gateway named default, or you can create a gateway. AI Gateway credits loaded on your account, or a provider API key stored on your gateway. REST API Send a POST request to the /ai/websearch/ endpoint: POST https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/websearch/ Authenticate with a Cloudflare API token that has both of the following permissions: Account > Workers AI > Read Account > AI Gateway > Read 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" } } }' Workers binding Call Web Search API from a Worker with the websearch() method on the AI binding. Add an AI binding to your Wrangler configuration file: name = "web-search-worker" main = "src/index.ts" upload_source_maps = true compatibility_date = "$today" [ai] binding = "AI" Call env.AI.websearch() with your gateway ID and query: export default { async fetch(request, env): Promise { 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(); return Response.json(results); }, } satisfies ExportedHandler; websearch() returns a standard Response object. Call response.json() to read the results. Request parameters Set provider to choose a search provider. If you do not set a provider, Web Search API uses Ceramic.ai as default. { "query": "What are some fun things to do in Salt Lake City as fall approaches?", "provider": "ceramic", "limit": 5, "options": { "gateway": { "id": "default" } } } const response = await env.AI.websearch({ gatewayId: "default", query: "What are some fun things to do in Salt Lake City as fall approaches?", provider: "ceramic", limit: 5, }); Response format { "items": [ { "url": "https://example.com/salt-lake-city-fall-guide", "title": "Fall in Salt Lake City: A Local's Guide", "description": "From scenic drives up Big Cottonwood Canyon to pumpkin patches..." } ], "metadata": { "query": "What are some fun things to do in Salt Lake City as fall approaches?", "requestId": "", "latencyMs": 612 } } Optional fields are only included when the provider returns them. Bring your own key (BYOK) If you have an existing account with a search provider, you can use your own API key instead of AI Gateway credits. The provider bills you directly. In the Cloudflare dashboard, go to the AI Gateway page. Select your gateway, then select Provider Keys. Add an API key for Ceramic.ai, Exa, or Linkup, and assign it an alias — for example, default. If the provider is not listed, select Configure custom providers to add it. Pass the provider and alias in your request. 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 Cloudflare Workers?", "provider": "exa", "byokAlias": "default", "options": { "gateway": { "id": "default" } } }' const response = await env.AI.websearch({ gatewayId: "default", query: "What is Cloudflare Workers?", provider: "exa", byokAlias: "default", }); Your API key is never sent in the request. AI Gateway retrieves the key stored on the gateway for the provider and alias, and encrypts stored keys with Secrets Store. AI Gateway selects credentials as follows: You set byokAlias — AI Gateway uses the stored key with that alias. If the provider or alias is not configured on the gateway, the request fails with a 400 error instead of falling back to your credits. You omit byokAlias — If the gateway has a stored key with the default alias for the provider, AI Gateway uses that key. Otherwise, the search is billed to your AI Gateway credits. For more information, refer to Bring your own keys. Use web search as a tool You can give a model access to web search by defining a web_search tool. When the model calls the tool, run the search and pass the results back to the model. const MODEL = "@cf/google/gemma-4-26b-a4b-it"; export default { async fetch(request, env): Promise { const prompt = "What happened during the last Cloudflare Birthday Week?"; const messages = [{ role: "user", content: prompt }]; const completion = await env.AI.run( MODEL, { messages, tools: [ { type: "function", function: { name: "web_search", description: "Search the web for current information.", parameters: { type: "object", properties: { query: { type: "string" } }, required: ["query"], }, }, }, ], }, { gateway: { id: "default" } }, ); const toolCall = completion.tool_calls?.[0]; if (toolCall?.name !== "web_search") { return Response.json(completion); } const searchResponse = await env.AI.websearch({ gatewayId: "default", query: toolCall.arguments.query, limit: 5, }); const searchResults = await searchResponse.json(); const finalResponse = await env.AI.run( MODEL, { messages: [ ...messages, { role: "tool", name: "web_search", content: JSON.stringify(searchResults), }, ], }, { gateway: { id: "default" } }, ); return Response.json(finalResponse); }, } satisfies ExportedHandler; Limits Limit Value Query length 1,024 characters Results per request 10 Cloudflare Web Search API import { CardGrid, Description, Feature, LinkButton, LinkTitleCard, Plan, RelatedProduct, } from "~/components"; Give your agents real-time web context with a single API call. Web Search API lets your AI agents and applications search the Internet and ground their responses in live information. Instead of guessing URLs or relying on a model's training cutoff, your agent sends a search query and receives structured results — titles, URLs, and descriptions — that you can pass straight into a model's context. Web Search API runs through AI Gateway, so every search gets the same logging, analytics, billing, and access controls as your model inference requests. You can call it from any backend with the REST API, or from a Worker with the AI binding. How to use{" "} Browse providers Features Choose between Ceramic.ai, Exa, and Linkup with a single provider parameter. All providers return results in the same format, so you can switch without changing your code. Pay for searches with your AI Gateway credits at each provider's list API price, with no additional markup. You can also bring your own provider API key. Search requests appear in your AI Gateway logs and analytics alongside your model inference requests. Every provider commits to Cloudflare's verified bot requirements and returns a link to the source of every result. Related products Observe and control your AI applications with analytics, caching, rate limiting, and model fallback. Run machine learning models, powered by serverless GPUs, on Cloudflare's global network. Build AI-powered agents that can perform tasks, persist state, browse the web, and communicate in real time. More resources