API ReferenceSearch

Search

View as Markdown
Run one or more web searches; return merged, de-duplicated results. For `depth` in {instant, fast, auto} this is synchronous: the response is the full `SearchResponse`. For `depth='deep'` the response is HTTP 202 with a `SearchRunView` carrying a `search_id` - poll GET /v1/searches/{search_id}, stream events via SSE (/v1/searches/{search_id}/events) or WebSocket (/v1/searches/{search_id}/ws), or pass a `webhook` URL on the body to receive the finished run.

Authentication

AuthorizationBearer
Your API key, sent as a Bearer token.

Request

This endpoint expects an object.
querieslist of stringsRequired

Keyword search queries to run; their results are merged and de-duplicated. Provide 1-5.

objectivestring or nullOptional

Natural-language description of what the caller is looking for. When set, results are automatically re-ranked by their relevance to this objective using a fast LLM pass - off-topic rows are dropped. Also focuses excerpts when advanced_settings.contents.highlights/summary is requested.

depthenumOptionalDefaults to auto

‘instant’ (~200ms, top of page, no enrichment), ‘fast’ (~450ms, single SERP page), ‘auto’ (~1s, recommended), ‘deep’ (~4-18s, multi-page gather + merge).

modeenum or nullOptional

Alias of depth (basic -> fast, advanced -> auto). If both are supplied, depth wins.

categoryenum or nullOptional

Result category hint. One of: company, research_paper, news, personal_site, financial_report, people.

limitintegerOptional1-100Defaults to 10
Maximum merged results to return.
countrystringOptionalDefaults to us

Two-letter country code to localize results.

locationstring or nullOptional

Alias of country (Parallel-style). If both are supplied, country wins.

languagestringOptionalDefaults to en
UI language code.
freshnessenum or nullOptional

Restrict to recent results: hour, day, week, month or year.

include_domainslist of strings or nullOptional
Only return results whose URL is on these domains.
exclude_domainslist of strings or nullOptional
Drop results whose URL is on these domains.
max_excerpt_charsinteger or nullOptional>=1
Cap on total excerpt characters across all results.
session_idstring or nullOptional

Optional caller-supplied session id. Echoed back; if absent a new one is generated.

client_modelstring or nullOptional

Caller’s model identifier. Echoed only; not used.

advanced_settingsobject or nullOptional

Envelope for advanced tuning - source policy (include/exclude domains, date window), excerpt sizing, and inline second-pass content extraction.

webhookstring or nullOptional

If set, deep-mode (depth='deep') runs POST the finished payload to this URL. Ignored for non-deep depths (which return synchronously).

promptstring or nullOptional

Research question for the agentic deep-research engine (only applied when depth='deep'). When absent, the engine falls back to joining queries.

max_subqueriesinteger or nullOptional1-12

Caps the planner’s sub-query count (deep only). Default 8.

max_fetchesinteger or nullOptional1-30

Global cap on pages fetched across all sub-queries (deep only). Default 18.

Response

Successful Response

Errors

422
Unprocessable Entity Error