Web Search

Agent-ready web search from a Cloudflare Worker: call the Web Search API through AI Gateway using Ceramic, Exa, or Linkup providers. Use it when an agent needs live search results without wiring each search vendor separately.

API ReferenceCopy Anchor Link

POST /searchCopy Anchor Link

Search the web via AI Gateway's Web Search API integration.

Request body

{
  "query": "cloudflare workers edge computing",
  "provider": "ceramic",
  "limit": 5
}

Fields

• query string (required) - Search query
• provider string (optional) - Search provider: ceramic, exa, or linkup. Defaults to ceramic
• limit number (optional) - Maximum results to return. Defaults to 5

Example request

curl -X POST https://web-search.example.workers.dev/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "cloudflare workers edge computing",
    "provider": "ceramic",
    "limit": 5
  }'

Example response

{
  "query": "cloudflare workers edge computing",
  "provider": "ceramic",
  "limit": 5,
  "results": [
    {
      "url": "https://workers.cloudflare.com",
      "title": "Cloudflare Workers",
      "snippet": "Deploy serverless code instantly across the globe..."
    }
  ]
}

Error responses

• 400 - Invalid JSON, missing query, or invalid provider
• 502 - Web Search API error

Error codes

• INVALID_JSON - Request body is not valid JSON
• INVALID_REQUEST - Missing or invalid query field
• INVALID_PROVIDER - Provider is not one of: ceramic, exa, linkup
• SEARCH_ERROR - Web Search API returned an error

Use CasesCopy Anchor Link

• Building AI chat agents with web search capabilities
• Research tools that need current web data
• Content discovery and aggregation workflows
• Search-augmented generation (RAG) pipelines
• Educational demos of multi-provider search APIs

LimitationsCopy Anchor Link

• Requires AI Gateway configuration (account ID and gateway ID)
• Web Search API is in beta (Oct 2 2026) - availability and limits may change
• Results limited by the provider's capabilities and coverage
• No persistent storage or search history
• Rate limits determined by AI Gateway and search provider quotas

Use in your projectCopy Anchor Link

export type SearchProvider = "ceramic" | "exa" | "linkup";export type SearchOptions = {  query: string;  provider?: SearchProvider;  limit?: number;  accountId: string;  gatewayId: string;};export async function searchWeb({  query,  provider = "ceramic",  limit = 5,  accountId,  gatewayId,}: SearchOptions): Promise<unknown> {  const gatewayUrl = `https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/web-search/${provider}`;  const response = await fetch(gatewayUrl, {    method: "POST",    headers: {      "Content-Type": "application/json",    },    body: JSON.stringify({      query,      limit,    }),  });  if (!response.ok) {    const errorText = await response.text();    throw new Error(`Web Search API error: ${response.status} ${errorText}`);  }  return response.json();}

DeploymentCopy Anchor Link

{
  "vars": {
    "AI_GATEWAY_ACCOUNT_ID": "your-account-id",
    "AI_GATEWAY_ID": "your-gateway-id"
  }
}

curl -X POST https://web-search.your-subdomain.workers.dev/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "cloudflare workers",
    "provider": "ceramic",
    "limit": 5
  }'

Local DevelopmentCopy Anchor Link

cd apps/experiments/web-search
npm install
npm run dev

The Worker runs at http://localhost:8787 with --remote for Web Search API access.

Test locally

curl -X POST http://localhost:8787/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "cloudflare workers",
    "provider": "ceramic"
  }'

ConfigurationCopy Anchor Link

Environment VariablesCopy Anchor Link

• AI_GATEWAY_ACCOUNT_ID - Your Cloudflare account ID
• AI_GATEWAY_ID - Your AI Gateway ID

Set these in wrangler.json under vars or as secrets via the Cloudflare dashboard.

Cloudflare Features UsedCopy Anchor Link

• Workers - Edge compute platform
• AI Gateway - Unified API gateway for AI services
• Web Search API (Oct 2026 beta) - Search the web via ceramic, exa, or linkup providers

Next StepsCopy Anchor Link