LIVE PRODUCT

SERP API

Live search results across four engines through one normalized contract.

SERP API removes parser drift, retry handling, and search engine branching from your application code. Send one search job, poll for completion, and work with normalized search modules instead of raw markup.

Endpoint

POST /v1/search

Poll GET /v1/search/:jobId for the final result payload.

Credits

1 credit per successful request

Pagination and retries that become new successful jobs each bill 1 credit.

Output

Structured JSON + optional markdown

Use markdown=true when you need a prompt-ready rendering of the same SERP.

What it's for

rank tracking across supported engines and locales
SERP features for SEO analytics dashboards
search evidence for AI agents and retrieval workflows
query monitoring for research and ad intelligence
internal tooling that needs stable search response objects

How it works

1Submit a search job with q, engine preference, location context, and output options.
2OrbitScraper enqueues the request and resolves the live SERP through the managed search layer.
3Poll the job endpoint until status is completed, then read the normalized result payload.

Request parameters

These are the fields accepted by the current backend contract for POST /v1/search.

Name	Type	Required	Description
q	string	Yes	Search query text. Maximum length 512 characters.
engine	string	Yes	The search engine to use. Supported values: google, bing, brave, duckduckgo.
allow_fallback	boolean	No	When true, automatically falls back to other healthy engines if the requested engine fails. Defaults to false.
location	string	No	Location context string. Defaults to Global.
gl	string	No	Two-letter country code. Defaults to us.
hl	string	No	Language code such as en or de-DE. Defaults to en.
device	desktop \| mobile	No	Client device context. Defaults to desktop.
num	integer	No	Results requested per page. Defaults to 10. Range 1-20.
page	integer	No	Results page number. Defaults to 1. Range 1-100.
safe	active \| off	No	Safe search mode. Defaults to active.
tbm	string	No	Optional vertical selector. Supported values: isch, nws, vid, lcl.
time_period	string	No	Optional freshness filter. Supported values: past_day, past_week, past_month, past_year.
markdown	boolean	No	Return a markdown rendering alongside JSON fields when true.

Response fields

These fields describe the completed payload you read from the current public API contract.

Name	Type	Description
search_metadata	object	Metadata including id, status, created_at, processing_time_ms, and credits_used.
search_parameters	object	The parameters used to perform the search (q, engine, gl, hl, etc).
search_information	object	Information about the pagination and returned results count.
organic_results	array	The main organic search results from the requested engine.
local_results	array	Local map pack or business results.
knowledge_graph	object	Knowledge graph panel information if present.
people_also_ask	array	Related question snippets.
related_searches	array	Related search queries.
detected_intent	string	The inferred intent of the query.

Code examples

Start with cURL, then switch to Python, JavaScript, Java, or PHP for the same SERP API flow.

Start with the raw HTTP request and poll flow.

bash

curl -X POST "https://api.orbitscraper.com/v1/search" \
  -H "x-api-key: ORS_live_1234567890" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "best ai chips 2026",
    "engine": "google",
    "location": "New York",
    "gl": "us",
    "hl": "en",
    "device": "desktop",
    "num": 10,
    "page": 1,
    "safe": "active",
    "allow_fallback": false,
    "markdown": true
  }'

curl -X GET "https://api.orbitscraper.com/v1/search/search_123456" \
  -H "x-api-key: ORS_live_1234567890"

Response examples

This is the shape you get back from the current public API contract for SERP API.

Queued response

The first response confirms the job was accepted and tells you what to poll next.

json

{
  "success": false,
  "request_id": "req_123456",
  "error": {
    "code": "search_pending",
    "message": "Search accepted and still processing",
    "details": {
      "job_id": "search_123456"
    }
  }
}

Completed response

After polling, this is the final payload shape your app reads.

json

{
  "search_metadata": {
    "id": "req_123456",
    "status": "Success",
    "created_at": "2026-06-15T12:00:00.000Z",
    "processing_time_ms": 320,
    "credits_used": 1
  },
  "search_parameters": {
    "q": "best ai chips 2026",
    "engine": "google",
    "gl": "us",
    "hl": "en",
    "location": "New York",
    "device": "desktop",
    "num": 10,
    "page": 1,
    "safe": "active"
  },
  "search_information": {
    "returned_results": 1,
    "page": 1,
    "num": 10
  },
  "organic_results": [
    {
      "position": 1,
      "title": "Best AI chips in 2026",
      "link": "https://example.com/ai-chips",
      "displayed_link": "example.com",
      "snippet": "A breakdown of current inference leaders."
    }
  ],
  "local_results": [],
  "knowledge_graph": {},
  "people_also_ask": [],
  "related_searches": [],
  "detected_intent": "product"
}

Use x-api-key for all search endpoints. Bearer auth is rejected by the current backend contract.

POST /v1/:engine is also supported when you want to force a single engine in the path.

A successful completed search job consumes 1 credit.

Ready to build on SERP API?

The current backend contract is already live. Use the docs page for request details and the pricing page for credit planning.

View SERP API docs See pricing