Workers binding

Workers provides a serverless execution environment that allows you to create new applications or augment existing ones. Use a Workers binding to create, list, update, and delete AI Search instances from a Cloudflare Worker. You can also check instance configuration and monitor indexing progress.

To use AI Search with Workers, you must create an AI Search binding. You create bindings by updating your Wrangler configuration. AI Search provides two types of bindings:

• Namespace binding: ai_search_namespaces
• Instance binding: ai_search

Access all instances within a namespace. You can get, create, list, and delete instances at runtime.

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "compatibility_date": "2026-03-27",
  "ai_search_namespaces": [
    {
      "binding": "AI_SEARCH",
      "namespace": "my-namespace"
    }
  ]
}

compatibility_date = "2026-03-27"

[[ai_search_namespaces]]
binding = "AI_SEARCH"
namespace = "my-namespace"

Bind directly to a single instance in the default namespace. Use this when you know which instance you need at deploy time.

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "compatibility_date": "2026-03-27",
  "ai_search": [
    {
      "binding": "MY_SEARCH",
      "instance_name": "my-instance"
    }
  ]
}

compatibility_date = "2026-03-27"

[[ai_search]]
binding = "MY_SEARCH"
instance_name = "my-instance"

The following methods are only available when using the ai_search_namespaces binding. The namespace handle (env.AI_SEARCH) exposes methods for working with instances within a namespace.

Returns a handle to a specific instance. This is synchronous and does not make a network call. The instance is resolved lazily when you call methods like search() or info().

const instance = env.AI_SEARCH.get("my-instance");
const results = await instance.search({
	messages: [{ role: "user", content: "What is Cloudflare?" }],
});

Returns all instances within the namespace.

const { result, result_info } = await env.AI_SEARCH.list();

for (const instance of result) {
	console.log(`${instance.id} (${instance.type}) - ${instance.status}`);
}
// result_info.total_count contains the total number of instances

Creates a new instance and returns a handle to it. You can create instances backed by a data source or create empty instances for use with the Items API.

Create an empty instance for file uploads:

AI Search instances come with built-in storage where you can upload documents directly.

const instance = await env.AI_SEARCH.create({
	id: "knowledge-base",
});

// Upload documents using the Items API
await instance.items.upload("guide.pdf", pdfArrayBuffer);

Create a web-crawler instance:

Automatically crawl and index a website that you own. For more configuration options, refer to Website data source.

const instance = await env.AI_SEARCH.create({
	id: "my-docs",
	type: "web-crawler",
	source: "developers.cloudflare.com",
});

Create an R2-backed instance:

Index documents stored in an R2 bucket. For more configuration options, refer to R2 data source.

const instance = await env.AI_SEARCH.create({
	id: "internal-docs",
	type: "r2",
	source: "my-docs-bucket",
});

id stringrequired

The unique identifier for the AI Search instance. Must be 1-64 characters and match the pattern ^[a-z0-9_]+(?:-[a-z0-9_]+)*$.

type stringoptional

The type of data source. Valid values: r2, web-crawler. Required when creating an instance with a data source. Omit when creating an empty instance for use with the Items API.

source stringoptional

The data source location. For r2 type, this is the R2 bucket name. For web-crawler type, this is the website domain. Required when type is specified.

source_params objectoptional

Additional parameters for the data source.

• prefix stringoptional
  • For R2 sources, limits indexing to objects with this key prefix.
• r2_jurisdiction stringoptional
  • The jurisdiction for the R2 bucket, for example eu.
• include_items arrayoptional
  • Glob patterns for paths to include in indexing. For example: ["/blog/**", "/docs/**/*.html"].
• exclude_items arrayoptional
  • Glob patterns for paths to exclude from indexing. For example: ["/admin/**", "/private/**"].
• web_crawler objectoptional
  • Configuration for web crawler sources.
  • parse_type stringoptional
    • How pages are discovered. Valid values: sitemap (reads XML sitemaps), discover (starts at the source URL and, by default, uses both sitemaps and links found on crawled pages). Defaults to sitemap. Refer to Parse types.
  • parse_options objectoptional
    • include_headers objectoptional
      • Custom HTTP headers to include when crawling.
    • include_images booleanoptional
      • Whether to include images in the index.
    • specific_sitemaps arrayoptional
      • Specific sitemap URLs to crawl. For example: ["https://example.com/sitemap.xml"]. Only valid when parse_type is sitemap.
    • use_browser_rendering booleanoptional
      • Use Browser Run (formerly Browser Rendering) to crawl JavaScript-rendered pages.
  • discover_options objectoptional
    • Crawl settings that apply when parse_type is discover.
    • source stringoptional
      • Where the crawler looks for candidate URLs. Valid values: all, sitemaps, links. Defaults to all.
    • limit numberoptional
      • Maximum number of pages to crawl. Valid values: 1 to 100000. Defaults to 100000.
    • depth numberoptional
      • Maximum number of link hops to follow from the source URL. Valid values: 1 to 100000. Defaults to 5.
    • max_age numberoptional
      • How long, in seconds, the crawler reuses cached page content before it re-fetches from the origin. Valid values: 0 to 604800. Defaults to 86400.
    • include_external_links booleanoptional
      • Whether to follow links that point to other domains. Defaults to false.
    • include_subdomains booleanoptional
      • Whether to follow links that point to subdomains of the source URL. Defaults to false.
  • store_options objectoptional
    • storage_type stringoptional
      • The storage type. Valid value: r2.
    • storage_id stringoptional
      • The storage bucket ID.
    • r2_jurisdiction stringoptional
      • The jurisdiction for the storage bucket.

index_method objectoptional

Configures which indexing methods are enabled for the instance. Determines whether vector (semantic) search, keyword search, or both are available. At least one must be true.

• vector booleanoptional
  • Enable vector-based semantic search. Defaults to true.
• keyword booleanoptional
  • Enable keyword-based search. Defaults to false.

Set both to true for hybrid search.

fusion_method stringoptional

Controls how vector and keyword scores are combined when using hybrid search. Valid values: rrf (Reciprocal Rank Fusion), max (takes the maximum score). Defaults to rrf.

indexing_options objectoptional

Configuration for how content is indexed.

• keyword_tokenizer stringoptional
  • The tokenizer used for keyword search indexing. Valid values: porter (stemming-based), trigram (character n-gram). Defaults to porter.

retrieval_options objectoptional

Default retrieval configuration for the instance. These defaults can be overridden per-request using ai_search_options.

• keyword_match_mode stringoptional
  • 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 arrayoptional
  • Default boost fields applied to all search queries. Maximum 3 items. Each item has:
    • field stringrequired - The metadata field name to boost by. Maximum 64 characters.
    • direction stringoptional - The boost direction. Valid values: asc, desc, exists, not_exists.

sync_interval numberoptional

Seconds between automatic data source syncs. Valid values: 3600, 7200, 14400, 21600, 43200, 86400. Defaults to 21600 (6 hours).

token_id stringoptional

The UUID of the service API token to use for this instance. Only required if you have never created an AI Search instance before. Refer to the API get started guide for how to create and register a service token.

ai_gateway_id stringoptional

The AI Gateway ID to route requests through for logging and analytics.

embedding_model stringoptional

The embedding model to use for vectorizing content.

ai_search_model stringoptional

The text-generation model to use for generating responses.

rewrite_query booleanoptional

Enable query rewriting to improve retrieval accuracy. Defaults to false.

rewrite_model stringoptional

The model to use for query rewriting.

reranking booleanoptional

Enable reranking to reorder retrieved results by semantic relevance. Defaults to false.

reranking_model stringoptional

The reranking model to use. Valid value: @cf/baai/bge-reranker-base.

chunk_size numberoptional

The size of chunks when splitting documents. Minimum value: 64.

chunk_overlap numberoptional

The overlap between chunks. Minimum value: 0.

max_num_results numberoptional

The default maximum number of results to return. Minimum value: 1.

score_threshold numberoptional

The default minimum score threshold for results. Minimum value: 0.

cache booleanoptional

Enable response caching. Defaults to true.

cache_threshold stringoptional

The cache matching threshold. Valid values: super_strict_match, close_enough, flexible_friend, anything_goes. Defaults to close_enough.

cache_ttl numberoptional

The cache entry TTL in seconds. Valid values are 600, 1800, 3600, 7200, 21600, 43200, 86400, 172800, 259200, and 518400. Defaults to 172800.

custom_metadata arrayoptional

Custom metadata fields to extract and index from documents.

• field_name stringrequired
  • The name of the metadata field.
• data_type stringrequired
  • The data type of the field. Valid values: text, number, boolean, datetime.

enable booleanoptional

Whether the instance is enabled. Defaults to true.

Returns an AiSearchInstance handle that is immediately usable for calling methods like search(), info(), stats(), and items.upload(). Call info() on the handle to get the instance configuration.

Permanently deletes an instance and all its indexed content. This action cannot be undone.

await env.AI_SEARCH.delete("old-docs");

Returns void. Throws an error if the instance does not exist.

The following methods are available on both the ai_search_namespaces and ai_search bindings. With the namespace binding, call methods on the handle returned by get(). With the instance binding, call methods directly on the binding (for example, env.MY_SEARCH.info()).

The examples below use the namespace binding.

Partially updates the instance configuration. Only the fields you pass are modified.

const updated = await env.AI_SEARCH.get("my-instance").update({
	ai_search_model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
	reranking: true,
});

Accepts a partial version of the create parameters. Only the fields you include are updated.

Returns the updated instance configuration. Same shape as info().

Returns the current configuration and metadata for the instance.

const info = await env.AI_SEARCH.get("my-instance").info();

Returns the current indexing progress for the instance. Use this to poll for completion after creating an instance or uploading files.

const stats = await env.AI_SEARCH.get("my-instance").stats();

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,
		},
	],
}