Workers binding

import { Render, MetaInfo, Type } from "~/components";

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.

Configure the binding

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

Response

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.

delete()

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

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

Parameters

Response

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

:::caution Deleting an instance permanently removes all indexed data, including embeddings, chunks, and source files. :::

Instance methods

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.

update()

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

Parameters

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

Response

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

info()

Returns the current configuration and metadata for the instance.

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

Response

stats()

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();

Response

Jobs methods

Use the jobs property on an instance handle to manage indexing jobs.

jobs.list()

Returns a paginated list of jobs. Pass optional page and per_page values.

const jobs = await env.AI_SEARCH.get("my-instance").jobs.list({
	page: 1,
	per_page: 20,
});

jobs.create()

Starts an indexing job. The optional description can contain up to 255 characters.

const job = await env.AI_SEARCH.get("my-instance").jobs.create({
	description: "Index updated content",
});

jobs.get().info()

Returns one job by ID.

const job = await env.AI_SEARCH.get("my-instance")
	.jobs.get("job-id-123")
	.info();

Job objects contain id, source, and optional description, last_seen_at, started_at, ended_at, and end_reason fields. The source is user or schedule.

jobs.get().cancel()

Cancels a job and returns the updated job object.

const job = await env.AI_SEARCH.get("my-instance")
	.jobs.get("job-id-123")
	.cancel();

jobs.get().logs()

Returns paginated logs for a job. Pass optional page and per_page values.

const logs = await env.AI_SEARCH.get("my-instance")
	.jobs.get("job-id-123")
	.logs({ page: 1, per_page: 20 });

Each log contains id, message, message_type, and created_at. The response includes result_info pagination metadata.

:::note The configured AI Gateway receives generation, query rewriting, and external-provider requests. Workers AI embedding and reranking requests run under AI Search and do not appear in your AI Gateway logs or Workers AI bill. :::

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