API Documentation

Complete guide to integrating OrbitScraper as a reliable SERP Data API for SEO platforms, analytics tools, and market research applications.

Introduction

OrbitScraper is a Search Engine Results Data API and search analytics infrastructure that returns normalized JSON from major search engines through a single integration.

Base URL: https://api.orbitscraper.com

Authenticate requests using your `x-api-key` header.
Send a JSON request body with query, location, language, and device fields.
Receive structured JSON responses with organic results and SERP modules.
Optionally return a markdown summary for AI agents, copilots, and LLM workflows.
Run concurrent requests within your plan's allocated concurrency.
Respect plan-based rate limits and monitor usage in the dashboard.

Authentication

Get your API key

ORS_*********b4c2

Use `x-api-key` for `/v1/search`. Session routes rely on an HttpOnly cookie sent with `credentials: "include"`.

Search Endpoint

Endpoint

POST /v1/search

Code Examples

Curl

curl

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

JavaScript

const apiBase = "https://api.orbitscraper.com";
const apiKey = "ORS_XXXX";
const searchPayload = {
  q: "best running shoes",
  location: "New York",
  gl: "us",
  hl: "en",
  device: "desktop",
  num: 10,
  page: 1,
  safe: "active",
  markdown: true
};

const result = await runOrbitSearch(apiBase, apiKey, searchPayload);
console.log(result.markdown);

Python

import requests

api_base = "https://api.orbitscraper.com"
api_key = "ORS_XXXX"

search_payload = {
    "q": "best running shoes",
    "location": "New York",
    "gl": "us",
    "hl": "en",
    "device": "desktop",
    "num": 10,
    "page": 1,
    "safe": "active",
    "markdown": True
}

result = run_orbit_search(api_base, api_key, search_payload)
print(result.get("markdown", ""))

Search Engines

OrbitScraper supports Google, Bing, Brave, and DuckDuckGo. You can choose the engine directly from the URL.

Use `POST /v1/search` for automatic routing, or call `POST /v1/google`, `POST /v1/bing`, `POST /v1/brave`, or `POST /v1/duckduckgo` to force a specific engine.

All engines return the same normalized JSON response shape.

Google

https://api.orbitscraper.com/v1/google

Use this endpoint when you want Google-first execution.

Bing

https://api.orbitscraper.com/v1/bing

Use this endpoint when you want Bing-first execution.

Brave

https://api.orbitscraper.com/v1/brave

Use this endpoint when you want Brave-first execution.

DuckDuckGo

https://api.orbitscraper.com/v1/duckduckgo

Use this endpoint when you want DuckDuckGo-first execution.

Engine-specific endpoints

bash

# Auto routing (recommended)
POST https://api.orbitscraper.com/v1/search

# Force Google
POST https://api.orbitscraper.com/v1/google

# Force Bing
POST https://api.orbitscraper.com/v1/bing

# Force Brave
POST https://api.orbitscraper.com/v1/brave

# Force DuckDuckGo
POST https://api.orbitscraper.com/v1/duckduckgo

Request body (same for all engine endpoints)

JSON

{
  "q": "best running shoes",
  "location": "New York",
  "gl": "us",
  "hl": "en",
  "device": "desktop",
  "num": 10,
  "page": 1
}

Vertical request example (news)

JSON

{
  "q": "AI chip launches",
  "location": "San Francisco",
  "gl": "us",
  "hl": "en",
  "device": "mobile",
  "tbm": "nws",
  "time_period": "past_week",
  "num": 10,
  "page": 1
}

API Key Lifecycle

API keys are tenant-bound and project-bound. Each key includes `keyId`, scopes, status (`active` or `revoked`), optional `expiresAt`, `lastUsedAt`, and policy overrides (`rpmLimit`, `tenantRpmLimit`, `monthlyQuota`).

Rotation uses overlap windows: old key stays valid until `rotateUntil`, then naturally expires.

Create scoped key

curl

curl -X POST "https://api.orbitscraper.com/keys" \
  -H "Cookie: session=USER_SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{
    "projectName": "production",
    "scopes": ["search:read", "usage:read"],
    "expiresAt": "2026-12-31T00:00:00.000Z",
    "rpmLimit": 240,
    "tenantRpmLimit": 1200,
    "monthlyQuota": 100000
  }'

List keys response

JSON

{
  "keys": [
    {
      "id": "7c1d8f41-58ad-4c35-b37f-5f611d1b8e59",
      "keyId": "key_7628ef8e2acb0c3f",
      "keyPreview": "ORS...4c2a",
      "status": "active",
      "scopes": ["search:read", "usage:read"],
      "tenantId": "tenant_8d7...",
      "projectId": "proj_93f...",
      "projectName": "production",
      "createdAt": "2026-02-11T16:52:10.000Z",
      "expiresAt": "2026-12-31T00:00:00.000Z",
      "isExpired": false,
      "lastUsedAt": "2026-02-11T17:01:33.000Z",
      "rpmLimit": 240,
      "tenantRpmLimit": 1200,
      "monthlyQuota": 100000
    }
  ]
}

Query Parameters

These fields are sent in the JSON body of `POST /v1/search`.

Search query string

Required

location

Geo target for localized results (default: Global)

Optional

Country code (2 letters) (default: us)

Optional

Language code (default: en)

Optional

device

desktop or mobile (default: desktop)

Optional

num

Results per page (1-20) (default: 10)

Optional

page

Page number (1-100) (default: 1)

Optional

safe

Safe search mode: active|off (default: active)

Optional

markdown

When true, also returns a markdown field for AI or agent workflows (default: false)

Optional

tbm

Vertical: isch|nws|vid|lcl

Optional

time_period

past_day|past_week|past_month|past_year

Optional

Response Format

This section shows the final structured response payload your user-facing application should consume.

For pagination, request each page explicitly with `page` in the search payload. Each page returns its own `search_information.page`.

Set `markdown=true` when you want the same response packaged as a markdown string for AI agents or markdown-native tools.

JSON

{
  "search_metadata": {
    "created_at": "2026-02-11T12:30:00.000Z",
    "processing_time_ms": 320,
    "credits_used": 1,
    "source": "live",
    "engine": "google"
  },
  "search_parameters": {
    "q": "best running shoes 2026",
    "location": "New York",
    "gl": "us",
    "hl": "en",
    "device": "desktop",
    "num": 10,
    "page": 1,
    "safe": "active",
    "markdown": true
  },
  "search_information": {
    "returned_results": 10,
    "page": 1,
    "num": 10
  },
  "organic_results": [
    {
      "position": 1,
      "title": "Best Running Shoes of 2026",
      "link": "https://example.com/best-running-shoes",
      "displayed_link": "example.com",
      "snippet": "Our top picks for stability and speed."
    }
  ],
  "ads": [],
  "local_results": [],
  "knowledge_graph": {},
  "people_also_ask": [],
  "related_searches": [],
  "detected_intent": "product",
  "markdown": "# Search Results\n\n- Query: best running shoes 2026\n- Engine: google\n- Location: New York\n- Results returned: 10"
}

Markdown response example

When `markdown=true`, the same structured result also includes a ready-to-use markdown summary.

markdown

# Search Results

- Query: best running shoes 2026
- Engine: google
- Location: New York
- Results returned: 10
- Processing time: 320 ms
- Source: live

## Organic Results

### 1. Best Running Shoes of 2026
- URL: https://example.com/best-running-shoes
- Display: example.com
- Snippet: Our top picks for stability and speed.

search_metadata

Request metadata including processing_time_ms, credits_used, source (live or cache), and resolved engine.

search_parameters

Normalized request inputs used to generate this result (q, location, gl, hl, device, num, page, safe, optional vertical/time filters).

search_information

Pagination/result summary for this response page: returned_results, page, and num.

organic_results

Primary organic listings with position, title, link, displayed_link, and snippet.

ads

Sponsored placements when available. This field may be empty depending on engine/query and rollout state.

local_results

Local pack business entries when present for local-intent queries.

people_also_ask, related_searches

SERP expansion modules for related questions and query suggestions.

detected_intent

Intent classification derived from query context (for example product, informational, or local_business).

markdown

Returned only when markdown=true. This is a preformatted markdown summary of the same SERP data for AI agents, LLM pipelines, or markdown-native tools.

Error Codes

400

Bad Request

401

Unauthorized (API key)

403

Forbidden (scope or tenant mismatch)

402

Insufficient Credits

429

Too Many Requests / Quota Exceeded

500

Internal Server Error

Rate Limits

Limits are enforced per user. Each user plan is allocated with matching concurrency and request-per-minute capacity.

Free

up to 50 req/min

Starter

up to 500 req/min

Pro

up to 5000 req/min

Custom

up to 15000 req/min

Credit System

1 credit = 1 successful search request.

Credits are deducted only when a request succeeds, including cached successful responses.

There are no extra credit multipliers for universal mode, location targeting, device type, or language.

Need help?

We can help you optimize your usage and limits.

99.9% uptime

Avg response 2.1 sec

Transparent usage billing

Trust & Buyer FAQ

Answers to common pre-purchase questions about credits, scale, reliability, and response quality.

Is 1 credit exactly equal to 1 SERP request?

Yes. Each successful /v1/search request consumes exactly 1 credit.

Does pagination consume additional credits?

Yes. page=2, page=3, and so on are separate requests, and each successful request consumes 1 credit.

Do SERP features like ads, PAA, or knowledge graph cost extra credits?

No. If they appear in the same successful response, they do not add extra credit cost.

Which engines are supported?

Google, Bing, Brave, and DuckDuckGo are currently supported.

Can I target country/city/language and choose desktop or mobile?

Yes. Use gl (country), location (city/region context), hl (language), and device (desktop/mobile).

Are GPS coordinates supported directly?

Not as a dedicated public request field at this time.

Do top-up credits expire?

No. Top-up credits are one-time credits and do not expire.

Are only successful responses billed?

Yes. Credits are deducted on successful request completion.

What happens when search providers block requests?

OrbitScraper runs retries and provider fallback paths before returning a final failed status.

Do responses come in structured JSON?

Yes. Responses are normalized JSON and designed for direct application use.