Workers binding (3)·续

Workers binding (3)·续

ai_gateway_id string optional

The AI Gateway ID for generation, query rewriting, and external-provider requests. Workers AI embedding and reranking usage is included in AI Search usage. These requests do not appear in your AI Gateway logs or Workers AI bill.

embedding_model string optional

The embedding model to use for vectorizing content.

ai_search_model string optional

The text-generation model to use for generating responses.

rewrite_query boolean optional

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

rewrite_model string optional

The model to use for query rewriting.

reranking boolean optional

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

reranking_model string optional

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

chunk_size number optional

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

chunk_overlap number optional

The overlap between chunks. Minimum value: 0.

max_num_results number optional

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

score_threshold number optional

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

cache boolean optional

Enable response caching. Defaults to true.

cache_threshold string optional

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

cache_ttl number optional

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

Custom metadata fields to extract and index from documents.

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

enable boolean optional

Whether the instance is enabled. Defaults to true.

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

Parameter	Type	Required	Description
`name`	string	Yes	The name of the instance to delete.

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.

Field	Type	Description
`ai_search_model`	string	The text-generation model.
`embedding_model`	string	The embedding model.
`index_method`	object	Indexing methods: `\{ vector: boolean, keyword: boolean \}`.
`fusion_method`	string	How vector and keyword scores are combined (`rrf` or `max`).
`indexing_options`	object	Indexing configuration including `keyword_tokenizer` and `use_ocr`.
`retrieval_options`	object	Retrieval configuration including `keyword_match_mode` and `boost_by`.
`reranking`	boolean	Turn on or off reranking.
`reranking_model`	string	The reranking model.
`rewrite_query`	boolean	Turn on or off query rewriting.
`rewrite_model`	string	The query rewriting model.
`source`	string	Update the data source location.
`cache`	boolean	Turn on or off response caching.
`cache_ttl`	number	Cache entry time to live in seconds.
`chunk_size`	number	Token size of each chunk.
`chunk_overlap`	number	Token overlap between chunks.
`score_threshold`	number	Minimum score threshold for results.
`max_num_results`	number	Maximum number of results per query.
`custom_metadata`	array	Custom metadata field definitions.
`sync_interval`	number	Seconds between automatic data source syncs.

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

Field	Type	Description
`id`	string	The instance identifier.
`type`	string	The data source type (`r2`, `web-crawler`, or `null`).
`source`	string	The data source location.
`namespace`	string	The namespace the instance belongs to.
`status`	string	The current indexing lifecycle status, such as `waiting`, `index_source`, `embed_files`, or a `paused_*` status.
`paused`	boolean	Whether indexing is paused.
`created_at`	string	Timestamp of when the instance was created.
`modified_at`	string	Timestamp of the last modification.
`ai_search_model`	string	The text-generation model.
`embedding_model`	string	The embedding model.
`reranking`	boolean	Whether reranking is enabled.
`reranking_model`	string	The reranking model.
`rewrite_query`	boolean	Whether query rewriting is enabled.
`rewrite_model`	string	The query rewriting model.
`cache`	boolean	Whether response caching is enabled.
`cache_threshold`	string	The similarity threshold for cache hits.
`cache_ttl`	number	Cache entry time to live in seconds.
`index_method`	object	Which indexing methods are enabled (`vector`, `keyword`).
`fusion_method`	string	How vector and keyword scores are combined (`rrf` or `max`).
`indexing_options`	object	Indexing configuration including `keyword_tokenizer` and `use_ocr`.
`retrieval_options`	object	Retrieval configuration including `keyword_match_mode` and `boost_by`.
`chunk_size`	number	Token size of each chunk.
`chunk_overlap`	number	Token overlap between chunks.
`score_threshold`	number	Minimum score threshold for results.
`max_num_results`	number	Maximum number of results per query.
`sync_interval`	number	Seconds between automatic data source syncs.
`custom_metadata`	array	Custom metadata field definitions.
`last_activity`	string	Timestamp of the last indexing activity.

`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

Field	Type	Description
`queued`	number	Items waiting to be processed.
`running`	number	Items currently being processed.
`completed`	number	Items successfully indexed.
`error`	number	Items that failed to index.
`skipped`	number	Items skipped during indexing.
`outdated`	number	Items that need re-indexing.
`last_activity`	string	ISO 8601 timestamp of the last indexing activity.
`file_embed_errors`	object	Map of file IDs to embedding error details.
`engine.vectorize.vectorsCount`	number	Total number of vectors stored.
`engine.vectorize.dimensions`	number	Dimensions of the vector embeddings.
`engine.r2.payloadSizeBytes`	number	Total size of stored payloads in bytes.
`engine.r2.metadataSizeBytes`	number	Total size of stored metadata in bytes.
`engine.r2.objectCount`	number	Total number of objects in storage.

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

Was this helpful?

YesNo

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/ai-search/api/instances/workers-binding/#page","headline":"Workers binding","description":"Manage AI Search instances from a Cloudflare Worker using the Instances Workers binding.","url":"https://developers.cloudflare.com/ai-search/api/instances/workers-binding/","inLanguage":"en","image":"https://developers.cloudflare.com/ai-search/api/instances/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: Upload, list, and manage documents in AI Search instances using the Items REST API. title: REST API image: https://developers.cloudflare.com/ai-search/api/items/rest-api/og.png?v=2130d71799ac2da7

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

Workers binding (3)·续

Workers binding (3)·续

Response

delete()

Parameters

Response

Instance methods

update()

Parameters

Response

info()

Response

stats()

Response

Jobs methods

jobs.list()

jobs.create()

jobs.get().info()

jobs.get().cancel()

jobs.get().logs()

Local development

On this page

`delete()`

`update()`

`info()`

`stats()`

`jobs.list()`

`jobs.create()`

`jobs.get().info()`

`jobs.get().cancel()`

`jobs.get().logs()`