Workers binding (7)·续

model string optional

The text-generation model used to generate responses. Defaults to the generation model configured in the AI Search instance settings. For a list of supported models, refer to Supported models.

stream boolean optional

Returns a stream of results as they are generated. When enabled, returns a Response object with a readable stream. Defaults to false.

ai_search_options object optional

Configuration options for the search and generation operation.

• custom_metadata object optional
• Adds up to two string, number, or boolean entries to AI Gateway logs. The keys ai-search, task, origin, and keys beginning with cf. are reserved.
• retrieval object optional
• retrieval_type string optional
  • The type of retrieval to perform. Valid values: vector, keyword, hybrid. Defaults to hybrid.
• match_threshold number optional
  • The minimum match score required for a result to be considered a match. Must be between 0 and 1. Defaults to 0.4.
• max_num_results integer optional
  • The maximum number of results to return. Must be between 1 and 50. Defaults to 10.
• filters object optional
  • Filter search results based on metadata. Supports comparison filters ( eq, ne, gt, gte, lt, lte) and compound filters ( and, or). For more details, refer to Metadata filtering.
• context_expansion integer optional
  • The number of surrounding chunks to include for additional context. Must be between 0 and 3. Defaults to 0.
• fusion_method string optional
  • Controls how vector and keyword scores are combined when using hybrid retrieval. Valid values: rrf (Reciprocal Rank Fusion), max (takes the maximum score). Defaults to the instance-level setting.
• keyword_match_mode string optional
  • Controls how keyword (BM25) matching selects candidate documents. and requires all terms to match. or requires any term to match. Defaults to and.
• boost_by array optional
  • Boost results by metadata fields. Maximum 3 items. Each item has:
  • field string required - The metadata field name to boost by (for example, timestamp). Maximum 64 characters.
  • direction string optional - The boost direction. Valid values: asc, desc, exists, not_exists. Defaults to asc for numeric fields and exists for text fields.
• metadata_only boolean optional
  • Return only metadata for each chunk without the text content.
• return_on_failure boolean optional
  • Whether to return partial results if some processing steps fail. Defaults to true.
• query_rewrite object optional
• enabled boolean optional
  • Rewrites the query to improve retrieval accuracy. Defaults to false.
• model string optional
  • The model to use for query rewriting.
• rewrite_prompt string optional
  • A custom prompt to guide query rewriting.
• reranking object optional
• enabled boolean optional
  • Reorders retrieved results based on semantic relevance using a reranking model. Defaults to false.
• model string optional
  • The reranking model to use. Valid value: @cf/baai/bge-reranker-base.
• match_threshold number optional
  • The minimum score for reranked results. Must be between 0 and 1. Defaults to 0.4.
• cache object optional
• enabled boolean optional
  • Override the instance-level cache setting for this request.
• cache_threshold string optional
  • The similarity threshold for cache hits. Valid values: super_strict_match, close_enough, flexible_friend, anything_goes.

Response (non-streaming)

Response (streaming)

When stream: true, the method returns a ReadableStream of Server-Sent Events. The retrieved chunks are sent first as a chunks event, followed by the streamed response.

event: chunks
data: [{"id":"chunk-001","type":"text","score":0.85,"text":"...","item":{"key":"about-cloudflare.md","timestamp":1775925540000},"scoring_details":{"vector_score":0.85}}]

data: {"id":"id-1776072781845","created":1776072781,"model":"@cf/meta/llama-3.3-70b-instruct-fp8-fast","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" document"}}]}

data: {"id":"id-1776072781845","created":1776072781,"model":"@cf/meta/llama-3.3-70b-instruct-fp8-fast","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" you provided doesn"}}]}

data: {"id":"id-1776072781845","created":1776072781,"model":"@cf/meta/llama-3.3-70b-instruct-fp8-fast","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"'t contain"}}]}

data: {"id":"id-1776072781845","created":1776072781,"model":"@cf/meta/llama-3.3-70b-instruct-fp8-fast","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" information"}}]}

data: [DONE]

Namespace methods

The following methods are only available when using the ai_search_namespaces binding. Search and chat across multiple instances in a single call using the namespace handle directly (env.AI_SEARCH).

search()

Pass instance_ids in ai_search_options to specify which instances to query. Results are merged and ranked, and each chunk includes an instance_id field identifying which instance it came from.

const results = await env.AI_SEARCH.search({
    messages: [{ role: "user", content: "What is Cloudflare?" }],
    ai_search_options: {
        instance_ids: ["product-docs", "customer-abc123"],
    },
});

Parameters

Same as instance-level search, with one additional required field:

Response

Same as instance-level search, with additional fields:

chatCompletions()

Generate chat completions using context retrieved from multiple instances.

const response = await env.AI_SEARCH.chatCompletions({
    messages: [{ role: "user", content: "What is Cloudflare?" }],
    ai_search_options: {
        instance_ids: ["product-docs", "customer-abc123"],
    },
});

Streaming is supported with stream: true.

Parameters

Same as instance-level chat completions, with one additional required field:

Response

Same as instance-level chat completions, with additional fields on each chunk:

Local development

Local development is supported by proxying requests to your deployed AI Search instance. Add remote: true to your binding configuration to enable local development with wrangler dev.

// wrangler.jsonc
{
    "ai_search": [
        {
            "binding": "MY_SEARCH",
            "instance_name": "my-instance",
            "remote": true,
        },
    ],
}

Was this helpful?

YesNo

On this page

Docs

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/ai-search/api/search/workers-binding/#page","headline":"Workers binding","description":"Search and chat with AI Search instances from a Cloudflare Worker using the Workers binding.","url":"https://developers.cloudflare.com/ai-search/api/search/workers-binding/","inLanguage":"en","image":"https://developers.cloudflare.com/ai-search/api/search/workers-binding/og.png?v=fa78d292a041eecc","dateModified":"2026-10-01","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Send and query unlimited-cardinality analytics from Workers. title: Workers Analytics Engine image: https://developers.cloudflare.com/analytics/analytics-engine/og.png?v=dfb72c4220270535

Skip to content

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/analytics/llms.txt
Use this file to discover all available pages before exploring further.