Sign in
Search

Search

Searches the web.

The legacy Search API reference is available here.

post/v1/search

Request body

client_modelstring nullable

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

max_chars_totalinteger nullable

Upper bound on total characters across excerpts from all results.

mode'basic' | 'advanced' nullable

Search mode preset: supported values are basic and advanced. Basic mode offers the lowest 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.

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.

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.

Example request

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

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

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

Changes