Search parameters
Send parameters as a JSON body to POST /v1/search. Only q is required.
| Field | Type | Default | Description |
|---|---|---|---|
q | string (1–500) | — | Required. The search query. |
gl | enum | us | Country edition (see below). |
hl | string | country default | UI / results language, BCP-47 (e.g. en, pt-BR). |
tbs | enum | all time | Time filter: qdr:h (past hour), qdr:d (day), qdr:w (week). |
page | integer (1–99) | 1 | Result page (1-indexed; ~10 organic results each). |
freshness | enum | default | Cache control: default, realtime (force fresh), cached. See Caching. |
scrape | object | — | Attach scraped page content to each organic result (see below). Billed per page — see Pricing. |
Countries (gl)
Section titled “Countries (gl)”br, us, gb, de, fr, es, it, mx, ca, au, jp, nl.
{ "q": "melhores tênis de corrida", "gl": "br", "hl": "pt-BR" }Time filter (tbs)
Section titled “Time filter (tbs)”Restrict results to recent content — ideal for news and trending topics.
{ "q": "nvidia earnings", "tbs": "qdr:d" }Page scraping (scrape)
Section titled “Page scraping (scrape)”Add scrape to pull each result page’s content as markdown — optionally rendering JavaScript and
capturing a screenshot. Or call POST /v1/scrape directly for a single arbitrary URL.
| Field | Type | Default | Description |
|---|---|---|---|
render_js | boolean | false | Render with a headless browser first (JS-heavy sites). |
screenshot | boolean | false | Capture a screenshot (1920×1080 by default, 48h presigned URL). Implies a render. |
top_n | integer (1–20) | 5 | How many of the top organic results to scrape. |
wait_for | string | — | CSS selector to wait for before extracting (render_js only). |
wait_ms | integer (0–5000) | — | Extra settle time after load (render_js only). |
screenshot_width | integer (320–1920) | 1920 | Screenshot width in px. |
screenshot_height | integer (320–1920) | 1080 | Screenshot height in px. |
{ "q": "best running shoes", "scrape": { "render_js": true, "screenshot": true, "top_n": 3 } }Each scraped result gains content (markdown), optionally screenshot_url, or scrape_error when a
page couldn’t be fetched. Only pages scraped successfully are billed.
Pagination (page)
Section titled “Pagination (page)”Each page returns roughly 10 organic results. Request pages 1–99; to collect the first 100 results,
loop pages 1–10. The SDKs expose helpers (searchPages / search_pages) that iterate pages
for you.