--- title: Web Search description: Use provider-native web search tools through AI Gateway, or reach search-first providers like Perplexity and Parallel through their proxy endpoints. image: https://developers.cloudflare.com/dev-products-preview.png --- > Documentation Index > Fetch the complete documentation index at: https://developers.cloudflare.com/ai-gateway/llms.txt > Use this file to discover all available pages before exploring further. [Skip to content](#%5Ftop) # Web Search AI Gateway proxies native web search tools from supported providers so models can answer questions about events after their training cutoff. Search runs on the upstream provider; AI Gateway applies its standard features — logging, caching, rate limiting, and guardrails — to the request. How you enable web search depends on the provider. Activation is either a tool entry on a `tools` array or a top-level flag on the request body. The table below points you to the right section. ## Supported providers | Provider | Endpoint | Activation | | --------- | ---------------------------- | ------------------------------------------------------------------------------------- | | Anthropic | POST /ai/v1/messages | tools: \[{ "type": "web\_search\_20250305", "name": "web\_search", "max\_uses": N }\] | | OpenAI | POST /ai/v1/responses | tools: \[{ "type": "web\_search\_preview" }\] | | xAI | POST /ai/v1/responses | tools: \[{ "type": "web\_search" }\] | | Alibaba | POST /ai/v1/chat/completions | top-level "enable\_search": true | For providers whose product is search itself — Perplexity and Parallel — refer to [Search-first providers](#search-first-providers). ## Anthropic web search Anthropic models expose web search through their native [web\_search\_20250305 tool ↗](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool). Add it to the `tools` array on a `POST /ai/v1/messages` request. Supported models — `anthropic/claude-haiku-4.5`, `anthropic/claude-opus-4.5`, `anthropic/claude-opus-4.6`, `anthropic/claude-opus-4.7`, `anthropic/claude-opus-4.8`, `anthropic/claude-sonnet-4.5`, `anthropic/claude-sonnet-4.6`. Terminal window ``` # Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/messages" \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "model": "anthropic/claude-haiku-4.5", "max_tokens": 4096, "messages": [ { "role": "user", "content": "What were the top news stories about Cloudflare this week? Summarize in three bullets." } ], "tools": [ { "type": "web_search_20250305", "name": "web_search", "max_uses": 3 } ] }' ``` Equivalent call from a Worker using the AI binding: * [ JavaScript ](#tab-panel-6894) * [ TypeScript ](#tab-panel-6895) JavaScript ``` const resp = await env.AI.run( "anthropic/claude-haiku-4.5", { max_tokens: 4096, messages: [ { role: "user", content: "What were the top news stories about Cloudflare this week? Summarize in three bullets.", }, ], tools: [{ type: "web_search_20250305", name: "web_search", max_uses: 3 }], }, { gateway: { id: "default", // or use a specific gateway name }, },); ``` TypeScript ``` const resp = await env.AI.run( "anthropic/claude-haiku-4.5", { max_tokens: 4096, messages: [ { role: "user", content: "What were the top news stories about Cloudflare this week? Summarize in three bullets.", }, ], tools: [{ type: "web_search_20250305", name: "web_search", max_uses: 3 }], }, { gateway: { id: "default", // or use a specific gateway name }, },); ``` Search invocations and results appear in the response as `server_tool_use` and `web_search_tool_result` content blocks. Configurable parameters include `max_uses`, `allowed_domains`, `blocked_domains`, and `user_location` — refer to Anthropic's [web search tool documentation ↗](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool) for the full list. ## OpenAI web search OpenAI models expose web search through the [web\_search\_preview tool ↗](https://developers.openai.com/api/docs/guides/tools-web-search) on the Responses API. Use the `POST /ai/v1/responses` endpoint and add the tool to the `tools` array. Supported models — `openai/gpt-4.1`, `openai/gpt-4.1-mini`, `openai/gpt-4o`, `openai/gpt-4o-mini`, `openai/gpt-5`, `openai/gpt-5-mini`, `openai/gpt-5-nano`, `openai/gpt-5.1`, `openai/gpt-5.4`, `openai/gpt-5.4-mini`, `openai/gpt-5.4-nano`, `openai/gpt-5.4-pro`, `openai/gpt-5.5`, `openai/gpt-5.5-pro`, `openai/o3`, `openai/o4-mini`. Terminal window ``` # Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/responses" \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "model": "openai/gpt-4o-mini", "input": "What were the top news stories about Cloudflare this week? Summarize in three bullets.", "max_output_tokens": 4096, "tools": [ { "type": "web_search_preview" } ] }' ``` Equivalent call from a Worker using the AI binding: * [ JavaScript ](#tab-panel-6890) * [ TypeScript ](#tab-panel-6891) JavaScript ``` const resp = await env.AI.run( "openai/gpt-4o-mini", { input: "What were the top news stories about Cloudflare this week? Summarize in three bullets.", max_output_tokens: 4096, tools: [{ type: "web_search_preview" }], }, { gateway: { id: "default", // or use a specific gateway name }, },); ``` TypeScript ``` const resp = await env.AI.run( "openai/gpt-4o-mini", { input: "What were the top news stories about Cloudflare this week? Summarize in three bullets.", max_output_tokens: 4096, tools: [{ type: "web_search_preview" }], }, { gateway: { id: "default", // or use a specific gateway name }, },); ``` OpenAI web search is available only on the Responses API endpoint (`POST /ai/v1/responses`). The `/ai/v1/chat/completions` endpoint does not accept the `web_search_preview` tool. Both `{ "type": "web_search_preview" }` and `{ "type": "web_search" }` are accepted on the Responses API. The examples here use `web_search_preview`. ## xAI web search xAI's multi-agent Grok model exposes web search through the [web\_search tool ↗](https://docs.x.ai/developers/tools/web-search) on the Responses API. Add `{ "type": "web_search" }` to the `tools` array on a `POST /ai/v1/responses` request. Supported models — `xai/grok-4.20-multi-agent-0309`. Terminal window ``` # Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/responses" \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "model": "xai/grok-4.20-multi-agent-0309", "input": "What were the top news stories about Cloudflare this week? Summarize in three bullets.", "max_turns": 4, "tools": [ { "type": "web_search" } ] }' ``` Equivalent call from a Worker using the AI binding: * [ JavaScript ](#tab-panel-6892) * [ TypeScript ](#tab-panel-6893) JavaScript ``` const resp = await env.AI.run( "xai/grok-4.20-multi-agent-0309", { input: "What were the top news stories about Cloudflare this week? Summarize in three bullets.", max_turns: 4, tools: [{ type: "web_search" }], }, { gateway: { id: "default", // or use a specific gateway name }, },); ``` TypeScript ``` const resp = await env.AI.run( "xai/grok-4.20-multi-agent-0309", { input: "What were the top news stories about Cloudflare this week? Summarize in three bullets.", max_turns: 4, tools: [{ type: "web_search" }], }, { gateway: { id: "default", // or use a specific gateway name }, },); ``` `xai/grok-4.20-multi-agent-0309` is the only xAI model that accepts web search through AI Gateway. For other Grok models, refer to [Models without web search support](#models-without-web-search-support). ## Alibaba (Qwen) web search Alibaba DashScope Qwen models enable web search through a top-level [enable\_search ↗](https://www.alibabacloud.com/help/en/model-studio/qwen-search) flag on a chat completions request. Unlike Anthropic, OpenAI, and xAI, there is no `tools` entry — web search is activated by the flag alone. Supported models — `alibaba/qwen3-max`, `alibaba/qwen3.5-397b-a17b`. Terminal window ``` # Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/chat/completions" \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "model": "alibaba/qwen3-max", "enable_search": true, "max_tokens": 4096, "messages": [ { "role": "user", "content": "What were the top news stories about Cloudflare this week? Summarize in three bullets." } ] }' ``` Equivalent call from a Worker using the AI binding: * [ JavaScript ](#tab-panel-6896) * [ TypeScript ](#tab-panel-6897) JavaScript ``` const resp = await env.AI.run( "alibaba/qwen3-max", { enable_search: true, max_tokens: 4096, messages: [ { role: "user", content: "What were the top news stories about Cloudflare this week? Summarize in three bullets.", }, ], }, { gateway: { id: "default", // or use a specific gateway name }, },); ``` TypeScript ``` const resp = await env.AI.run( "alibaba/qwen3-max", { enable_search: true, max_tokens: 4096, messages: [ { role: "user", content: "What were the top news stories about Cloudflare this week? Summarize in three bullets.", }, ], }, { gateway: { id: "default", // or use a specific gateway name }, },); ``` DashScope does not return search-grounded context as separate tool-call response blocks. It folds the fetched context into the prompt as additional input tokens — expect `prompt_tokens` to increase substantially on a successful search-grounded response. ## Search-first providers For some providers, the primary API is a search endpoint rather than a chat endpoint with a web search tool. AI Gateway exposes them through their existing provider proxy endpoints at `gateway.ai.cloudflare.com`. AI Gateway does not provide a provider-agnostic web search abstraction. Call the provider proxy directly using the patterns below. ### Perplexity Call any [Perplexity Sonar model ↗](https://docs.perplexity.ai/docs/sonar/models) through the [Perplexity provider proxy](https://developers.cloudflare.com/ai-gateway/usage/providers/perplexity/). Terminal window ``` curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/perplexity-ai/chat/completions \ --header "Authorization: Bearer $PERPLEXITY_API_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "model": "sonar", "messages": [ { "role": "user", "content": "What were the top news stories about Cloudflare this week?" } ] }' ``` ### Parallel Call Parallel's Search API through the [Parallel provider proxy](https://developers.cloudflare.com/ai-gateway/usage/providers/parallel/). Refer to Parallel's [Search API documentation ↗](https://docs.parallel.ai/search/search-quickstart) for the full request schema. Terminal window ``` curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/parallel/v1beta/search \ --header "x-api-key: $PARALLEL_API_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "objective": "Top news stories about Cloudflare this week.", "processor": "base", "max_results": 10 }' ``` ## Models without web search support The following models do not accept web search through AI Gateway: * **Google Gemini** — not available through the unified `web_search` tool, because Vertex's OpenAI-compatible surface does not translate it into Gemini's native `googleSearch` tool. To use Gemini grounding, pass the native `google_search` tool to the [provider-specific Vertex endpoint](https://developers.cloudflare.com/ai-gateway/usage/providers/vertex/#using-provider-specific-endpoint). * **Grok chat-completions models** — `xai/grok-4.20-0309-non-reasoning`, `xai/grok-4.20-0309-reasoning`, and `xai/grok-4.3` use the chat-completions endpoint, which does not accept the `web_search` tool. For Grok web search, refer to [xAI web search](#xai-web-search). * **DeepSeek `deepseek-v4-flash`, `deepseek-v4-pro`** — these models accept function tools only. * **MiniMax `m2.7`, `m3`** — these models accept `{ "type": "function" }` tools only. * **OpenAI `gpt-4.1-nano`, `o1-pro`, `o3-mini`** — the upstream returns `invalid_request_error` for `web_search_preview` on these models. * **OpenAI `gpt-4o-search-preview`, `gpt-4o-mini-search-preview`** — these preview models are deprecated upstream. ## Pricing and logging Web search requests are billed at the upstream provider's web-search rates and flow through [Unified Billing](https://developers.cloudflare.com/ai-gateway/features/unified-billing/) along with the rest of the model call. AI Gateway does not charge a separate web-search fee. Web search tool calls and their results are visible in AI Gateway [logs](https://developers.cloudflare.com/ai-gateway/observability/logging/) alongside the rest of the request and response. ## Related resources * [REST API](https://developers.cloudflare.com/ai-gateway/usage/rest-api/) — the four endpoints these examples target * [Workers Bindings](https://developers.cloudflare.com/ai-gateway/usage/worker-binding-methods/) — `env.AI.run` reference * [Anthropic provider](https://developers.cloudflare.com/ai-gateway/usage/providers/anthropic/) * [OpenAI provider](https://developers.cloudflare.com/ai-gateway/usage/providers/openai/) * [Grok (xAI) provider](https://developers.cloudflare.com/ai-gateway/usage/providers/grok/) * [Perplexity provider](https://developers.cloudflare.com/ai-gateway/usage/providers/perplexity/) * [Parallel provider](https://developers.cloudflare.com/ai-gateway/usage/providers/parallel/) * [Unified Billing](https://developers.cloudflare.com/ai-gateway/features/unified-billing/) ```json {"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/ai-gateway/usage/web-search/#page","headline":"Web Search · Cloudflare AI Gateway docs","description":"Use provider-native web search tools through AI Gateway, or reach search-first providers like Perplexity and Parallel through their proxy endpoints.","url":"https://developers.cloudflare.com/ai-gateway/usage/web-search/","inLanguage":"en","image":"https://developers.cloudflare.com/dev-products-preview.png","dateModified":"2026-06-26","publisher":{"@type":"Organization","name":"Cloudflare","url":"https://www.cloudflare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"},"keywords":["AI"]} {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/ai-gateway/","name":"AI Gateway"}},{"@type":"ListItem","position":3,"item":{"@id":"/ai-gateway/usage/","name":"Using AI Gateway"}},{"@type":"ListItem","position":4,"item":{"@id":"/ai-gateway/usage/web-search/","name":"Web Search"}}]} ```