Skip to content
Start here

List AI Search instances.

Deprecated
aisearch.instances.list(InstanceListParams**kwargs) -> SyncV4PagePaginationArray[InstanceListResponse]
GET/accounts/{account_id}/ai-search/instances

Lists all AI Search instances in the account.

Deprecated: use /accounts/{account_id}/ai-search/namespaces/{namespace}/instances (and descendant paths) instead.

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

Return only instances with this exact Search for Agents hostname (case-insensitive).

maxLength253
minLength1
namespace: Optional[str]

Return only instances in this namespace.

order_by: Optional[Literal["created_at"]]

Field to order results by.

order_by_direction: Optional[Literal["asc", "desc"]]

Order direction.

One of the following:
"asc"
"desc"
page: Optional[int]

Page number (1-indexed).

maximum10000
minimum1
per_page: Optional[int]

Number of results per page.

maximum100
minimum1
ReturnsExpand Collapse
class InstanceListResponse: …
id: str
ai_gateway_id: Optional[str]
aisearch_model: Optional[str]
cache: bool
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"
cache_ttl: Literal[600, 1800, 3600, 7 more]
One of the following:
600
1800
3600
7200
21600
43200
86400
172800
259200
518400
chunk: bool
chunk_overlap: Optional[float]
chunk_size: Optional[float]
created_at: datetime
formatdate-time
created_by: Optional[str]
custom_metadata: Optional[List[CustomMetadata]]
data_type: Literal["text", "number", "boolean", "datetime"]
One of the following:
"text"
"number"
"boolean"
"datetime"
field_name: str
embedding_model: Optional[str]
enable: bool
engine_version: float
fusion_method: Literal["max", "rrf"]
One of the following:
"max"
"rrf"
hybrid_search_enabled: bool
index_method: IndexMethod
keyword: bool
vector: bool
indexing_options: Optional[IndexingOptions]
keyword_tokenizer: Optional[Literal["porter", "trigram"]]
One of the following:
"porter"
"trigram"
use_ocr: Optional[bool]
last_activity: Optional[datetime]
formatdate-time
max_num_results: Optional[float]
metadata: Optional[Metadata]
created_from_aisearch_wizard: Optional[bool]
created_from_emdash_plugin: Optional[MetadataCreatedFromEmdashPlugin]
type: Literal["native", "rest"]
One of the following:
"native"
"rest"
version: str
worker_domain: Optional[str]
modified_at: datetime
formatdate-time
modified_by: Optional[str]
namespace: str
paused: bool
public_endpoint_id: Optional[str]
public_endpoint_params: Optional[PublicEndpointParams]
authorized_hosts: Optional[List[str]]
chat_completions_endpoint: Optional[PublicEndpointParamsChatCompletionsEndpoint]
disabled: Optional[bool]
custom_domains: Optional[List[str]]
default_domain_enabled: Optional[bool]
enabled: Optional[bool]
mcp: Optional[PublicEndpointParamsMcp]
description: Optional[str]
disabled: Optional[bool]
rate_limit: Optional[PublicEndpointParamsRateLimit]
period_ms: Optional[int]
maximum3600000
minimum60000
requests: Optional[int]
minimum1
technique: Optional[Literal["fixed", "sliding"]]
One of the following:
"fixed"
"sliding"
search_endpoint: Optional[PublicEndpointParamsSearchEndpoint]
disabled: Optional[bool]
reranking: bool
reranking_model: Optional[str]
retrieval_options: Optional[RetrievalOptions]
boost_by: Optional[List[RetrievalOptionsBoostBy]]
field: str
maxLength64
minLength1
data_type: Optional[Literal["number", "datetime", "text", "boolean"]]
One of the following:
"number"
"datetime"
"text"
"boolean"
direction: Optional[Literal["asc", "desc", "exists", "not_exists"]]
One of the following:
"asc"
"desc"
"exists"
"not_exists"
keyword_match_mode: Optional[Literal["and", "or"]]
One of the following:
"and"
"or"
rewrite_model: Optional[str]
rewrite_query: bool
score_threshold: Optional[float]
source: Optional[str]
source_params: Optional[SourceParams]
d1: Optional[SourceParamsD1]

D1 source configuration of a d1 instance.

query: Optional[str]

Read-only SELECT query run against the D1 database. It must return an id column that uniquely identifies each row. Columns named title and content set the document title and body, and up to 5 meta_* columns become filterable custom metadata; any other column is indexed as a labelled field. Every sync reads the full result, up to 100,000 rows, with the instance’s token, and those reads count against your D1 usage. Leading and trailing whitespace is trimmed before the query is stored.

template: Optional[str]

How each row is rendered into the indexed document: labelled renders the title, the labelled fields, then the content; content_only renders the title and content (labelled fields only when there is no content); key_value renders every column as name: value; json renders every column as a JSON object.

exclude_items: Optional[List[str]]
include_items: Optional[List[str]]
prefix: Optional[str]
r2_jurisdiction: Optional[str]
web_crawler: Optional[SourceParamsWebCrawler]
discover_options: Optional[SourceParamsWebCrawlerDiscoverOptions]
depth: Optional[float]
maximum100000
minimum1
include_subdomains: Optional[bool]
limit: Optional[float]

Maximum number of pages to crawl. New values have a maximum of 100000; instances configured before that cap may report a higher stored value, which the crawler clamps at run time.

maximum100000
minimum1
max_age: Optional[float]
maximum604800
minimum0
source: Optional[Literal["all", "sitemaps", "links"]]
One of the following:
"all"
"sitemaps"
"links"
parse_options: Optional[SourceParamsWebCrawlerParseOptions]
content_selector: Optional[List[SourceParamsWebCrawlerParseOptionsContentSelector]]
path: str
maxLength200
minLength1
selector: str
maxLength200
minLength1
include_headers: Optional[Dict[str, str]]
include_images: Optional[bool]
specific_sitemaps: Optional[List[str]]
use_browser_rendering: Optional[bool]
parse_type: Optional[Literal["sitemap", "discover"]]
One of the following:
"sitemap"
"discover"
status: str
summarization: bool
summarization_model: Optional[str]
sync_interval: Literal[900, 1800, 3600, 5 more]
One of the following:
900
1800
3600
7200
14400
21600
43200
86400
system_prompt_index_summarization: Optional[str]
system_prompt_rewrite_query: Optional[str]
token_id: Optional[str]
type: Optional[Literal["r2", "web-crawler", "d1"]]
One of the following:
"r2"
"web-crawler"
"d1"

List AI Search instances.

import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
page = client.aisearch.instances.list(
    account_id="c3dc5f0b34a14ff8e1b3ec04895e1b22",
)
page = page.result[0]
print(page.id)
{
  "result": [
    {
      "id": "id",
      "ai_gateway_id": "ai_gateway_id",
      "ai_search_model": "ai_search_model",
      "cache": true,
      "cache_threshold": "super_strict_match",
      "cache_ttl": 600,
      "chunk": true,
      "chunk_overlap": 0,
      "chunk_size": 0,
      "created_at": "2019-12-27T18:11:19.117Z",
      "created_by": "created_by",
      "custom_metadata": [
        {
          "data_type": "text",
          "field_name": "field_name"
        }
      ],
      "embedding_model": "embedding_model",
      "enable": true,
      "engine_version": 0,
      "fusion_method": "max",
      "hybrid_search_enabled": true,
      "index_method": {
        "keyword": true,
        "vector": true
      },
      "indexing_options": {
        "keyword_tokenizer": "porter",
        "use_ocr": true
      },
      "last_activity": "2019-12-27T18:11:19.117Z",
      "max_num_results": 0,
      "metadata": {
        "created_from_aisearch_wizard": true,
        "created_from_emdash_plugin": {
          "type": "native",
          "version": "version"
        },
        "worker_domain": "worker_domain"
      },
      "modified_at": "2019-12-27T18:11:19.117Z",
      "modified_by": "modified_by",
      "namespace": "namespace",
      "paused": true,
      "public_endpoint_id": "public_endpoint_id",
      "public_endpoint_params": {
        "authorized_hosts": [
          "string"
        ],
        "chat_completions_endpoint": {
          "disabled": true
        },
        "custom_domains": [
          "x"
        ],
        "default_domain_enabled": true,
        "enabled": true,
        "mcp": {
          "description": "description",
          "disabled": true
        },
        "rate_limit": {
          "period_ms": 60000,
          "requests": 1,
          "technique": "fixed"
        },
        "search_endpoint": {
          "disabled": true
        }
      },
      "reranking": true,
      "reranking_model": "reranking_model",
      "retrieval_options": {
        "boost_by": [
          {
            "field": "x",
            "dataType": "number",
            "direction": "asc"
          }
        ],
        "keyword_match_mode": "and"
      },
      "rewrite_model": "rewrite_model",
      "rewrite_query": true,
      "score_threshold": 0,
      "source": "source",
      "source_params": {
        "d1": {
          "query": "query",
          "template": "template"
        },
        "exclude_items": [
          "string"
        ],
        "include_items": [
          "string"
        ],
        "prefix": "prefix",
        "r2_jurisdiction": "r2_jurisdiction",
        "web_crawler": {
          "discover_options": {
            "depth": 1,
            "include_external_links": true,
            "include_subdomains": true,
            "limit": 1,
            "max_age": 0,
            "source": "all"
          },
          "parse_options": {
            "content_selector": [
              {
                "path": "x",
                "selector": "x"
              }
            ],
            "include_headers": {
              "foo": "string"
            },
            "include_images": true,
            "specific_sitemaps": [
              "https://example.com"
            ],
            "use_browser_rendering": true
          },
          "parse_type": "sitemap"
        }
      },
      "status": "status",
      "summarization": true,
      "summarization_model": "summarization_model",
      "sync_interval": 900,
      "system_prompt_ai_search": "system_prompt_ai_search",
      "system_prompt_index_summarization": "system_prompt_index_summarization",
      "system_prompt_rewrite_query": "system_prompt_rewrite_query",
      "token_id": "token_id",
      "type": "r2"
    }
  ],
  "result_info": {
    "count": 0,
    "page": 0,
    "per_page": 0,
    "total_count": 0
  },
  "success": true
}
Returns Examples
{
  "result": [
    {
      "id": "id",
      "ai_gateway_id": "ai_gateway_id",
      "ai_search_model": "ai_search_model",
      "cache": true,
      "cache_threshold": "super_strict_match",
      "cache_ttl": 600,
      "chunk": true,
      "chunk_overlap": 0,
      "chunk_size": 0,
      "created_at": "2019-12-27T18:11:19.117Z",
      "created_by": "created_by",
      "custom_metadata": [
        {
          "data_type": "text",
          "field_name": "field_name"
        }
      ],
      "embedding_model": "embedding_model",
      "enable": true,
      "engine_version": 0,
      "fusion_method": "max",
      "hybrid_search_enabled": true,
      "index_method": {
        "keyword": true,
        "vector": true
      },
      "indexing_options": {
        "keyword_tokenizer": "porter",
        "use_ocr": true
      },
      "last_activity": "2019-12-27T18:11:19.117Z",
      "max_num_results": 0,
      "metadata": {
        "created_from_aisearch_wizard": true,
        "created_from_emdash_plugin": {
          "type": "native",
          "version": "version"
        },
        "worker_domain": "worker_domain"
      },
      "modified_at": "2019-12-27T18:11:19.117Z",
      "modified_by": "modified_by",
      "namespace": "namespace",
      "paused": true,
      "public_endpoint_id": "public_endpoint_id",
      "public_endpoint_params": {
        "authorized_hosts": [
          "string"
        ],
        "chat_completions_endpoint": {
          "disabled": true
        },
        "custom_domains": [
          "x"
        ],
        "default_domain_enabled": true,
        "enabled": true,
        "mcp": {
          "description": "description",
          "disabled": true
        },
        "rate_limit": {
          "period_ms": 60000,
          "requests": 1,
          "technique": "fixed"
        },
        "search_endpoint": {
          "disabled": true
        }
      },
      "reranking": true,
      "reranking_model": "reranking_model",
      "retrieval_options": {
        "boost_by": [
          {
            "field": "x",
            "dataType": "number",
            "direction": "asc"
          }
        ],
        "keyword_match_mode": "and"
      },
      "rewrite_model": "rewrite_model",
      "rewrite_query": true,
      "score_threshold": 0,
      "source": "source",
      "source_params": {
        "d1": {
          "query": "query",
          "template": "template"
        },
        "exclude_items": [
          "string"
        ],
        "include_items": [
          "string"
        ],
        "prefix": "prefix",
        "r2_jurisdiction": "r2_jurisdiction",
        "web_crawler": {
          "discover_options": {
            "depth": 1,
            "include_external_links": true,
            "include_subdomains": true,
            "limit": 1,
            "max_age": 0,
            "source": "all"
          },
          "parse_options": {
            "content_selector": [
              {
                "path": "x",
                "selector": "x"
              }
            ],
            "include_headers": {
              "foo": "string"
            },
            "include_images": true,
            "specific_sitemaps": [
              "https://example.com"
            ],
            "use_browser_rendering": true
          },
          "parse_type": "sitemap"
        }
      },
      "status": "status",
      "summarization": true,
      "summarization_model": "summarization_model",
      "sync_interval": 900,
      "system_prompt_ai_search": "system_prompt_ai_search",
      "system_prompt_index_summarization": "system_prompt_index_summarization",
      "system_prompt_rewrite_query": "system_prompt_rewrite_query",
      "token_id": "token_id",
      "type": "r2"
    }
  ],
  "result_info": {
    "count": 0,
    "page": 0,
    "per_page": 0,
    "total_count": 0
  },
  "success": true
}