Cloudflare Web Search API: búsqueda web para tus agentes de IA desde AI Gateway

La Web Search API de Cloudflare es un endpoint que le da búsqueda web a tus agentes y aplicaciones de IA: mandas una query y recibes resultados con URL, título y descripción, listos para meter en el contexto del modelo. Corre sobre AI Gateway, se llama por REST o desde un Worker con env.AI.websearch(), y está en beta abierta desde el 2 de octubre de 2026.

El problema que ataca lo describe la propia documentación: sin búsqueda, un agente que necesita información actual adivina la URL de una página y la pide directamente. Si adivina mal, recibe un 404 Not Found y vuelve a intentar. Con la API, el agente hace lo mismo que una persona: empieza por un buscador.

Qué es la Web Search API de Cloudflare

No es un buscador propio de Cloudflare. Es una capa delante de tres proveedores de búsqueda pensados para IA, con un formato de respuesta común. Cuando mandas una búsqueda, la API:

1. Pasa la petición por el AI Gateway que indiques.
2. Reenvía la query al proveedor que elegiste: Ceramic.ai, Exa o Linkup. Si no eliges ninguno, usa Ceramic.ai.
3. Normaliza la respuesta del proveedor: URL y título siempre, y si el proveedor los devuelve, descripción, imagen, favicon y fecha de última modificación.
4. Registra la petición en los logs de tu gateway y te la cobra.

Como los tres devuelven el mismo formato, cambiar de proveedor es cambiar un parámetro.

Que viva en AI Gateway es la parte interesante si ya lo usas para inferencia: las búsquedas aparecen en los mismos logs y analytics que las llamadas al modelo, se pagan con el mismo saldo de créditos y pasan por los mismos controles de acceso.

Proveedores y precios: Ceramic.ai, Exa y Linkup

Con créditos de AI Gateway, cada búsqueda se cobra al precio de lista del proveedor, sin recargo de Cloudflare. Estos son los datos de la página de proveedores de la documentación:

Cada uno tiene su perfil, según la misma documentación:

• Ceramic.ai tiene un índice propio de más de 40.000 millones de páginas, pensado para agentes y no para personas. Apunta a baja latencia y bajo costo, y sus descripciones llegan hasta 8.000 caracteres por página. Encaja con agentes que hacen muchas búsquedas por tarea.
• Exa combina búsqueda por palabras clave con búsqueda por embeddings. Devuelve como descripción los highlights, los fragmentos de la página más relevantes para la query, así que sirve cuando quieres pasar extractos cortos directo al contexto.
• Linkup se usa en modo fast y con resultados crudos: devuelve resultados con fuente sin generar una respuesta. Encaja con tool calls que necesitan resultados citados rápido.

Sobre Zero Data Retention hay una contradicción. El changelog del lanzamiento dice que los tres proveedores soportan ZDR para las peticiones que llegan desde Cloudflare; la tabla de la página de proveedores marca a Exa con "No". Si la retención de datos importa en tu caso, usa Ceramic.ai o Linkup hasta que Cloudflare lo aclare.

Requisitos

• Una cuenta de Cloudflare.
• Un AI Gateway. Toda cuenta trae uno llamado default.
• Créditos de AI Gateway cargados, o la API key de un proveedor guardada en el gateway.

Cómo usar la Web Search API con REST

El endpoint es un POST por cuenta:

POST https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/websearch/

Necesitas un API token de Cloudflare con dos permisos: Account > Workers AI > Read y 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": "novedades de Laravel 13",
    "provider": "ceramic",
    "limit": 5,
    "options": {
      "gateway": { "id": "default" }
    }
  }'

Los parámetros:

La respuesta:

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

Los campos opcionales de cada resultado solo aparecen cuando el proveedor los devuelve.

Web Search API en Cloudflare Workers: env.AI.websearch()

Desde un Worker no hace falta token: se usa el binding de Workers AI. Primero, el binding en wrangler.jsonc:

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "web-search-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-10-04",
  "ai": {
    "binding": "AI"
  }
}

Y después la llamada, con el ID del gateway en gatewayId:

export default {
  async fetch(request, env): Promise<Response> {
    const response = await env.AI.websearch({
      gatewayId: "default",
      query: "novedades de Laravel 13",
      provider: "exa",
      limit: 5,
    });
 
    const results = await response.json();
    return Response.json(results);
  },
} satisfies ExportedHandler<Env>;

websearch() devuelve un Response estándar, así que hay que llamar a response.json() para leer los resultados.

Usar web search como tool del modelo

Lo normal no es buscar a mano sino dejar que el modelo decida cuándo buscar. Hoy eso se arma en dos vueltas: defines una tool web_search, el modelo la pide, tú corres la búsqueda y le devuelves los resultados. Este ejemplo sale de la documentación de Cloudflare y usa Gemma en Workers AI:

const MODEL = "@cf/google/gemma-4-26b-a4b-it";
 
export default {
  async fetch(request, env): Promise<Response> {
    const messages = [
      { role: "user", content: "What happened during the last Cloudflare Birthday Week?" },
    ];
 
    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>;

El anuncio del blog adelanta que Cloudflare está construyendo Server Tools nativas dentro de AI Gateway, para que no tengas que definir ni orquestar la tool tú mismo. Todavía no tienen fecha.

Usar tu propia API key (BYOK)

Si ya tienes cuenta con Ceramic.ai, Exa o Linkup, puedes usar tu key y que el proveedor te cobre directo:

1. En el dashboard, entra a AI Gateway, elige tu gateway y ve a Provider Keys.
2. Agrega la key del proveedor y ponle un alias, por ejemplo default.
3. Manda el provider y el byokAlias en la petición.

const response = await env.AI.websearch({
  gatewayId: "default",
  query: "What is Cloudflare Workers?",
  provider: "exa",
  byokAlias: "default",
});

La key nunca viaja en la petición: AI Gateway la busca en el gateway, donde se guarda cifrada con Secrets Store. La regla de qué credencial usa tiene un detalle que conviene saber:

• Con byokAlias, usa esa key. Si el alias o el proveedor no están configurados, la petición falla con un 400; no cae a tus créditos.
• Sin byokAlias, usa la key con alias default de ese proveedor si existe. Si no, cobra la búsqueda a tus créditos de AI Gateway.

Es decir: si guardas una key con alias default, las búsquedas a ese proveedor dejan de cobrarse en créditos aunque no pases ningún alias.

Los proveedores y los dueños de sitios

Cloudflare exige a los tres proveedores dos compromisos: que su crawler cumpla los requisitos de verified bots, lo que incluye identificarse y respetar robots.txt, y que cada resultado enlace a la fuente. Encaja con lo que Cloudflare viene empujando del lado de los publishers, como el Monetization Gateway para cobrarle a los agentes por el contenido.

Límites

Preguntas frecuentes

Fuentes

• Changelog: Introducing Web Search API
• Introducing Web Search API via AI Gateway, blog de Cloudflare
• Documentación de Web Search API
• About Web Search API
• How to use Web Search API
• Providers
• AI Gateway