docs / endpoint

POST /v1/search

Run one search query and get the parsed SERP back — ranked items, not raw HTML.

Credits: 1 credit at the default depth (10 results); 10 credits at depth=100. Timeout: 180s

Parameters

Name	Type	Required	Default	Description
`query`	string	required	—	Search query text. Required, max 700 chars.
`engine`	string	optional	`"google"`	Search engine. Optional, default "google". One of: bing, google.
`location`	any	optional	`2840`	Google Ads geotarget ID, an ISO country code (e.g. "US"), or a country name. Optional, default 2840 (United States). Look one up with /v1/locations.
`language`	string	optional	`"en"`	ISO language code. Optional, default "en".
`device`	string	optional	`"desktop"`	One of: desktop, mobile. Optional, default "desktop".
`depth`	integer	optional	`10`	up to 10 results — 1 credit (default); up to 100 results — 10 credits. Bing returns up to 50 at depth=100.

Request

→ requestPOST /v1/search

POST /v1/search HTTP/1.1
Authorization: Bearer sof_live_your_key_here
Content-Type: application/json

{
  "query": "best running shoes"
}

Response

The usual envelope (id, request_id, object, created_at, elapsed_ms, credits) is documented once on The Contract. Below is an example response with this endpoint's data. Values vary per request; … marks an array cut short.

← response200

{
  "id": "srch_7f34stnlffnsbalonq66dpuj",
  "request_id": "req_7e5465ge5fjmziqx5dyueaqyvy",
  "object": "search",
  "created_at": "2026-07-29T12:00:00Z",
  "elapsed_ms": 244,
  "credits": {
    "charged": 1,
    "balance": 9857
  },
  "data": {
    "query": "best running shoes",
    "engine": "google",
    "location": 2840,
    "language": "en",
    "device": "desktop",
    "total_results": 84900000,
    "serp_url": "https://www.google.com/search?q=best+running+shoes",
    "result_types": [
      "organic"
    ],
    "results_count": 10,
    "items": [
      {
        "type": "organic",
        "rank": 1,
        "page": 1,
        "domain": "example.com",
        "title": "The 12 Best Running Shoes",
        "url": "https://example.com/best-running-shoes",
        "description": "Our team tested 40 pairs...",
        "displayed_link": "example.com › reviews › shoes",
        "date": null,
        "site_name": "Example Running Co.",
        "rating": {
          "value": 4.6,
          "votes": 1284,
          "max": 5
        },
        "sitelinks": [
          {
            "title": "Best Trail Running Shoes",
            "url": "https://example.com/best-running-shoes/trail",
            "description": null
          },
          {
            "title": "Best Budget Running Shoes",
            "url": "https://example.com/best-running-shoes/budget",
            "description": null
          }
        ],
        "price": null,
        "highlighted_words": [
          "running shoes"
        ]
      }
    ]
  }
}

Response fields

What each field in data (above) means.

Field	Description
`data.query`	The query string you sent.
`data.engine`	Search engine that served this result set.
`data.location`	Google Ads geotarget ID this call ran against.
`data.language`	ISO language code this call ran against.
`data.device`	Device profile this search ran as.
`data.total_results`	The search engine's own on-page estimate for the query, not the number of items here. null when the page shows none (most modern result pages), and can be 0 beside real results when the engine says so.
`data.serp_url`	URL of the search-results page that was fetched, or null if the engine didn't report one.
`data.result_types`	Distinct SERP item types observed on the page.
`data.results_count`	Number of entries in items.
`data.items`	One parsed result per SERP item. Not sorted by rank: rank counts within each item's type.
`data.items[].type`	Item type. Each type has its own field set; see the per-type tables below.
`data.items[].rank`	1-based position among results of the same type -- for organic results, the rank you track. Single-instance blocks (AI overview, featured snippet, People Also Ask) are always 1.
`data.items[].page`	Present on organic and paid items only -- other item types carry a different field set (see the per-type tables below). Results page number this item was found on (1 for the first page).
`data.items[].domain`	Registrable domain hosting the result.
`data.items[].title`	Result title.
`data.items[].url`	Result URL.
`data.items[].description`	Result description/snippet text, or null if the result carries none.
`data.items[].displayed_link`	The line shown under the title -- usually the page's path (site › section › page), sometimes a comment count or age.
`data.items[].date`	Date text as the results page displayed it (e.g. "Jan 6, 2020", localised), or null.
`data.items[].site_name`	Publisher or site name shown next to the result, if the SERP surfaced one; null otherwise.
`data.items[].rating`	Star rating block ({value, votes, max}), or null if the result carries no rating.
`data.items[].sitelinks`	Sub-links shown under the result; empty array if none.
`data.items[].price`	Price block ({amount, currency, displayed}), or null if the result carries no price.
`data.items[].highlighted_words`	Query terms the engine bolded in the snippet; empty array if none were highlighted.

SERP item fields

data.items[] holds a different field set per item's type. One table below per type.

featured_snippet, images, top_stories, and shopping currently return only type and rank.

`ai_overview`

Field	Description
`type`	Always "ai_overview".
`rank`	1-based position among ai_overview items; a SERP carries one such block, so this is 1.
`is_async`	True when the engine loaded the AI Overview asynchronously; false when it rendered with the rest of the page.
`items`	The overview's text blocks, in order.
`items[].title`	Block heading, or null.
`items[].text`	Block body text, or null.
`items[].images`	Image URLs shown in this block; empty when none.
`items[].references`	Sources cited by this block; empty when none.
`items[].references[].source`	Citation label as the engine displayed it, or null.
`items[].references[].domain`	Registrable domain of the cited page.
`items[].references[].url`	URL of the cited page.
`items[].references[].title`	Cited page's title, or null.
`items[].references[].text`	Excerpt the engine quoted from the cited page, or null.
`references`	Every source cited anywhere in the overview, flattened across all blocks; empty when none.
`references[].source`	Citation label as the engine displayed it, or null.
`references[].domain`	Registrable domain of the cited page.
`references[].url`	URL of the cited page.
`references[].title`	Cited page's title, or null.
`references[].text`	Excerpt the engine quoted from the cited page, or null.

`knowledge_graph`

Field	Description
`type`	Always "knowledge_graph".
`rank`	1-based position among knowledge_graph items; a SERP normally carries one panel, so this is normally 1.
`title`	Subject name, or null.
`subtitle`	Short descriptor under the title, e.g. a role or category, or null.
`description`	Longer description text, or null.
`url`	Link to the subject's own site, or null.
`image_url`	Photo URL, or null.
`logo_url`	Logo URL, or null.
`attributes`	Extra label/value facts about the subject (e.g. founding date, headquarters); empty when none.

`local_pack`

Field	Description
`type`	Always "local_pack".
`rank`	1-based position among local results.
`title`	Business name, or null.
`description`	Short description text, or null.
`category`	Business category, e.g. "Running store", or null.
`address`	Street address as shown, or null.
`domain`	Registrable domain of the business's own site, or null.
`phone`	Phone number as shown, or null.
`url`	Link to the business's own site, or null.
`is_paid`	True if this is a paid placement.
`rating`	Star rating block ({value, votes, max}), or null if the result carries no rating.
`price`	Price block ({amount, currency, displayed}), or null if the result carries no price.
`latitude`	Latitude, or null.
`longitude`	Longitude, or null.

`organic`

Field	Description
`type`	Always "organic".
`rank`	1-based position among organic results -- the rank you track.
`page`	Results page number this item was found on (1 for the first page).
`domain`	Registrable domain hosting the result.
`title`	Result title.
`url`	Result URL.
`description`	Result description/snippet text, or null if the result carries none.
`displayed_link`	The line shown under the title -- usually the page's path (site › section › page), sometimes a comment count or age.
`date`	Date text as the results page displayed it (e.g. "Jan 6, 2020", localised), or null.
`site_name`	Publisher or site name shown next to the result, if the SERP surfaced one; null otherwise.
`rating`	Star rating block ({value, votes, max}), or null if the result carries no rating.
`sitelinks`	Sub-links shown under the result; empty array if none.
`price`	Price block ({amount, currency, displayed}), or null if the result carries no price.
`highlighted_words`	Query terms the engine bolded in the snippet; empty array if none were highlighted.

`paid`

Field	Description
`type`	Always "paid".
`rank`	1-based position among paid (ad) results.
`page`	Results page number this item was found on (1 for the first page).
`domain`	Registrable domain hosting the result.
`title`	Result title.
`url`	Result URL.
`description`	Result description/snippet text, or null if the result carries none.
`displayed_link`	The line shown under the title -- usually the page's path (site › section › page), sometimes a comment count or age.
`date`	Date text as the results page displayed it (e.g. "Jan 6, 2020", localised), or null.
`site_name`	Publisher or site name shown next to the result, if the SERP surfaced one; null otherwise.
`rating`	Star rating block ({value, votes, max}), or null if the result carries no rating.
`sitelinks`	Sub-links shown under the result; empty array if none.
`price`	Price block ({amount, currency, displayed}), or null if the result carries no price.
`highlighted_words`	Query terms the engine bolded in the snippet; empty array if none were highlighted.

`people_also_ask`

Field	Description
`type`	Always "people_also_ask".
`rank`	1-based position among people_also_ask items; a SERP carries one such block, so this is 1.
`items`	The questions the engine surfaced, in order.
`items[].question`	The question text.
`items[].seed_question`	Question this one was inserted as a follow-up to, or null if it appeared without one.
`items[].answers`	This question's answer; an empty array unless the results page shipped the answer already expanded.
`items[].answers[].featured_title`	Headline text shown above the answer body, or null.
`items[].answers[].title`	The answer's title, or null.
`items[].answers[].url`	Link to the answer's source page, or null.
`items[].answers[].domain`	Registrable domain of the answer's source page, or null.
`items[].answers[].description`	The answer body text, or null.
`items[].answers[].date`	Date text as shown, or null.
`items[].answers[].images`	Image URLs shown in the answer; empty when none.
`items[].answers[].table`	Table block shown in the answer ({header, rows}), or null when the answer carries no table.
`items[].answers[].table.header`	Column headers, as text.
`items[].answers[].table.rows`	Table rows; each entry is a list of cell text for that row.

`related_searches`

Field	Description
`type`	Always "related_searches".
`rank`	1-based position among related_searches items; a SERP carries one such block, so this is 1.
`items`	Suggested follow-up queries, as plain text.

`video`

Field	Description
`type`	Always "video".
`rank`	1-based position among video items; a SERP normally carries one video block, so this is normally 1.
`items`	The videos in this block, in order.
`items[].title`	Video title, or null.
`items[].source`	Source line as shown, e.g. view count and age, or null.
`items[].url`	Video URL, or null.
`items[].date`	Upload/publish date as text, when the SERP shows one; null otherwise.