Sign in

v19

latestOpenAPI 3.1.0raw.githubusercontent.com2026-06-084091267.1 KB
Search

Search

Searches the web.

The legacy Search API reference (/v1beta/search endpoint) is available here, and migration guide is here.

post/v1/search

Request body

objectivestring nullable

Natural-language description of the underlying question or goal driving the search. Used together with search_queries to focus results on the most relevant content. Should be self-contained with enough context to understand the intent of the search.

search_queriesstring[] required

Concise keyword search queries, 3-6 words each. At least one query is required, provide 2-3 for best results. Used together with objective to focus results on the most relevant content.

mode'turbo' | 'basic' | 'advanced' nullable

Search mode preset: supported values are turbo, basic, and advanced. Turbo mode is optimized for the fastest responses. Basic mode offers low latency and works best with 2-3 high-quality search_queries. Advanced mode provides higher quality with more advanced retrieval and compression. Defaults to advanced when omitted.

max_chars_totalinteger nullable

Upper bound on total characters across excerpts from all results.

session_idstring nullable

Session identifier to track calls across separate search and extract calls, to be used as part of a larger task. Specifying it may give better contextual results for subsequent API calls.

client_modelstring nullable

The model generating this request and consuming the results. Enables optimizations and tailors default settings for the model's capabilities.

Example request

{
  "client_model": "claude-opus-4-7",
  "advanced_settings": {
    "source_policy": {
      "include_domains": [
        "wikipedia.org",
        "usa.gov",
        ".edu"
      ],
      "exclude_domains": [
        "reddit.com",
        "x.com",
        ".ai"
      ],
      "after_date": "2024-01-01"
    },
    "fetch_policy": {
      "max_age_seconds": 86400,
      "timeout_seconds": 60
    },
    "location": "us"
  }
}

Response

Successful Response

search_idstring required

Search ID. Example: search_cad0a6d2dec046bd95ae900527d880e7

session_idstring required

Session identifier, echoed back from the request if provided, otherwise generated by the server. Should be passed to future search and extract calls made by the agent as part of the same larger task.

Example response

{
  "warnings": [
    {
      "type": "spec_validation_warning"
    }
  ],
  "usage": [
    {
      "name": "sku_search_additional_results",
      "count": 1
    }
  ],
  "session_id": "session_8a911eb27c7a4afaa20d0d9dc98d07c0"
}