Multi-Instance Search

aisearch.namespaces.search(, ) -> NamespaceSearchResponse

POST/accounts/{account_id}/ai-search/namespaces/{name}/search

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: Optional[str]

name: str

aisearch_options: AISearchOptions

instance_ids: Sequence[str]

cache: Optional[AISearchOptionsCache]

cache_threshold: Optional[Literal["super_strict_match", "close_enough", "flexible_friend", "anything_goes"]]

One of the following:

"super_strict_match"

"close_enough"

"flexible_friend"

"anything_goes"

enabled: Optional[bool]

query_rewrite: Optional[AISearchOptionsQueryRewrite]

enabled: Optional[bool]

model: Optional[Literal["@cf/meta/llama-3.3-70b-instruct-fp8-fast", "@cf/zai-org/glm-4.7-flash", "@cf/meta/llama-3.1-8b-instruct-fast", 27 more]]

One of the following:

"@cf/meta/llama-3.3-70b-instruct-fp8-fast"

"@cf/zai-org/glm-4.7-flash"

"@cf/meta/llama-3.1-8b-instruct-fast"

"@cf/meta/llama-3.1-8b-instruct-fp8"

"@cf/meta/llama-4-scout-17b-16e-instruct"

"@cf/qwen/qwen3-30b-a3b-fp8"

"@cf/deepseek-ai/deepseek-r1-distill-qwen-32b"

"@cf/moonshotai/kimi-k2-instruct"

"@cf/google/gemma-3-12b-it"

"@cf/google/gemma-4-26b-a4b-it"

"@cf/moonshotai/kimi-k2.5"

"anthropic/claude-3-7-sonnet"

"anthropic/claude-sonnet-4"

"anthropic/claude-opus-4"

"anthropic/claude-3-5-haiku"

"cerebras/qwen-3-235b-a22b-instruct"

"cerebras/qwen-3-235b-a22b-thinking"

"cerebras/llama-3.3-70b"

"cerebras/llama-4-maverick-17b-128e-instruct"

"cerebras/llama-4-scout-17b-16e-instruct"

"cerebras/gpt-oss-120b"

"google-ai-studio/gemini-2.5-flash"

"google-ai-studio/gemini-2.5-pro"

"grok/grok-4"

"groq/llama-3.3-70b-versatile"

"groq/llama-3.1-8b-instant"

"openai/gpt-5"

"openai/gpt-5-mini"

"openai/gpt-5-nano"

rewrite_prompt: Optional[str]

reranking: Optional[AISearchOptionsReranking]

enabled: Optional[bool]

match_threshold: Optional[float]

maximum1

minimum0

model: Optional[Literal["@cf/baai/bge-reranker-base", ""]]

One of the following:

"@cf/baai/bge-reranker-base"

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 asc/desc directions; text/boolean fields support exists/not_exists.

maxLength64

minLength1

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"

"desc"

"exists"

"not_exists"

context_expansion: Optional[int]

maximum3

minimum0

filters: Optional[Dict[str, object]]

fusion_method: Optional[Literal["max", "rrf"]]

One of the following:

"max"

"rrf"

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. Defaults to ‘and’.

One of the following:

"and"

"or"

match_threshold: Optional[float]

maximum1

minimum0

max_num_results: Optional[int]

maximum50

minimum1

retrieval_type: Optional[Literal["vector", "keyword", "hybrid"]]

One of the following:

"vector"

"keyword"

"hybrid"

return_on_failure: Optional[bool]

messages: Optional[Iterable[Message]]

content: Optional[str]

role: Literal["system", "developer", "user", 2 more]

One of the following:

"system"

"developer"

"user"

"assistant"

"tool"

query: Optional[str]

A simple text query string. Alternative to ‘messages’ — provide either this or ‘messages’, not both.

minLength1

ReturnsExpand Collapse

class NamespaceSearchResponse: …

chunks: List[Chunk]

id: str

instance_id: str

score: float

maximum1

minimum0

text: str

type: str

item: Optional[ChunkItem]

key: str

metadata: Optional[Dict[str, object]]

timestamp: Optional[float]

scoring_details: Optional[ChunkScoringDetails]

fusion_method: Optional[Literal["rrf", "max"]]

One of the following:

"rrf"

"max"

keyword_rank: Optional[float]

keyword_score: Optional[float]

minimum0

reranking_score: Optional[float]

maximum1

minimum0

vector_rank: Optional[float]

vector_score: Optional[float]

maximum1

minimum0

search_query: str

errors: Optional[List[Error]]

instance_id: str

message: str

Multi-Instance Search

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)

{
  "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
        }
      }
    ],
    "search_query": "search_query",
    "errors": [
      {
        "instance_id": "instance_id",
        "message": "message"
      }
    ]
  },
  "success": true
}

Returns Examples

{
  "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
        }
      }
    ],
    "search_query": "search_query",
    "errors": [
      {
        "instance_id": "instance_id",
        "message": "message"
      }
    ]
  },
  "success": true
}