API Reference

AI Search

Instances

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Search

client.AISearch.Instances.Search(ctx, id, params) (*InstanceSearchResponse, error)

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

AccountID param.Field[string]

Path param

Messages param.Field[[]InstanceSearchParamsMessage]

Body param

Content string

Role InstanceSearchParamsMessagesRole

One of the following:

const InstanceSearchParamsMessagesRoleSystem InstanceSearchParamsMessagesRole = "system"

const InstanceSearchParamsMessagesRoleDeveloper InstanceSearchParamsMessagesRole = "developer"

const InstanceSearchParamsMessagesRoleUser InstanceSearchParamsMessagesRole = "user"

const InstanceSearchParamsMessagesRoleAssistant InstanceSearchParamsMessagesRole = "assistant"

const InstanceSearchParamsMessagesRoleTool InstanceSearchParamsMessagesRole = "tool"

AISearchOptions param.Field[InstanceSearchParamsAISearchOptions]optional

Body param

Cache InstanceSearchParamsAISearchOptionsCacheoptional

CacheThreshold InstanceSearchParamsAISearchOptionsCacheCacheThresholdoptional

One of the following:

const InstanceSearchParamsAISearchOptionsCacheCacheThresholdSuperStrictMatch InstanceSearchParamsAISearchOptionsCacheCacheThreshold = "super_strict_match"

const InstanceSearchParamsAISearchOptionsCacheCacheThresholdCloseEnough InstanceSearchParamsAISearchOptionsCacheCacheThreshold = "close_enough"

const InstanceSearchParamsAISearchOptionsCacheCacheThresholdFlexibleFriend InstanceSearchParamsAISearchOptionsCacheCacheThreshold = "flexible_friend"

const InstanceSearchParamsAISearchOptionsCacheCacheThresholdAnythingGoes InstanceSearchParamsAISearchOptionsCacheCacheThreshold = "anything_goes"

Enabled booloptional

QueryRewrite InstanceSearchParamsAISearchOptionsQueryRewriteoptional

Enabled booloptional

Model InstanceSearchParamsAISearchOptionsQueryRewriteModeloptional

One of the following:

const InstanceSearchParamsAISearchOptionsQueryRewriteModelCfMetaLlama3_3_70bInstructFp8Fast InstanceSearchParamsAISearchOptionsQueryRewriteModel = "@cf/meta/llama-3.3-70b-instruct-fp8-fast"

const InstanceSearchParamsAISearchOptionsQueryRewriteModelCfZaiOrgGlm4_7Flash InstanceSearchParamsAISearchOptionsQueryRewriteModel = "@cf/zai-org/glm-4.7-flash"

const InstanceSearchParamsAISearchOptionsQueryRewriteModelCfMetaLlama3_1_8bInstructFast InstanceSearchParamsAISearchOptionsQueryRewriteModel = "@cf/meta/llama-3.1-8b-instruct-fast"

const InstanceSearchParamsAISearchOptionsQueryRewriteModelCfMetaLlama3_1_8bInstructFp8 InstanceSearchParamsAISearchOptionsQueryRewriteModel = "@cf/meta/llama-3.1-8b-instruct-fp8"

const InstanceSearchParamsAISearchOptionsQueryRewriteModelCfMetaLlama4Scout17b16eInstruct InstanceSearchParamsAISearchOptionsQueryRewriteModel = "@cf/meta/llama-4-scout-17b-16e-instruct"

const InstanceSearchParamsAISearchOptionsQueryRewriteModelCfQwenQwen3_30bA3bFp8 InstanceSearchParamsAISearchOptionsQueryRewriteModel = "@cf/qwen/qwen3-30b-a3b-fp8"

const InstanceSearchParamsAISearchOptionsQueryRewriteModelCfDeepseekAIDeepseekR1DistillQwen32b InstanceSearchParamsAISearchOptionsQueryRewriteModel = "@cf/deepseek-ai/deepseek-r1-distill-qwen-32b"

const InstanceSearchParamsAISearchOptionsQueryRewriteModelCfMoonshotaiKimiK2Instruct InstanceSearchParamsAISearchOptionsQueryRewriteModel = "@cf/moonshotai/kimi-k2-instruct"

const InstanceSearchParamsAISearchOptionsQueryRewriteModelCfGoogleGemma3_12bIt InstanceSearchParamsAISearchOptionsQueryRewriteModel = "@cf/google/gemma-3-12b-it"

const InstanceSearchParamsAISearchOptionsQueryRewriteModelAnthropicClaude3_7Sonnet InstanceSearchParamsAISearchOptionsQueryRewriteModel = "anthropic/claude-3-7-sonnet"

const InstanceSearchParamsAISearchOptionsQueryRewriteModelAnthropicClaudeSonnet4 InstanceSearchParamsAISearchOptionsQueryRewriteModel = "anthropic/claude-sonnet-4"

const InstanceSearchParamsAISearchOptionsQueryRewriteModelAnthropicClaudeOpus4 InstanceSearchParamsAISearchOptionsQueryRewriteModel = "anthropic/claude-opus-4"

const InstanceSearchParamsAISearchOptionsQueryRewriteModelAnthropicClaude3_5Haiku InstanceSearchParamsAISearchOptionsQueryRewriteModel = "anthropic/claude-3-5-haiku"

const InstanceSearchParamsAISearchOptionsQueryRewriteModelCerebrasQwen3_235bA22bInstruct InstanceSearchParamsAISearchOptionsQueryRewriteModel = "cerebras/qwen-3-235b-a22b-instruct"

const InstanceSearchParamsAISearchOptionsQueryRewriteModelCerebrasQwen3_235bA22bThinking InstanceSearchParamsAISearchOptionsQueryRewriteModel = "cerebras/qwen-3-235b-a22b-thinking"

const InstanceSearchParamsAISearchOptionsQueryRewriteModelCerebrasLlama3_3_70b InstanceSearchParamsAISearchOptionsQueryRewriteModel = "cerebras/llama-3.3-70b"

const InstanceSearchParamsAISearchOptionsQueryRewriteModelCerebrasLlama4Maverick17b128eInstruct InstanceSearchParamsAISearchOptionsQueryRewriteModel = "cerebras/llama-4-maverick-17b-128e-instruct"

const InstanceSearchParamsAISearchOptionsQueryRewriteModelCerebrasLlama4Scout17b16eInstruct InstanceSearchParamsAISearchOptionsQueryRewriteModel = "cerebras/llama-4-scout-17b-16e-instruct"

const InstanceSearchParamsAISearchOptionsQueryRewriteModelCerebrasGptOSs120b InstanceSearchParamsAISearchOptionsQueryRewriteModel = "cerebras/gpt-oss-120b"

const InstanceSearchParamsAISearchOptionsQueryRewriteModelGoogleAIStudioGemini2_5Flash InstanceSearchParamsAISearchOptionsQueryRewriteModel = "google-ai-studio/gemini-2.5-flash"

const InstanceSearchParamsAISearchOptionsQueryRewriteModelGoogleAIStudioGemini2_5Pro InstanceSearchParamsAISearchOptionsQueryRewriteModel = "google-ai-studio/gemini-2.5-pro"

const InstanceSearchParamsAISearchOptionsQueryRewriteModelGrokGrok4 InstanceSearchParamsAISearchOptionsQueryRewriteModel = "grok/grok-4"

const InstanceSearchParamsAISearchOptionsQueryRewriteModelGroqLlama3_3_70bVersatile InstanceSearchParamsAISearchOptionsQueryRewriteModel = "groq/llama-3.3-70b-versatile"

const InstanceSearchParamsAISearchOptionsQueryRewriteModelGroqLlama3_1_8bInstant InstanceSearchParamsAISearchOptionsQueryRewriteModel = "groq/llama-3.1-8b-instant"

const InstanceSearchParamsAISearchOptionsQueryRewriteModelOpenAIGpt5 InstanceSearchParamsAISearchOptionsQueryRewriteModel = "openai/gpt-5"

const InstanceSearchParamsAISearchOptionsQueryRewriteModelOpenAIGpt5Mini InstanceSearchParamsAISearchOptionsQueryRewriteModel = "openai/gpt-5-mini"

const InstanceSearchParamsAISearchOptionsQueryRewriteModelOpenAIGpt5Nano InstanceSearchParamsAISearchOptionsQueryRewriteModel = "openai/gpt-5-nano"

const InstanceSearchParamsAISearchOptionsQueryRewriteModelEmpty InstanceSearchParamsAISearchOptionsQueryRewriteModel = ""

RewritePrompt stringoptional

Reranking InstanceSearchParamsAISearchOptionsRerankingoptional

Enabled booloptional

MatchThreshold float64optional

maximum1

minimum0

Model InstanceSearchParamsAISearchOptionsRerankingModeloptional

One of the following:

const InstanceSearchParamsAISearchOptionsRerankingModelCfBaaiBgeRerankerBase InstanceSearchParamsAISearchOptionsRerankingModel = "@cf/baai/bge-reranker-base"

const InstanceSearchParamsAISearchOptionsRerankingModelEmpty InstanceSearchParamsAISearchOptionsRerankingModel = ""

Retrieval InstanceSearchParamsAISearchOptionsRetrievaloptional

BoostBy []InstanceSearchParamsAISearchOptionsRetrievalBoostByoptional

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 InstanceSearchParamsAISearchOptionsRetrievalBoostByDirectionoptional

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:

const InstanceSearchParamsAISearchOptionsRetrievalBoostByDirectionAsc InstanceSearchParamsAISearchOptionsRetrievalBoostByDirection = "asc"

const InstanceSearchParamsAISearchOptionsRetrievalBoostByDirectionDesc InstanceSearchParamsAISearchOptionsRetrievalBoostByDirection = "desc"

const InstanceSearchParamsAISearchOptionsRetrievalBoostByDirectionExists InstanceSearchParamsAISearchOptionsRetrievalBoostByDirection = "exists"

const InstanceSearchParamsAISearchOptionsRetrievalBoostByDirectionNotExists InstanceSearchParamsAISearchOptionsRetrievalBoostByDirection = "not_exists"

ContextExpansion int64optional

maximum3

minimum0

Filters map[string, unknown]optional

FusionMethod InstanceSearchParamsAISearchOptionsRetrievalFusionMethodoptional

One of the following:

const InstanceSearchParamsAISearchOptionsRetrievalFusionMethodMax InstanceSearchParamsAISearchOptionsRetrievalFusionMethod = "max"

const InstanceSearchParamsAISearchOptionsRetrievalFusionMethodRrf InstanceSearchParamsAISearchOptionsRetrievalFusionMethod = "rrf"

KeywordMatchMode InstanceSearchParamsAISearchOptionsRetrievalKeywordMatchModeoptional

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:

const InstanceSearchParamsAISearchOptionsRetrievalKeywordMatchModeAnd InstanceSearchParamsAISearchOptionsRetrievalKeywordMatchMode = "and"

const InstanceSearchParamsAISearchOptionsRetrievalKeywordMatchModeOr InstanceSearchParamsAISearchOptionsRetrievalKeywordMatchMode = "or"

MatchThreshold float64optional

maximum1

minimum0

MaxNumResults int64optional

maximum50

minimum1

RetrievalType InstanceSearchParamsAISearchOptionsRetrievalRetrievalTypeoptional

One of the following:

const InstanceSearchParamsAISearchOptionsRetrievalRetrievalTypeVector InstanceSearchParamsAISearchOptionsRetrievalRetrievalType = "vector"

const InstanceSearchParamsAISearchOptionsRetrievalRetrievalTypeKeyword InstanceSearchParamsAISearchOptionsRetrievalRetrievalType = "keyword"

const InstanceSearchParamsAISearchOptionsRetrievalRetrievalTypeHybrid InstanceSearchParamsAISearchOptionsRetrievalRetrievalType = "hybrid"

ReturnOnFailure booloptional

ReturnsExpand Collapse

type InstanceSearchResponse struct{…}

Chunks []InstanceSearchResponseChunk

ID string

Score float64

maximum1

minimum0

Text string

Type string

Item InstanceSearchResponseChunksItemoptional

Key string

Metadata map[string, unknown]optional

Timestamp float64optional

ScoringDetails InstanceSearchResponseChunksScoringDetailsoptional

FusionMethod InstanceSearchResponseChunksScoringDetailsFusionMethodoptional

One of the following:

const InstanceSearchResponseChunksScoringDetailsFusionMethodRrf InstanceSearchResponseChunksScoringDetailsFusionMethod = "rrf"

const InstanceSearchResponseChunksScoringDetailsFusionMethodMax InstanceSearchResponseChunksScoringDetailsFusionMethod = "max"

KeywordRank float64optional

KeywordScore float64optional

minimum0

RerankingScore float64optional

maximum1

minimum0

VectorRank float64optional

VectorScore float64optional

maximum1

minimum0

SearchQuery string

Search

Go

HTTP

TypeScript

Python

Go

Terraform

package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/ai_search"
  "github.com/cloudflare/cloudflare-go/option"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  response, err := client.AISearch.Instances.Search(
    context.TODO(),
    "my-ai-search",
    ai_search.InstanceSearchParams{
      AccountID: cloudflare.F("c3dc5f0b34a14ff8e1b3ec04895e1b22"),
      Messages: cloudflare.F([]ai_search.InstanceSearchParamsMessage{ai_search.InstanceSearchParamsMessage{
        Content: cloudflare.F("content"),
        Role: cloudflare.F(ai_search.InstanceSearchParamsMessagesRoleSystem),
      }}),
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.Chunks)
}

200 example

{
  "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

200 example

{
  "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
}