--- title: Multi-Instance Search --- [Skip to content](#_top) [API Reference](https://developers.cloudflare.com/api) [AI Search](https://developers.cloudflare.com/api/resources/ai_search) [Namespaces](https://developers.cloudflare.com/api/resources/ai_search/subresources/namespaces) Copy Markdown Open in **Claude**Open in **ChatGPT**Open in **Cursor** --- **Copy Markdown****View as Markdown** # Multi-Instance Search 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
##### P ath ParametersExpand Collapse account\_id: string [Link to this property](<#(resource)%20ai_search.namespaces%20%3E%20(method)%20search%20%3E%20(params)%20default%20%3E%20(param)%20account_id%20%3E%20(schema)>) 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)>) ##### Body ParametersJSONExpand Collapse
ai\_search\_options: object {instance\_ids, cache, custom\_metadata, 3 more } instance\_ids: array of string Link to this property
cache: optional object {cache\_threshold, enabled }
cache\_threshold: optional "super\_strict\_match"or "close\_enough"or "flexible\_friend"or "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: optional boolean Link to this property
Link to this property
custom\_metadata: optional map\[stringor numberor 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: optional object {enabled, model, rewrite\_prompt } enabled: optional boolean Link to this property model: optional 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: optional string Link to this property
Link to this property
reranking: optional object {enabled, match\_threshold, model } enabled: optional boolean Link to this property match\_threshold: optional number maximum1 minimum0 Link to this property model: optional string Link to this property
Link to this property
retrieval: optional object {boost\_by, context\_expansion, filters, 6 more }
boost\_by: optional array of object {field, direction } 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: optional "asc"or "desc"or "exists"or "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: optional number maximum3 minimum0 Link to this property filters: optional map\[unknown] Link to this property
fusion\_method: optional "max"or "rrf" One of the following: "max" Link to this property "rrf" Link to this property
Link to this property
keyword\_match\_mode: optional "and"or "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: optional number maximum1 minimum0 Link to this property max\_num\_results: optional number maximum50 minimum1 Link to this property
retrieval\_type: optional "vector"or "keyword"or "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: optional boolean Link to this property
Link to this property
[Link to this property](<#(resource)%20ai_search.namespaces%20%3E%20(method)%20search%20%3E%20(params)%200%20%3E%20(param)%20ai_search_options%20%3E%20(schema)>)
messages: optional array of object {content, role } 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: stringor array of object {text, type } or object {image\_url, type } or object {file, type } or string One of the following: string Link to this property
array of object {text, type } or object {image\_url, type } or object {file, type } One of the following:
object {text, type } text: string minLength1 Link to this property type: "text" Link to this property
Link to this property
object {image\_url, type }
image\_url: object {url } url: string maxLength20971520 minLength1 Link to this property
Link to this property type: "image\_url" Link to this property
Link to this property
object {file, type }
file: object {filename, file\_data, file\_id } filename: string maxLength255 minLength1 Link to this property file\_data: optional string maxLength13981144 minLength1 Link to this property file\_id: optional string Link to this property
Link to this property type: "file" Link to this property
Link to this property
Link to this property string Link to this property
Link to this property
role: "system"or "developer"or "user"or 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](<#(resource)%20ai_search.namespaces%20%3E%20(method)%20search%20%3E%20(params)%200%20%3E%20(param)%20messages%20%3E%20(schema)>) query: optional string A simple text query string. Alternative to ‘messages’ — provide either this or ‘messages’, not both. minLength1 [Link to this property](<#(resource)%20ai_search.namespaces%20%3E%20(method)%20search%20%3E%20(params)%200%20%3E%20(param)%20query%20%3E%20(schema)>) ##### ReturnsExpand Collapse
result: object {chunks, query\_kind, errors, search\_query }
chunks: array of object {id, instance\_id, score, 4 more } 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: optional object {key, metadata, timestamp } key: string Link to this property metadata: optional map\[unknown] Link to this property timestamp: optional number Link to this property
Link to this property
scoring\_details: optional object {fusion\_method, keyword\_rank, keyword\_score, 3 more }
fusion\_method: optional "rrf"or "max" One of the following: "rrf" Link to this property "max" Link to this property
Link to this property keyword\_rank: optional number Link to this property keyword\_score: optional number minimum0 Link to this property reranking\_score: optional number maximum1 minimum0 Link to this property vector\_rank: optional number Link to this property vector\_score: optional number maximum1 minimum0 Link to this property
Link to this property
Link to this property
query\_kind: "text"or "image"or "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: optional array of object {instance\_id, message } instance\_id: string Link to this property message: string Link to this property
Link to this property search\_query: optional string Link to this property
[Link to this property](<#(resource)%20ai_search.namespaces%20%3E%20(method)%20search%20%3E%20(network%20schema)%20%3E%20(property)%20result>) success: boolean [Link to this property](<#(resource)%20ai_search.namespaces%20%3E%20(method)%20search%20%3E%20(network%20schema)%20%3E%20(property)%20success>) ### Multi-Instance Search HTTP HTTPTypeScriptPythonGoTerraform ``` curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/namespaces/$NAME/search \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ -d '{ "ai_search_options": { "instance_ids": [ "my-ai-search" ] } }' ``` 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 } ```