--- title: Multi-Instance Search --- [Skip to content](#_top) [API Reference](https://developers.cloudflare.com/api/python) [AI Search](https://developers.cloudflare.com/api/python/resources/ai_search) [Namespaces](https://developers.cloudflare.com/api/python/resources/ai_search/subresources/namespaces) Copy Markdown Open in **Claude**Open in **ChatGPT**Open in **Cursor** --- **Copy Markdown****View as Markdown** # Multi-Instance Search aisearch.namespaces.search(strname, NamespaceSearchParams\*\*kwargs) -> [NamespaceSearchResponse]() 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 account\_id: str [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: str [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)>)
aisearch\_options: AISearchOptions instance\_ids: Sequence\[str] Link to this property
cache: Optional\[AISearchOptionsCache]
cache\_threshold: Optional\[Literal\["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: Optional\[bool] Link to this property
Link to this property
custom\_metadata: Optional\[Dict\[str, Union\[str, float, bool]]] 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: str Link to this property float Link to this property bool Link to this property
Link to this property
query\_rewrite: Optional\[AISearchOptionsQueryRewrite] enabled: Optional\[bool] Link to this property model: Optional\[str] 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\[str] Link to this property
Link to this property
reranking: Optional\[AISearchOptionsReranking] enabled: Optional\[bool] Link to this property match\_threshold: Optional\[float] maximum1 minimum0 Link to this property model: Optional\[str] Link to this property
Link to this property
retrieval: Optional\[AISearchOptionsRetrieval]
boost\_by: Optional\[Iterable\[AISearchOptionsRetrievalBoostBy]] 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: str 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\[Literal\["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: Optional\[int] maximum3 minimum0 Link to this property filters: Optional\[Dict\[str, object]] Link to this property
fusion\_method: Optional\[Literal\["max", "rrf"]] One of the following: "max" Link to this property "rrf" Link to this property
Link to this property
keyword\_match\_mode: Optional\[Literal\["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: Optional\[float] maximum1 minimum0 Link to this property max\_num\_results: Optional\[int] maximum50 minimum1 Link to this property
retrieval\_type: Optional\[Literal\["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: Optional\[bool] 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)%20default%20%3E%20(param)%20ai_search_options%20%3E%20(schema)>)
messages: Optional\[Iterable\[Message]] 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: Union\[str, Iterable\[MessageContentUnionMember1], Optional\[str]] One of the following: str Link to this property
Iterable\[MessageContentUnionMember1] One of the following:
class MessageContentUnionMember1UnionMember0: … text: str minLength1 Link to this property type: Literal\["text"] Link to this property
Link to this property
class MessageContentUnionMember1UnionMember1: …
image\_url: MessageContentUnionMember1UnionMember1ImageURL url: str maxLength20971520 minLength1 Link to this property
Link to this property type: Literal\["image\_url"] Link to this property
Link to this property
class MessageContentUnionMember1UnionMember2: …
file: MessageContentUnionMember1UnionMember2File filename: str maxLength255 minLength1 Link to this property file\_data: Optional\[str] maxLength13981144 minLength1 Link to this property file\_id: Optional\[str] Link to this property
Link to this property type: Literal\["file"] Link to this property
Link to this property
Link to this property Optional\[str] Link to this property
Link to this property
role: Literal\["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](<#(resource)%20ai_search.namespaces%20%3E%20(method)%20search%20%3E%20(params)%20default%20%3E%20(param)%20messages%20%3E%20(schema)>) query: Optional\[str] 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)%20default%20%3E%20(param)%20query%20%3E%20(schema)>) ##### ReturnsExpand Collapse
class NamespaceSearchResponse: …
chunks: List\[Chunk] id: str Link to this property instance\_id: str Link to this property score: float maximum1 minimum0 Link to this property text: str Link to this property type: str Link to this property
item: Optional\[ChunkItem] key: str Link to this property metadata: Optional\[Dict\[str, object]] Link to this property timestamp: Optional\[float] Link to this property
Link to this property
scoring\_details: Optional\[ChunkScoringDetails]
fusion\_method: Optional\[Literal\["rrf", "max"]] One of the following: "rrf" Link to this property "max" Link to this property
Link to this property keyword\_rank: Optional\[float] Link to this property keyword\_score: Optional\[float] minimum0 Link to this property reranking\_score: Optional\[float] maximum1 minimum0 Link to this property vector\_rank: Optional\[float] Link to this property vector\_score: Optional\[float] maximum1 minimum0 Link to this property
Link to this property
Link to this property
query\_kind: Literal\["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: Optional\[List\[Error]] instance\_id: str Link to this property message: str Link to this property
Link to this property search\_query: Optional\[str] 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 Python HTTPTypeScriptPythonGoTerraform ``` import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) response = client.aisearch.namespaces.search( name="my-namespace", account_id="c3dc5f0b34a14ff8e1b3ec04895e1b22", aisearch_options={ "instance_ids": ["my-ai-search"] }, ) print(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 } ```