Sign in
Search (Beta)

Search

Searches the web.

post/v1beta/search

Headers

parallel-betastring nullable

Request body

locationstring nullable

ISO 3166-1 alpha-2 country code for geo-targeted search results.

max_chars_per_resultinteger nullable

DEPRECATED: Use excerpts.max_chars_per_result instead.

max_resultsinteger nullable

Upper bound on the number of results to return. Defaults to 10 if not provided.

mode'one-shot' | 'agentic' | 'fast' nullable

Presets default values for parameters for different use cases.

  • one-shot returns more comprehensive results and longer excerpts to answer questions from a single response
  • agentic returns more concise, token-efficient results for use in an agentic loop
  • fast trades some quality for lower latency, with best results when used with concise and high-quality objective and keyword queries
objectivestring nullable

Natural-language description of what the web search is trying to find. May include guidance about preferred sources or freshness. At least one of objective or search_queries must be provided.

processor'base' | 'pro' nullable

DEPRECATED: use mode instead.

search_queriesstring[] nullable

Optional list of traditional keyword search queries to guide the search. May contain search operators. At least one of objective or search_queries must be provided.

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

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

Response

Successful Response

search_idstring required

Search ID. Example: search_cad0a6d2dec046bd95ae900527d880e7

Example response

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

Changes