How to use Web Search API

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.

• 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.

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" }
    }
  }'

Call Web Search API from a Worker with the websearch() method on the AI binding.

websearch() returns a standard Response object. Call response.json() to read the results.

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,
});

{
	"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": "<REQUEST_ID>",
		"latencyMs": 612
	}
}

Optional fields are only included when the provider returns them.

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.

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.

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<Response> {
		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<Env>;