Workers binding (3)

Last updated Oct 1, 2026 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.

Configure the binding

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

Namespace binding

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"

Instance binding

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"

Namespace methods

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.

get()

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

Parameters

list()

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

Parameters

Response

create()

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", pdfBlob);

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

Parameters

id string required

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

type string optional

The type of data source. Valid values: r2 or web-crawler. If omitted, an HTTP(S) URL source selects web-crawler, an existing R2 bucket selects r2, and a missing or blank source creates an instance with built-in storage. Other sources return error 7111. The REST API also accepts null, which behaves like an omitted value. The Workers binding does not accept null.

source string optional

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 object optional

Additional parameters for the data source.

• prefix string optional
• For R2 sources, limits indexing to objects with this key prefix.
• r2_jurisdiction string optional
• The jurisdiction for the R2 bucket, for example eu.
• include_items array optional
• Glob patterns for paths to include in indexing. For example: ["/blog/**", "/docs/**/*.html"].
• exclude_items array optional
• Glob patterns for paths to exclude from indexing. For example: ["/admin/**", "/private/**"].
• web_crawler object optional
• Configuration for web crawler sources.
• parse_type string optional
  • 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 object optional
  • include_headers object optional
  • Custom HTTP headers to include when crawling.
  • include_images boolean optional
  • Whether to include images in the index.
  • specific_sitemaps array optional
  • Specific sitemap URLs to crawl. For example: ["https://example.com/sitemap.xml"]. Only valid when parse_type is sitemap.
  • use_browser_rendering boolean optional
  • Use Browser Run (formerly Browser Rendering) to crawl JavaScript-rendered pages.
• discover_options object optional
  • Crawl settings that apply when parse_type is discover.
  • source string optional
  • Where the crawler looks for candidate URLs. Valid values: all, sitemaps, links. Defaults to all.
  • limit number optional
  • Maximum number of pages to crawl. Valid values: 1 to 100000. Defaults to 100000.
  • depth number optional
  • Maximum number of link hops to follow from the source URL. Valid values: 1 to 100000. Defaults to 5.
  • max_age number optional
  • 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 boolean optional
  • Whether to follow links that point to other domains. Defaults to false.
  • include_subdomains boolean optional
  • Whether to follow links that point to subdomains of the source URL. Defaults to false.
• store_options object optional
  • storage_type string optional
  • The storage type. Valid value: r2.
  • storage_id string optional
  • The storage bucket ID.
  • r2_jurisdiction string optional
  • The jurisdiction for the storage bucket.

index_method object optional

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 boolean optional
• Enable vector-based semantic search. Defaults to true.
• keyword boolean optional
• Enable keyword-based search. Defaults to true.

Set both to true for hybrid search.

fusion_method string optional

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 object optional

Configuration for how content is indexed.

• keyword_tokenizer string optional
• The tokenizer used for keyword search indexing. Valid values: porter (stemming-based), trigram (character n-gram). Defaults to porter.
• use_ocr boolean optional
• Use optical character recognition (OCR) when ingesting PDFs and images. Defaults to false. OCR is available on every account and is billed as image-processing ingestion tokens.

retrieval_options object optional

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

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

sync_interval number optional

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

token_id string optional

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.