Live search

POST /v1/serp/search runs a Google SERP synchronously and returns the parsed result inline. It is the fastest way to get a single SERP — typically ~1 second.

Request

curl -X POST https://api.serplify.io/v1/serp/search \
  -H "Authorization: Bearer live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "coffee shops",
    "location": { "name": "London,England,United Kingdom" },
    "language": { "code": "en" },
    "device": "mobile",
    "format": "advanced",
    "depth": 20
  }'

See the request shape for every field.

Response

HTTP 200 with a SERP result in data:

{
  "request_id": "req_…",
  "status": "ok",
  "meta": { "api_version": "0.1.0", "time": 1.02, "cost": 0.005, "currency": "USD" },
  "data": {
    "keyword": "coffee shops",
    "search_engine": "google",
    "device": "mobile",
    "location": { "code": 2826, "name": "London,England,United Kingdom" },
    "language": { "code": "en", "name": "English" },
    "result_url": "https://www.google.co.uk/search?q=coffee+shops",
    "fetched_at": "2026-07-02T12:00:00.000Z",
    "total_results_count": 512000000,
    "pages_crawled": 1,
    "items_count": 38,
    "feature_types": ["local_pack", "organic", "people_also_ask"],
    "items": [ /* … */ ]
  }
}

Formats

format controls the detail level of data.items:

• advanced (default) — every parsed SERP feature type.
• standard — organic, paid, and featured-snippet items only.
• html — raw page HTML instead of parsed items (see response format).

If the SERP can’t finish in time

If a live request cannot complete within the synchronous budget, it is transparently promoted to an async task and returns HTTP 202:

HTTP 202

{
  "request_id": "req_…",
  "status": "accepted",
  "meta": { "api_version": "0.1.0", "time": 15.0, "cost": 0.005, "currency": "USD" },
  "data": {
    "task_id": "…",
    "keyword": "coffee shops",
    "format": "advanced",
    "status_url": "/v1/serp/tasks/…"
  }
}

Poll status_url (see tasks) to retrieve the result. From that moment the request bills exactly like an async task: the task price (cost in the 202 response) is the single charge — you are never billed the live price on top, and fetching the result is free.

Errors

Failures use the standard error contract, e.g. 422 invalid_location, 402 insufficient_balance, or 502 task_failed.