Skip to content
serp.cheap

Run a Google search and return structured SERP data.

POST
/v1/search
 
curl --request POST \
  --url https://api.serp.cheap/v1/search \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '{ "q": "example", "gl": "br", "hl": "example", "tbs": "qdr:h", "page": 1, "scrape": { "render_js": false, "screenshot": false, "top_n": 5, "wait_for": "example", "wait_ms": 1, "screenshot_width": 1920, "screenshot_height": 1080 } }'

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”
Media type application/json
object
q
required

The search query.

string
>= 1 characters <= 500 characters
gl
string
default: us
Allowed values: br us gb de fr es it mx ca au jp nl
hl

UI language (BCP-47-ish, e.g. “en”, “pt-BR”).

string
<= 8 characters /^[a-z]{2}(-[A-Z]{2})?$/
tbs

Time filter — past hour/day/week.

string
Allowed values: qdr:h qdr:d qdr:w
page
integer
default: 1 >= 1 <= 99
scrape

Opt-in page-content scraping attached to a search. Each result page scraped successfully is billed on top of the search (1 content / 3 render JS / +1 screenshot).

object
render_js

Render with a headless browser before extracting (JS-heavy sites).

boolean
screenshot

Capture a screenshot (1920x1080 by default, 48h presigned URL). Implies a browser render.

boolean
top_n

How many of the top organic results to scrape.

integer
default: 5 >= 1 <= 20
wait_for

CSS selector to wait for before extracting (render_js only).

string
<= 200 characters
wait_ms

Extra settle time after load, in ms (render_js only).

integer
<= 5000
screenshot_width

Screenshot width in px (default 1920, max 1920).

integer
default: 1920 >= 320 <= 1920
screenshot_height

Screenshot height in px (default 1080, max 1920).

integer
default: 1080 >= 320 <= 1920

Responses

Section titled “ Responses ”

200

Section titled “200 ”

A parsed SERP.

Media type application/json
object
search
required
string
page
required
integer
knowledgeGraph
object
title
required
string
imageUrl
string
description
string
descriptionSource
string
descriptionLink
string
attributes
object
key
additional properties
string
organic
required
Array<object>
object
position
required
integer
title
required
string
link
required
string
snippet
required
string
date
string
sitelinks
Array<object>
object
title
required
string
link
required
string
content

Scraped page content as markdown (present when scrape was requested and succeeded).

string
screenshot_url

Screenshot (1920x1080 by default), 48h presigned URL (present when scrape.screenshot was requested).

string
scrape_error

Why this page couldn’t be scraped (not billed). Mutually exclusive with content.

string
ads
Array<object>
object
position
required
integer
title
required
string
link
required
string
displayedLink
string
snippet
string
block
required

“top” or “bottom”

string
sitelinks
Array<object>
object
title
required
string
link
required
string
peopleAlsoAsk
Array<string>
relatedSearches
Array<object>
object
query
required
string
link
required
string
stats
object
balance
required

Credits remaining after this search.

integer
cost
required

Credits charged (6 fresh / 3 cache hit).

integer
cached
required
boolean
Example generated
{
  "search": "example",
  "page": 1,
  "knowledgeGraph": {
    "title": "example",
    "imageUrl": "example",
    "description": "example",
    "descriptionSource": "example",
    "descriptionLink": "example",
    "attributes": {
      "additionalProperty": "example"
    }
  },
  "organic": [
    {
      "position": 1,
      "title": "example",
      "link": "example",
      "snippet": "example",
      "date": "example",
      "sitelinks": [
        {
          "title": "example",
          "link": "example"
        }
      ],
      "content": "example",
      "screenshot_url": "example",
      "scrape_error": "example"
    }
  ],
  "ads": [
    {
      "position": 1,
      "title": "example",
      "link": "example",
      "displayedLink": "example",
      "snippet": "example",
      "block": "example",
      "sitelinks": [
        {
          "title": "example",
          "link": "example"
        }
      ]
    }
  ],
  "peopleAlsoAsk": [
    "example"
  ],
  "relatedSearches": [
    {
      "query": "example",
      "link": "example"
    }
  ],
  "stats": {
    "balance": 1,
    "cost": 1,
    "cached": true
  }
}

400

Section titled “400 ”

A typed error.

Media type application/json
object
error
required

Machine code: invalid_request, missing_api_key, unknown_api_key, inactive_api_key, account_blocked, insufficient_credits, rate_limited, request_in_progress, too_many_concurrent_requests, service_temporarily_unavailable, result_timeout.

string
message
string
details
retry_after_ms
integer
required
integer
balance
integer
Example generated
{
  "error": "example",
  "message": "example",
  "details": "example",
  "retry_after_ms": 1,
  "required": 1,
  "balance": 1
}

401

Section titled “401 ”

A typed error.

Media type application/json
object
error
required

Machine code: invalid_request, missing_api_key, unknown_api_key, inactive_api_key, account_blocked, insufficient_credits, rate_limited, request_in_progress, too_many_concurrent_requests, service_temporarily_unavailable, result_timeout.

string
message
string
details
retry_after_ms
integer
required
integer
balance
integer
Example generated
{
  "error": "example",
  "message": "example",
  "details": "example",
  "retry_after_ms": 1,
  "required": 1,
  "balance": 1
}

402

Section titled “402 ”

A typed error.

Media type application/json
object
error
required

Machine code: invalid_request, missing_api_key, unknown_api_key, inactive_api_key, account_blocked, insufficient_credits, rate_limited, request_in_progress, too_many_concurrent_requests, service_temporarily_unavailable, result_timeout.

string
message
string
details
retry_after_ms
integer
required
integer
balance
integer
Example generated
{
  "error": "example",
  "message": "example",
  "details": "example",
  "retry_after_ms": 1,
  "required": 1,
  "balance": 1
}

403

Section titled “403 ”

A typed error.

Media type application/json
object
error
required

Machine code: invalid_request, missing_api_key, unknown_api_key, inactive_api_key, account_blocked, insufficient_credits, rate_limited, request_in_progress, too_many_concurrent_requests, service_temporarily_unavailable, result_timeout.

string
message
string
details
retry_after_ms
integer
required
integer
balance
integer
Example generated
{
  "error": "example",
  "message": "example",
  "details": "example",
  "retry_after_ms": 1,
  "required": 1,
  "balance": 1
}

409

Section titled “409 ”

A typed error.

Media type application/json
object
error
required

Machine code: invalid_request, missing_api_key, unknown_api_key, inactive_api_key, account_blocked, insufficient_credits, rate_limited, request_in_progress, too_many_concurrent_requests, service_temporarily_unavailable, result_timeout.

string
message
string
details
retry_after_ms
integer
required
integer
balance
integer
Example generated
{
  "error": "example",
  "message": "example",
  "details": "example",
  "retry_after_ms": 1,
  "required": 1,
  "balance": 1
}

422

Section titled “422 ”

A typed error.

Media type application/json
object
error
required

Machine code: invalid_request, missing_api_key, unknown_api_key, inactive_api_key, account_blocked, insufficient_credits, rate_limited, request_in_progress, too_many_concurrent_requests, service_temporarily_unavailable, result_timeout.

string
message
string
details
retry_after_ms
integer
required
integer
balance
integer
Example generated
{
  "error": "example",
  "message": "example",
  "details": "example",
  "retry_after_ms": 1,
  "required": 1,
  "balance": 1
}

429

Section titled “429 ”

A typed error.

Media type application/json
object
error
required

Machine code: invalid_request, missing_api_key, unknown_api_key, inactive_api_key, account_blocked, insufficient_credits, rate_limited, request_in_progress, too_many_concurrent_requests, service_temporarily_unavailable, result_timeout.

string
message
string
details
retry_after_ms
integer
required
integer
balance
integer
Example generated
{
  "error": "example",
  "message": "example",
  "details": "example",
  "retry_after_ms": 1,
  "required": 1,
  "balance": 1
}

503

Section titled “503 ”

A typed error.

Media type application/json
object
error
required

Machine code: invalid_request, missing_api_key, unknown_api_key, inactive_api_key, account_blocked, insufficient_credits, rate_limited, request_in_progress, too_many_concurrent_requests, service_temporarily_unavailable, result_timeout.

string
message
string
details
retry_after_ms
integer
required
integer
balance
integer
Example generated
{
  "error": "example",
  "message": "example",
  "details": "example",
  "retry_after_ms": 1,
  "required": 1,
  "balance": 1
}