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

NameTypeRequiredDefaultDescription
query string required — Search query text. Required, max 700 chars.
engine string optional "google" Search engine. Optional, default "google". One of: google, google-maps, google-news, google-images, google-shopping, bing, yandex, youtube.
location any optional 2840 Google Ads geotarget ID. 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 10 results — 1 credit (default); 100 results — 10 credits.

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

Wrapped in the standard envelope -- id, object, created_at, elapsed_ms, cache, credits -- documented once on The Contract. The body below is a real envelope with this endpoint's data shape; values vary per request, and a … marks an array cut short for display.

← response200
{
  "id": "srch_vaqa36dz2qble5iobr3wz2eb",
  "request_id": "req_kp6yi3y2ojevfnzoqeemujf2my",
  "object": "search",
  "created_at": "2026-08-08T17:16:27Z",
  "elapsed_ms": 142,
  "cache": "miss",
  "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": [
          {
            "type": "sitelink",
            "title": "Best Trail Running Shoes",
            "description": null,
            "url": "https://example.com/best-running-shoes/trail"
          },
          {
            "type": "sitelink",
            "title": "Best Budget Running Shoes",
            "description": null,
            "url": "https://example.com/best-running-shoes/budget"
          }
        ],
        "price": null
      }
    ]
  }
}

Response fields

What each field in data (above) means.

FieldDescription
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 the search was simulated from.
data.total_results The search engine's own total-results estimate for the query -- not the number of items in this response.
data.serp_url URL of the search-results page that was fetched.
data.result_types Distinct SERP item types observed on the page. Only "organic" is populated today.
data.results_count Number of entries in items.
data.items One parsed result per SERP item, in rank order.
data.items[].type Item type. Only "organic" is populated today.
data.items[].rank 1-based rank on the results page.
data.items[].page 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.
data.items[].displayed_link Breadcrumb-style path shown under the title.
data.items[].date Result date, if the SERP surfaced one; null otherwise.
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[].sitelinks[].type Sitelink type, e.g. "sitelink".
data.items[].sitelinks[].title Sitelink title.
data.items[].sitelinks[].url Sitelink URL.
data.items[].sitelinks[].description Sitelink description, or null if the SERP didn't include one.
data.items[].price Price block ({current, currency, displayed}), or null if the result carries no price.