Skip to main content
POST
Python

Authorizations

x-api-key
string
header
required

Headers

parallel-beta
string | null
deprecated

Body

application/json

Request to Search API.

mode
enum<string> | null
default:one-shot

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
Available options:
one-shot,
agentic,
fast
objective
string | null

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.

search_queries
string[] | null

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.

processor
enum<string> | null
deprecated

DEPRECATED: use mode instead.

Available options:
base,
pro
max_results
integer | null

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

max_chars_per_result
integer | null
deprecated

DEPRECATED: Use excerpts.max_chars_per_result instead.

excerpts
ExcerptSettings · object

Optional settings to configure excerpt generation.

location
string | null

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

Example:

"us"

source_policy
SourcePolicy · object | null

Optional source policy governing domain and date preferences in search results.

fetch_policy
FetchPolicy · object | null

Fetch policy: determines when to return cached content from the index (faster) vs fetching live content (fresher). Default is to disable live fetch and return cached content from the index.

session_id
string | null

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.

Maximum string length: 1000
client_model
string | null

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

Example:

"claude-opus-4-7"

Response

Successful Response

Output for the Search API.

search_id
string
required

Search ID. Example: search_cad0a6d2dec046bd95ae900527d880e7

results
WebSearchResult · object[]
required

A list of WebSearchResult objects, ordered by decreasing relevance.

warnings
Warning · object[] | null

Warnings for the search request, if any.

usage
UsageItem · object[] | null

Usage metrics for the search request.