Search

client.aiSearch.instances.search(, , ?): InstanceSearchResponse { chunks, search_query }

POST/accounts/{account_id}/ai-search/instances/{id}/search

Executes a semantic search query against an AI Search instance to find relevant indexed content.

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

id: string

AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.

maxLength64

minLength1

params: InstanceSearchParams { account_id, messages, ai_search_options }

account_id: string

Path param

messages: Array<Message>

Body param

content: string | null

role: "system" | "developer" | "user" | 2 more

One of the following:

"system"

"developer"

"user"

"assistant"

"tool"

ai_search_options?: AISearchOptions

Body param

cache?: Cache { cache_threshold, enabled }

cache_threshold?: "super_strict_match" | "close_enough" | "flexible_friend" | "anything_goes"

One of the following:

"super_strict_match"

"close_enough"

"flexible_friend"

"anything_goes"

enabled?: boolean

query_rewrite?: QueryRewrite { enabled, model, rewrite_prompt }

enabled?: boolean

model?: "@cf/meta/llama-3.3-70b-instruct-fp8-fast" | "@cf/zai-org/glm-4.7-flash" | "@cf/meta/llama-3.1-8b-instruct-fast" | 25 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"

"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?: string

reranking?: Reranking { enabled, match_threshold, model }

enabled?: boolean

match_threshold?: number

maximum1

minimum0

model?: "@cf/baai/bge-reranker-base" | ""

One of the following:

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

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

maxLength64

minLength1

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"

"desc"

"exists"

"not_exists"

context_expansion?: number

maximum3

minimum0

filters?: Record<string, unknown>

fusion_method?: "max" | "rrf"

One of the following:

"max"

"rrf"

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. Defaults to 'and'. Legacy values 'exact_match' and 'fuzzy_match' are accepted and map to 'and' and 'or' respectively.

One of the following:

"and"

"or"

match_threshold?: number

maximum1

minimum0

max_num_results?: number

maximum50

minimum1

retrieval_type?: "vector" | "keyword" | "hybrid"

One of the following:

"vector"

"keyword"

"hybrid"

return_on_failure?: boolean

ReturnsExpand Collapse

InstanceSearchResponse { chunks, search_query }

chunks: Array<Chunk>

id: string

score: number

maximum1

minimum0

text: string

type: string

item?: Item { key, metadata, timestamp }

key: string

metadata?: Record<string, unknown>

timestamp?: number

scoring_details?: ScoringDetails { fusion_method, keyword_rank, keyword_score, 3 more }

fusion_method?: "rrf" | "max"

One of the following:

"rrf"

"max"

keyword_rank?: number

keyword_score?: number

minimum0

reranking_score?: number

maximum1

minimum0

vector_rank?: number

vector_score?: number

maximum1

minimum0

search_query: string

Search

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.instances.search('my-ai-search', {
  account_id: 'c3dc5f0b34a14ff8e1b3ec04895e1b22',
  messages: [{ content: 'content', role: 'system' }],
});

console.log(response.chunks);

{
  "result": {
    "chunks": [
      {
        "id": "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"
  },
  "success": true
}

Returns Examples

{
  "result": {
    "chunks": [
      {
        "id": "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"
  },
  "success": true
}