--- title: Multi-Instance Search --- [Skip to content](#_top) [API Reference](https://developers.cloudflare.com/api/typescript) [AI Search](https://developers.cloudflare.com/api/typescript/resources/ai_search) [Namespaces](https://developers.cloudflare.com/api/typescript/resources/ai_search/subresources/namespaces) Copy Markdown Open in **Claude**Open in **ChatGPT**Open in **Cursor** --- **Copy Markdown****View as Markdown** # Multi-Instance Search client.aiSearch.namespaces.search(stringname, NamespaceSearchParams {account\_id, ai\_search\_options, messages, query } params, RequestOptionsoptions?): [NamespaceSearchResponse]() {chunks, query\_kind, errors, search\_query } POST/accounts/{account\_id}/ai-search/namespaces/{name}/search Performs a semantic search query against multiple AI Search instances in parallel, merging the retrieved results into a single ranked response. ##### Security
API Token The preferred authorization scheme for interacting with the Cloudflare API. Create a token. **Example:**Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY
API Email + API Key The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key. **Example:**X-Auth-Email: user@example.com The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys. **Example:**X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194
##### ParametersExpand Collapse name: string [Link to this property](<#(resource)%20ai_search.namespaces%20%3E%20(method)%20search%20%3E%20(params)%20default%20%3E%20(param)%20name%20%3E%20(schema)>)
params: NamespaceSearchParams {account\_id, ai\_search\_options, messages, query } account\_id: string Path param Link to this property
ai\_search\_options: AISearchOptions Body param instance\_ids: Array<string> Link to this property
cache?: Cache {cache\_threshold, enabled }
cache\_threshold?: "super\_strict\_match"| "close\_enough"| "flexible\_friend"| "anything\_goes" One of the following: "super\_strict\_match" Link to this property "close\_enough" Link to this property "flexible\_friend" Link to this property "anything\_goes" Link to this property
Link to this property enabled?: boolean Link to this property
Link to this property
custom\_metadata?: Record<string, string| number| boolean> Metadata added to AI Gateway logs for requests triggered by this operation. Accepts up to 2 string, number, or boolean entries. Keys ‘ai-search’, ‘task’, ‘origin’, and keys beginning with ‘cf.’ are reserved. One of the following: string Link to this property number Link to this property boolean Link to this property
Link to this property
query\_rewrite?: QueryRewrite {enabled, model, rewrite\_prompt } enabled?: boolean Link to this property model?: string A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model. Link to this property rewrite\_prompt?: string Link to this property
Link to this property
reranking?: Reranking {enabled, match\_threshold, model } enabled?: boolean Link to this property match\_threshold?: number maximum1 minimum0 Link to this property model?: string Link to this property
Link to this property
retrieval?: Retrieval {boost\_by, context\_expansion, filters, 6 more }
boost\_by?: Array<BoostBy> Metadata fields to boost search results by. Overrides the instance-level boost\_by config. Direction defaults to ‘asc’ for numeric/datetime fields, ‘exists’ for text/boolean fields. Fields must match ‘timestamp’ or a defined custom\_metadata field. field: string Metadata field name to boost by. Use ‘timestamp’ for document freshness, or any custom\_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not\_exists); text/boolean fields only support exists/not\_exists. maxLength64 minLength1 Link to this property
direction?: "asc"| "desc"| "exists"| "not\_exists" Boost direction. ‘desc’ = higher values rank higher (e.g. newer timestamps). ‘asc’ = lower values rank higher. ‘exists’ = boost chunks that have the field. ‘not\_exists’ = boost chunks that lack the field. Optional — defaults to ‘asc’ for numeric/datetime fields, ‘exists’ for text/boolean fields. One of the following: "asc" Link to this property "desc" Link to this property "exists" Link to this property "not\_exists" Link to this property
Link to this property
Link to this property context\_expansion?: number maximum3 minimum0 Link to this property filters?: Record<string, unknown> Link to this property
fusion\_method?: "max"| "rrf" One of the following: "max" Link to this property "rrf" Link to this property
Link to this property
keyword\_match\_mode?: "and"| "or" Controls which documents are candidates for BM25 scoring. ‘and’ restricts candidates to documents containing all query terms; ‘or’ includes any document containing at least one term, ranked by BM25 relevance. When omitted, falls back to the instance-level retrieval\_options.keyword\_match\_mode, then to ‘and’. One of the following: "and" Link to this property "or" Link to this property
Link to this property match\_threshold?: number maximum1 minimum0 Link to this property max\_num\_results?: number maximum50 minimum1 Link to this property
retrieval\_type?: "vector"| "keyword"| "hybrid" One of the following: "vector" Link to this property "keyword" Link to this property "hybrid" Link to this property
Link to this property return\_on\_failure?: boolean Link to this property
Link to this property
Link to this property
messages?: Array<Message> Body param: OpenAI-compatible message array. For multimodal queries, set the last user message’s content to an array of typed parts: [{type:'text', text:'…'}, {type:'image_url', image_url:{url:'…'}}]. Image inputs require the RAG’s embedding\_model to declare ‘image’ in supported\_modalities.
content: string| Array<UnionMember0 {text, type } | UnionMember1 {image\_url, type } | UnionMember2 {file, type } >| string| null One of the following: string Link to this property
Array<UnionMember0 {text, type } | UnionMember1 {image\_url, type } | UnionMember2 {file, type } >
UnionMember0 {text, type } text: string minLength1 Link to this property type: "text" Link to this property
Link to this property
UnionMember1 {image\_url, type }
image\_url: ImageURL {url } url: string maxLength20971520 minLength1 Link to this property
Link to this property type: "image\_url" Link to this property
Link to this property
UnionMember2 {file, type }
file: File {filename, file\_data, file\_id } filename: string maxLength255 minLength1 Link to this property file\_data?: string maxLength13981144 minLength1 Link to this property file\_id?: string Link to this property
Link to this property type: "file" Link to this property
Link to this property
Link to this property string| null Link to this property
Link to this property
role: "system"| "developer"| "user"| 2 more One of the following: "system" Link to this property "developer" Link to this property "user" Link to this property "assistant" Link to this property "tool" Link to this property
Link to this property
Link to this property query?: string Body param: A simple text query string. Alternative to ‘messages’ — provide either this or ‘messages’, not both. minLength1 Link to this property
[Link to this property](<#(resource)%20ai_search.namespaces%20%3E%20(method)%20search%20%3E%20(params)%20default>) ##### ReturnsExpand Collapse
NamespaceSearchResponse {chunks, query\_kind, errors, search\_query }
chunks: Array<Chunk> id: string Link to this property instance\_id: string Link to this property score: number maximum1 minimum0 Link to this property text: string Link to this property type: string Link to this property
item?: Item {key, metadata, timestamp } key: string Link to this property metadata?: Record<string, unknown> Link to this property timestamp?: number Link to this property
Link to this property
scoring\_details?: ScoringDetails {fusion\_method, keyword\_rank, keyword\_score, 3 more }
fusion\_method?: "rrf"| "max" One of the following: "rrf" Link to this property "max" Link to this property
Link to this property keyword\_rank?: number Link to this property keyword\_score?: number minimum0 Link to this property reranking\_score?: number maximum1 minimum0 Link to this property vector\_rank?: number Link to this property vector\_score?: number maximum1 minimum0 Link to this property
Link to this property
Link to this property
query\_kind: "text"| "image"| "multimodal" One of the following: "text" Link to this property "image" Link to this property "multimodal" Link to this property
Link to this property
errors?: Array<Error> instance\_id: string Link to this property message: string Link to this property
Link to this property search\_query?: string Link to this property
[Link to this property](<#(resource)%20ai_search.namespaces%20%3E%20(model)%20namespace_search_response%20%3E%20(schema)>) ### Multi-Instance Search TypeScript HTTPTypeScriptPythonGoTerraform ``` import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const response = await client.aiSearch.namespaces.search('my-namespace', { account_id: 'c3dc5f0b34a14ff8e1b3ec04895e1b22', ai_search_options: { instance_ids: ['my-ai-search'] }, }); console.log(response.chunks); ``` 200 example ``` { "result": { "chunks": [ { "id": "id", "instance_id": "instance_id", "score": 0, "text": "text", "type": "type", "item": { "key": "key", "metadata": { "foo": "bar" }, "timestamp": 0 }, "scoring_details": { "fusion_method": "rrf", "keyword_rank": 0, "keyword_score": 0, "reranking_score": 0, "vector_rank": 0, "vector_score": 0 } } ], "query_kind": "text", "errors": [ { "instance_id": "instance_id", "message": "message" } ], "search_query": "search_query" }, "success": true } ``` ##### Returns Examples 200 example ``` { "result": { "chunks": [ { "id": "id", "instance_id": "instance_id", "score": 0, "text": "text", "type": "type", "item": { "key": "key", "metadata": { "foo": "bar" }, "timestamp": 0 }, "scoring_details": { "fusion_method": "rrf", "keyword_rank": 0, "keyword_score": 0, "reranking_score": 0, "vector_rank": 0, "vector_score": 0 } } ], "query_kind": "text", "errors": [ { "instance_id": "instance_id", "message": "message" } ], "search_query": "search_query" }, "success": true } ```