## Search

`client.aiSearch.instances.search(stringid, InstanceSearchParamsparams, RequestOptionsoptions?): InstanceSearchResponse`

**post** `/accounts/{account_id}/ai-search/instances/{id}/search`

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

### Parameters

- `id: string`

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

- `params: InstanceSearchParams`

  - `account_id: string`

    Path param

  - `messages: Array<Message>`

    Body param

    - `content: string | null`

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

      - `"system"`

      - `"developer"`

      - `"user"`

      - `"assistant"`

      - `"tool"`

  - `ai_search_options?: AISearchOptions`

    Body param

    - `cache?: Cache`

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

        - `"super_strict_match"`

        - `"close_enough"`

        - `"flexible_friend"`

        - `"anything_goes"`

      - `enabled?: boolean`

    - `query_rewrite?: QueryRewrite`

      - `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`

        - `"@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?: boolean`

      - `match_threshold?: number`

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

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

        - `""`

    - `retrieval?: Retrieval`

      - `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.

        - `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.

          - `"asc"`

          - `"desc"`

          - `"exists"`

          - `"not_exists"`

      - `context_expansion?: number`

      - `filters?: Record<string, unknown>`

      - `fusion_method?: "max" | "rrf"`

        - `"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.

        - `"and"`

        - `"or"`

      - `match_threshold?: number`

      - `max_num_results?: number`

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

        - `"vector"`

        - `"keyword"`

        - `"hybrid"`

      - `return_on_failure?: boolean`

### Returns

- `InstanceSearchResponse`

  - `chunks: Array<Chunk>`

    - `id: string`

    - `score: number`

    - `text: string`

    - `type: string`

    - `item?: Item`

      - `key: string`

      - `metadata?: Record<string, unknown>`

      - `timestamp?: number`

    - `scoring_details?: ScoringDetails`

      - `fusion_method?: "rrf" | "max"`

        - `"rrf"`

        - `"max"`

      - `keyword_rank?: number`

      - `keyword_score?: number`

      - `reranking_score?: number`

      - `vector_rank?: number`

      - `vector_score?: number`

  - `search_query: string`

### Example

```node
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);
```

#### Response

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