Skip to main content
POST
Search the web (JSON body)

Authorizations

x-api-key
string
header
required

API key from the API Console.

Body

application/json
q
string
required

Search query string. Same semantics as the GET q parameter.

limit
integer
default:10

Maximum number of results to return.

Required range: 1 <= x <= 100
offset
integer
default:0

Number of results to skip for pagination.

Required range: x >= 0
searchMode
enum<string>
default:auto

Search effort control. auto (default) sets the effort per query automatically — simple lookups resolve fast, complex questions get deeper treatment. The fixed modes pin an effort level: low-cost caps the work done per request for budget-constrained callers. fast returns results in about 1 second. balanced is everyday web search with mid-range latency. deep searches from multiple angles with spell correction in about 2–3 seconds. exhaustive runs multi-round retrieval for the most complete results, up to about 15 seconds. Deeper modes add query expansion, follow-up searches fanned out from initial results, and stronger reranking. Requests are billed on outcome-based pricing (see metrics.cost_dollars).

Available options:
auto,
low-cost,
fast,
balanced,
deep,
exhaustive
effort
enum<string>

Thoroughness dial, independent of searchMode: low favors speed, medium is balanced, high searches from multiple angles with spell correction, max runs multi-round retrieval for the most complete results — the same tiers as pinning searchMode to fast, balanced, deep, and exhaustive respectively. An explicit searchMode always wins over effort. With the default auto mode, an explicit effort pins its equivalent mode. Omit for the adaptive default. Invalid values return a 400 listing the valid tiers.

Available options:
low,
medium,
high,
max
reranker
enum<string>
default:auto

Semantic reranker size hint. Larger tiers apply more thorough relevance scoring but need a deeper searchMode and may be clamped by the request's time and cost budget (for example, xl needs deep or exhaustive). auto (default) selects a tier automatically based on the query and search mode.

Available options:
auto,
small,
medium,
large,
xl
intent
string

Force a specific search intent. When not set, the API auto-detects intent from the query. Accepts common aliases like search, news, video, images, weather, wiki, code, recipe, place, time, and others.

format
enum<string>
default:json

Response format. json returns a JSON object. context returns results as markdown text, suitable for passing to language models.

Available options:
json,
context
metadata
enum<string>
default:basic

Level of metadata to include. basic includes standard search metrics. full includes extended metadata with content type details and reader data on results.

Available options:
basic,
full
extracts
boolean
default:false

Include text extracts from result pages in the response.

enrichContent
boolean
default:false

Fetch and include full page content for results, beyond the standard description and snippet. Increases response time; the time budget scales with searchMode (more time is allotted for deep and exhaustive).

maxContentLength
integer

Maximum number of characters of enriched content to return per result. Only applies when enrichContent is true.

safe
enum<string>
default:off

Safe search filtering level. off disables filtering, moderate filters most explicit content, strict applies maximum filtering.

Available options:
off,
moderate,
strict
country
string
default:US

Two-letter ISO 3166-1 country code to localize results.

sourceCountry
string

Two-letter ISO 3166-1 country code to restrict results to sources from this country. Unlike country, which biases results by locale, sourceCountry excludes results from other countries.

language
string
default:en

Two-letter ISO 639-1 language code to filter results by language.

units
enum<string>

Unit system for weather and calculation results. Defaults based on the country parameter — imperial for US, metric for all other countries.

Available options:
metric,
imperial
noCache
boolean
default:false

Bypass cached results and fetch fresh data.

dateRange
enum<string>

Relative date range filter for results.

Available options:
day,
week,
month,
year,
24h,
7d,
30d,
90d,
1y
dateFrom
string<date>

Filter results published on or after this date. Format: YYYY-MM-DD.

dateTo
string<date>

Filter results published on or before this date. Format: YYYY-MM-DD.

includeDomains
string

Comma-separated list of domains to restrict results to. Supports wildcards (*.example.com).

excludeDomains
string

Comma-separated list of domains to exclude from results. Supports wildcards.

includeTerms
string

Comma-separated terms that must appear in results.

excludeTerms
string

Comma-separated terms to exclude from results.

parseOperators
boolean
default:true

Parse query operators (like site:, filetype:, intitle:) from the query string. When disabled, the query is treated as literal text.

Field name for result URLs. Use url to receive the URL field as url instead of the default link. Only affects the /search endpoint.

Available options:
link,
url
imageFormat
enum<string>
default:long

Field naming for image results. long (default) uses full field names. short uses abbreviated field names.

Available options:
short,
long
filetype
string

Filter results by file type.

intitle
string

Filter results to pages with this term in the title.

inurl
string

Filter results to pages with this term in the URL.

intext
string

Filter results to pages with this term in the body text.

latitude
number

Latitude in decimal degrees. Sent in the body to keep coordinates out of HTTP access logs.

longitude
number

Longitude in decimal degrees.

accuracy
number

Location accuracy in meters.

city
string

City name for location-aware queries.

state
string

State or region name.

countryCode
string

Two-letter ISO 3166-1 country code for the caller's location.

postalCode
string

Postal or ZIP code.

timezone
string

IANA timezone, for example America/Los_Angeles.

location
string

Display name for the caller's location, for example "San Francisco, CA".

Response

Search results. JSON by default; LLM-ready markdown with YAML frontmatter when format=context.

results_type
string
required

The type of results returned (e.g., Search, News, Weather, Calculator). Determines which optional response sections are present.

answer
string
required

A generated answer for the query. May be an empty string when no direct answer is available.

type
string
required

Same as results_type. Indicates the category of results.

title
string
required

A title summarizing the search results.

results
object[]
required

Array of search results.

metrics
object
required

Search performance metrics. Always included in the response.

correctedQuery
string

Spell-corrected query. Present when a misspelling in the original query is detected and corrected — any mode can return it; deep and exhaustive modes run the strongest spell correction.

Related search suggestions. Present on some queries.

topics
string[]

Related topics. Present on some queries.

videos
object[]

Video results. Present when the query triggers a video intent.

images
object[]

Image results. Present when the query triggers an image intent.

news
object[]

News results. Present when the query triggers a news intent.

places
object[]

Place/business results. Present for location-related queries.

profiles
object[]

Profile results. Present for people-related queries.

social
object[]

Social media results. Present for social-related queries.

academic
object[]

Academic results. Present for scholarly queries.

weather
object

Weather data. Present when the query triggers a weather intent.

calculation
object

Calculation result. Present when the query triggers a calculation intent.