# Data API — QuanticData API

> Data API endpoints of the QuanticData API with parameters, request and response examples in cURL, Python, Node.js and PHP. Part of https://quanticdata.io/docs/index.md.

Base URL `https://api.quanticdata.io/v1` · Auth `Authorization: Bearer qd_live_…` · HTML: https://quanticdata.io/docs/ · OpenAPI: https://quanticdata.io/docs/openapi.json · All endpoints: https://quanticdata.io/docs/llms.txt · This file: https://quanticdata.io/docs/data-api.md

_Generated from openapi.json v2026-11-11 on 2026-10-19; prices and limits as of 2026-10-19_

## Scrape

One URL in, Markdown/HTML/text out, with optional structured and AI extraction.

### Scrape one URL

`POST /scraper/extract`

**Price:** `extract` $0.0015 per call + $3/GB, max $0.02 per call · `extract_render` $0.0025 per call + $4/GB, max $0.05 per call · `ai_extract` $0.005 per call, max $1.50 per call. `extract` when the TLS/fetch tier served the page, `extract_render` when the browser did; both carry a perGb meter and a capUsd ceiling (pricing.json → meters). `ai_extract` + LLM tokens × ai_token_markup when ai_prompt/ai_schema is used. The pre-check reserves the worst case (render price unless engine is pinned to tls/fetch without render). _(list of 2026-10-19)_  
**Rate limit:** Per API key, by tier (see Rate limits and tiers).  
**Short alias:** `POST https://api.quanticdata.io/v1/scrape` (same handler, primary host only)  
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/data-api.md)

Fetches one page through the residential pool and returns it as Markdown, HTML or text. Starts on a TLS-fingerprint tier (fast, cheap) and, with `engine: auto`, escalates to a stealth headless browser only when the target blocks; `render: true` (or `engine: render`, `screenshot`, `xhr`, `reveal_hidden`) forces the browser. Binary documents (PDF, DOCX, XLSX, CSV) are converted to text. Optional structured extraction (`extract` CSS schema or a stored `presetId`) and AI extraction (`ai_prompt`/`ai_schema`) run on the same fetch. Pass `html` instead of `url` to convert markup you already have (no fetch, no proxy bandwidth). What it does not do: it does not solve interactive captchas, and `mode: summary` returns no page content (so it cannot be combined with AI extraction). Billed per successful page by the engine that served it, plus a per-GB bandwidth component with a per-call cap; AI extraction adds the `ai_extract` fee plus marked-up LLM tokens. A page flagged as blocked or a target status ≥ 400 is not charged.

#### Request body (required)

`Content-Type: application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | no | http/https URL to scrape. Required unless `html` is given. |
| `html` | string | no | Markup to convert instead of fetching (max 5 MB). |
| `format` | string: `markdown`, `html`, `text`, `raw` | no | `raw` is an alias of `html`. Defaults to markdown (also when AI extraction is requested). Default `"markdown"`. |
| `formats` | array of string: `markdown`, `html`, `text` | no | Extra formats returned together under `payload.formats`. |
| `data_format` | string: `markdown`, `screenshot` | no | Compatibility alias: `markdown` sets format, `screenshot` sets `screenshot: fullPage`. |
| `engine` | string: `auto`, `tls`, `fetch`, `render` | no | `auto` starts on the TLS tier and escalates to the browser on a block; `tls`/`fetch` never escalate; `render` forces the browser. Default `"auto"`. |
| `autoEscalate` | boolean | no | Allow/forbid the auto engine's escalation to the browser (ignored once the plan's render budget is spent). |
| `tlsProfile` | string | no | TLS fingerprint profile for the TLS tier (opaque to the API; see /scraper/unlock for the known names). |
| `render` | boolean | no | Force the stealth headless browser (JS execution). Bills the render rate. Default `false`. |
| `mobile` | boolean | no | Mobile viewport and user agent. Default `false`. |
| `waitMs` | number | no | Extra wait after load before capture, render tier (clamped by the service, max 15000). |
| `waitForSelector` | string | no | Wait until this CSS selector appears (render tier). |
| `scrollToBottom` | boolean | no | Auto-scroll to trigger lazy-loaded content (render tier). Default `false`. |
| `actions` | array of object (PageAction) | no |  |
| `screenshot` | boolean \\| string: `fullPage` | no | `true` = viewport PNG, `fullPage` = whole page; forces render. Returned base64 under `screenshot`. |
| `xhr` | boolean | no | Record the page's XHR/fetch traffic under `xhr` (forces render). Use it to discover which API to target with a `fetchResource` action. |
| `expect` | object | no | Assertion that the page is the real one: `element` (CSS selector, ≤512 chars) and/or `text` (≤512 chars) must be present, otherwise the fetch is treated as blocked and retried. |
| `expect.element` | string | no |  |
| `expect.text` | string | no |  |
| `extract` | object (ExtractSchema) | no | Structured-extraction schema: field name → CSS selector, or an object with `selector`, optional `attr` (attribute to read instead of text) and `all` (true = every match as an array). |
| `presetId` | string | no | Run a stored parser preset instead of an inline `extract` schema; the run is scored per field for self-healing. 404 if the preset is not yours. |
| `contentMode` | string: `smart`, `article`, `full` | no | `smart` = whole page minus nav/footer/cookie chrome; `article` = Readability main article; `full` = entire body. Alias `content_mode`. Default `"smart"`. |
| `content_modes` | array of string: `smart`, `article`, `full` | no | Return several content modes at once under `contents`. Alias `contentModes`. |
| `fullPage` | boolean | no | Legacy: `true` = contentMode full. |
| `mode` | string: `full`, `summary` | no | `summary` drops the content and returns only metadata (title, description, canonical, contentLength, engine, bytes) — the light view for audits over many pages. Default `"full"`. |
| `include_links` | boolean | no | Also return de-duplicated absolute links under `links`. Alias `includeLinks`. Default `false`. |
| `app_state` | boolean \\| string: `auto`, `raw` | no | Mine the page's own hydration state (Next/Nuxt/JSON islands) into `metadata.appState`. `true`/`auto` = pruned to the informative parts; `raw` = full blobs. Alias `appState`. |
| `parser` | object | no | Caller CSS rules: `include` (scope the content), `exclude` (drop site-specific chrome), `keep` (protect sections from smart stripping). Each an array of ≤25 selectors, ≤200 chars each. |
| `parser.include` | array of string | no |  |
| `parser.exclude` | array of string | no |  |
| `parser.keep` | array of string | no |  |
| `reveal_hidden` | boolean | no | Render tier: open `<details>`/accordions and click through tabs, capturing every panel. Alias `revealHidden`. |
| `output` | object | no | Markdown shaping; every key also accepted flat (snake_case) at the top level, flat wins. |
| `output.frontmatter` | boolean | no |  |
| `output.toc` | boolean | no |  |
| `output.linksMode` | string: `inline`, `footnote`, `strip` | no |  |
| `output.maxTokens` | number | no |  |
| `output.imagesMode` | string: `inline`, `alt`, `strip` | no |  |
| `output.query` | string | no | Relevance filter for LLM-oriented output. |
| `output.highlights` | integer | no | Most query-relevant passages to return (requires `query`). |
| `output.summarySections` | boolean | no |  |
| `output.chunk` | object | no |  |
| `frontmatter` | boolean | no |  |
| `links_mode` | string: `inline`, `footnote`, `strip` | no |  |
| `toc` | boolean | no |  |
| `max_tokens` | number | no |  |
| `images_mode` | string: `inline`, `alt`, `strip` | no |  |
| `query` | string | no |  |
| `highlights` | integer | no |  |
| `chunk` | object | no |  |
| `summary_sections` | boolean | no |  |
| `ai_prompt` | string | no | Natural-language instruction: the LLM turns the page into structured JSON under `payload.ai.data`. |
| `ai_schema` | object | no | JSON Schema the AI output must follow (deterministic shape). Either `ai_prompt` or `ai_schema` (or both) enables AI extraction. |
| `headers` | object \\| string | no | Extra headers replayed to the target. Either a JSON object (name → value) or a raw `Header: Value` block, one per line (lines starting with `//` or `#` are ignored). Max 32 headers, names must be RFC 7230 tokens, values ≤ 4096 characters; hop-by-hop and framing headers (host, content-length, transfer-encoding, connection, …) are rejected. |
| `cookies` | object | no | name → value cookies sent to the target. |
| `country` | string | no | Country code or place name: letters, digits, spaces, dots, hyphens, underscores; max 56 characters. `all` means no targeting. |
| `state` | string | no | Country code or place name: letters, digits, spaces, dots, hyphens, underscores; max 56 characters. `all` means no targeting. |
| `city` | string | no | Country code or place name: letters, digits, spaces, dots, hyphens, underscores; max 56 characters. `all` means no targeting. |
| `rotation` | string: `rotating`, `sticky` | no | New exit IP per request, or keep one IP for the session. Any other value is treated as `rotating`. Default `"rotating"`. |
| `sessionId` | string | no | Sticky session id (generated if omitted). |
| `sessionDuration` | number | no | Sticky session lifetime in minutes (clamped by the proxy layer, 3–1440, default 10). |

Example:

```json
{
  "url": "https://example.com/pricing",
  "format": "markdown",
  "country": "us",
  "extract": {
    "title": "h1",
    "price": ".price"
  }
}
```

#### Examples

**curl**

```bash
curl -X POST 'https://api.quanticdata.io/v1/scraper/extract' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/pricing","format":"markdown","country":"us","extract":{"title":"h1","price":".price"}}'
```

**Python (requests)**

```python
import requests

r = requests.post(
    'https://api.quanticdata.io/v1/scraper/extract',
    headers={"Authorization": "Bearer qd_live_YOUR_API_KEY"},
    json={
        "url": "https://example.com/pricing",
        "format": "markdown",
        "country": "us",
        "extract": {
            "title": "h1",
            "price": ".price"
        }
    },
    timeout=120,
)
data = r.json()
if data["type"] != "response":
    raise SystemExit(data["message"])
print(data["payload"])
```

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/scraper/extract", {
  method: "POST",
  headers: {
    Authorization: "Bearer qd_live_YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "url": "https://example.com/pricing",
    "format": "markdown",
    "country": "us",
    "extract": {
      "title": "h1",
      "price": ".price"
    }
  })
});
const data = await res.json();
if (data.type !== "response") throw new Error(data.message);
console.log(data.payload);
```

**PHP (curl)**

```php
<?php
$ch = curl_init('https://api.quanticdata.io/v1/scraper/extract');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode([
    'url' => 'https://example.com/pricing',
    'format' => 'markdown',
    'country' => 'us',
    'extract' => [
      'title' => 'h1',
      'price' => '.price'
    ]
  ]),
]);
$raw = curl_exec($ch);
curl_close($ch);
$data = json_decode($raw, true);
if ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }
print_r($data['payload']);
```

#### Responses

- `200` — Page fetched. `engine` says which tier served it and therefore which price applied.
- `400` — Malformed input. `message` names the parameter and the rule it broke.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `402` — The free tier plus wallet balance cannot cover the worst-case estimate of this call (`INSUFFICIENT_FUNDS`), or the account's monthly spend cap is reached (`BUDGET_REACHED`). Nothing was run or charged. When the missing credit is more than one top-up may add, or on `BUDGET_REACHED`, the envelope also carries `escalation` (`type` `contact`): an agent asks for a higher limit at `contact_api` (`POST /agent/contact`, same API key), a person uses `contact_url`. When card top-ups for agents are enabled on this host, `INSUFFICIENT_FUNDS` answered to an API key also carries `WWW-Authenticate: Payment …` (`method="stripe"`): an agent holding a Stripe Shared Payment Token can repeat the same request with `Authorization: Payment <credential>` and pay a balance top-up by itself, $0.50 to $1,000 of credit per request plus 22% VAT on a numbered invoice; the call then runs from the balance at list price. `BUDGET_REACHED` carries no challenge. Step by step: tag Agents, "How an agent pays a top-up without a human".
- `403` — No proxy pool is available to serve the call (no house plan and no residential/datacenter/IPv6 plan on the account).
- `404` — `presetId` does not resolve to one of your presets.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `500` — Extraction failed on our side or timed out (70 s budget). Never billed.
- `503` — The Data API group is switched off for non-admin keys (early-access kill switch).

Example `200` response:

```json
{
  "type": "response",
  "message": "Extraction successful",
  "payload": {
    "url": "https://example.com/pricing",
    "finalUrl": "https://example.com/pricing",
    "status": 200,
    "contentType": "text/html; charset=utf-8",
    "format": "markdown",
    "title": "Pricing — Example",
    "metadata": {
      "description": "Simple, transparent pricing.",
      "canonical": "https://example.com/pricing",
      "language": "en"
    },
    "content": "# Pricing\n\nStarter — $9/month …",
    "data": {
      "title": "Pricing",
      "price": "$9"
    },
    "engine": "tls",
    "attempts": 1,
    "escalated": false,
    "bytes": 48213,
    "durationMs": 1240,
    "geo": {
      "country": "us",
      "state": null,
      "city": null,
      "rotation": "rotating"
    },
    "usage": {
      "cost_usd": 0.0015,
      "free_usd": 0.0015,
      "paid_usd": 0
    }
  },
  "pagination": {}
}
```

Example `400`:

```json
{
  "type": "error",
  "message": "Invalid format. Must be one of: markdown, html, text (or data_format markdown/screenshot, format raw)"
}
```

Example `401`:

```json
{
  "type": "error",
  "message": "Missing or invalid Authorization header. Use: Authorization: Bearer qd_live_YOUR_API_KEY"
}
```

Example `402`:

```json
{
  "type": "error",
  "message": "Your free tier for this month is used up and your balance can't cover this call (estimated $0.002). Add pay-as-you-go credit or pick a plan — your API key stays the same: https://app.quanticdata.io/plans?utm_source=api&utm_medium=402&utm_campaign=free-tier",
  "payload": {
    "code": "INSUFFICIENT_FUNDS",
    "balance": 0,
    "free_remaining": 0,
    "estimated_cost": 0.002,
    "plans_url": "https://app.quanticdata.io/plans?utm_source=api&utm_medium=402&utm_campaign=free-tier",
    "billing_mode": "free_first"
  }
}
```

Example `403`:

```json
{
  "type": "error",
  "message": "Scraper API is not available: no proxy credentials found. Contact support or purchase a residential, datacenter or IPv6 plan."
}
```

Example `404`:

```json
{
  "type": "error",
  "message": "Preset not found",
  "payload": {
    "url": "https://example.com/"
  }
}
```

Example `429`:

```json
{
  "type": "error",
  "message": "Rate limit exceeded. Resets in 23 minutes.",
  "payload": {
    "rateLimit": 1200,
    "requestCount": 1200,
    "resetAt": "2026-10-07T15:00:00.000Z"
  }
}
```

Example `500`:

```json
{
  "type": "error",
  "message": "Extraction timed out",
  "payload": {
    "url": "https://example.com/"
  }
}
```

Example `503`:

```json
{
  "type": "error",
  "message": "This API is temporarily unavailable while we finalize pricing. Contact support for early access."
}
```

Try it: https://app.quanticdata.io/data-api/playground

### Price a call before sending it

`GET /scraper/cost`

**Price:** No charge.  
**Rate limit:** No rate limit.  
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/data-api.md)

Returns what a scrape, batch, crawl, SERP or map call can cost on this account, from the configured prices alone. Nothing is fetched, nothing is charged and no rate-limit token is taken, so it is safe to call before every job. Use it to size a `max_cost` ceiling: pass the ceiling you have in mind and the answer says whether the call fits under it, whether the browser tier would still be allowed and how many units fit. It does not predict the outcome of a call: the real charge depends on the tier that answers and on the bytes moved, and only a usable result is charged.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `kind` | query | string: `extract`, `batch`, `crawl`, `serp`, `map` | no | The call to price. Default `"extract"`. |
| `proxy_type` | query | string: `residential`, `datacenter`, `mobile` | no | Proxy tier of an `extract`, `batch` or `crawl`. Ignored for `serp` and `map`. Default `"residential"`. |
| `render` | query | string: `true`, `false` | no | `true` prices the call with the browser tier forced. |
| `units` | query | integer | no | URLs of a batch, pages of a crawl, or number of calls. Default `1`. |
| `ai` | query | string: `true`, `false` | no | `true` adds AI extraction to an `extract`. |
| `max_cost` | query | number | no | Optional ceiling in USD. When present the answer carries `under_max_cost`. |

#### Examples

**curl**

```bash
curl -X GET 'https://api.quanticdata.io/v1/scraper/cost' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'
```

**Python (requests)**

```python
import requests

r = requests.get(
    'https://api.quanticdata.io/v1/scraper/cost',
    headers={"Authorization": "Bearer qd_live_YOUR_API_KEY"},
    timeout=120,
)
data = r.json()
if data["type"] != "response":
    raise SystemExit(data["message"])
print(data["payload"])
```

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/scraper/cost", {
  method: "GET",
  headers: {
    Authorization: "Bearer qd_live_YOUR_API_KEY"
  }
});
const data = await res.json();
if (data.type !== "response") throw new Error(data.message);
console.log(data.payload);
```

**PHP (curl)**

```php
<?php
$ch = curl_init('https://api.quanticdata.io/v1/scraper/cost');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],
]);
$raw = curl_exec($ch);
curl_close($ch);
$data = json_decode($raw, true);
if ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }
print_r($data['payload']);
```

#### Responses

- `200` — The estimate. Money fields are USD list prices of this account's plan.
- `400` — Malformed input. `message` names the parameter and the rule it broke.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `500` — Our side: the scraper service is unavailable or the call timed out. Never billed.

Example `200` response:

```json
{
  "type": "response",
  "message": "string",
  "payload": {}
}
```

Example `400`:

```json
{
  "type": "error",
  "message": "Invalid format. Must be one of: markdown, html, text (or data_format markdown/screenshot, format raw)"
}
```

Example `401`:

```json
{
  "type": "error",
  "message": "Missing or invalid Authorization header. Use: Authorization: Bearer qd_live_YOUR_API_KEY"
}
```

Example `500`:

```json
{
  "type": "error",
  "message": "Scraper service unavailable. Please try again later."
}
```

Try it: https://app.quanticdata.io/data-api/playground

## Search

Structured search-engine results (Google, Bing, DuckDuckGo) and async multi-page jobs.

### Structured search results

`POST /scraper/serp`

**Price:** `serp` $0.0009 per call · `serp_render` $0.002 per call. Google (except autocomplete/reviews): `serp` when search_metadata.path is `http`, `serp_render` otherwise; Bing/DuckDuckGo: always `serp`. The pre-check reserves `serp_render` for Google. _(list of 2026-10-19)_  
**Rate limit:** Per API key, by tier (see Rate limits and tiers).  
**Short alias:** `POST https://api.quanticdata.io/v1/serp` (same handler, primary host only)  
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/data-api.md)

One search on Google, Bing or DuckDuckGo through the residential pool, returned as JSON in the common SERP-API shape: organic results, ads, People Also Ask, related searches, knowledge panels, AI Overview and 17 Google verticals (`search_type`). `render: true` asks for the rendered Google page (People Also Ask, related questions, ads), `render: false` pins the cheaper HTTP tier, and without `render` the service picks: the HTTP tier for Google web search, a browser for the verticals that need one. Identical requests are served from a 24h cache for free (`search_metadata.from_cache`). It does not paginate on your behalf: request one `page` at a time and read `pagination.available_pages`/`has_next`, or use `/scraper/serp/bulk`. Billed per successful search by the tier that served it (`search_metadata.path`); blocked searches answer 429 and cost nothing; `autocomplete` and `reviews` always bill the request price. Bing: a page whose results answer another query (a decoy) or Bing's "no results" shell is never returned as a result; the service retries as a different browser identity, then once in a real browser, and if nothing genuine comes back the call ends 429 with `code` `bing-decoy` or `bing-no-results`, `attempts` and `retries` (one entry per attempt: `tier`, `outcome`, `reason`) — retry it or use `engine: "google"`. A Bing Success with `organic: []` always carries `search_metadata.empty_reason`.

#### Request body (required)

`Content-Type: application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | no | Search query. Required except for ID-addressed verticals: `place_details` with `place_id`/`data_id`, `product` with `product_id`, `flights`, `lens`, `trends` (no query = trending searches), `reviews` with `data_id`. |
| `engine` | string: `google`, `bing`, `duckduckgo` | no |  Default `"google"`. |
| `search_type` | string: `search`, `shopping`, `images`, `news`, `places`, `maps`, `videos`, `scholar`, `jobs`, `autocomplete`, `place_details`, `hotels`, `flights`, `events`, `product`, `lens`, `reviews`, `trends` | no | Vertical. Alias `type`; Google aliases `tbm` (shop/isch/nws/lcl/vid) and `udm` (28/2/12/1/7) are mapped too. Default `"search"`. |
| `country` | string | no | Country code or place name: letters, digits, spaces, dots, hyphens, underscores; max 56 characters. `all` means no targeting. |
| `lang` | string | no | UI language, e.g. `en`, `it`. Alias `hl`. |
| `num` | number | no | Results to request (clamped to 1–100 by the service; Google serves ~10 per page and merges pages — see `search_metadata.paging`). |
| `page` | number | no | Result page, 1-based. |
| `start` | number | no | Result offset (alternative to `page`). |
| `device` | string: `desktop`, `mobile`, `ios`, `android` | no | Device to search as. `desktop` (default) gets the computer page; `mobile`, `ios` and `android` get the phone page. Google web, news and videos are fetched as Edge: on an Android phone for every phone value, on Windows or macOS for `desktop`. Every page of one query (`num` above 10, every page of a bulk job) comes from the same device and browser; identities rotate between queries, among current versions and phone models. `search_metadata.served_device` says which page came back (phone or computer layout), `served_platform` and `served_browser` which device and browser fetched it. Desktop and phone results are cached separately. Also accepted as `brd_mobile`: `1` (mobile), `ios` or `android`. Default `"desktop"`. |
| `render` | boolean | no | Forwarded as sent. `true` asks for the rendered Google page (People Also Ask, related questions, ads; billed `serp_render` when a rendered tier answers), `false` pins the cheaper HTTP tier, unset lets the service pick (the HTTP tier for Google web search, a browser for the verticals that need one). DuckDuckGo never renders; Bing renders only as the last attempt after decoys (always billed `serp`). |
| `browser` | string: `chrome`, `firefox`, `safari` | no | Browser to search as: `chrome`, `firefox` or `safari` (Safari is iPhone or macOS, Chrome is Android or desktop, Firefox desktop only). Bing and DuckDuckGo fetch as that browser; Google web, news and videos always fetch as Edge (`search_metadata.served_browser`). Without it the browser rotates between queries. Alias `brd_browser`. |
| `safe` | string: `active`, `off` | no | SafeSearch. |
| `nfpr` | boolean \\| integer: `1` | no | Disable auto-corrected results. |
| `location` | string | no | Human-readable search location ("Milan, Italy"), encoded to uule server-side. For `places`/`maps` it sets the map center: where Google puts that name (a region or a country gives its centre). `gps_coordinates` and `uule` win over it. |
| `uule` | string | no | Encoded uule token OR raw `lat,lon[,radius]`. For `places`/`maps` it sets the map center (coordinates, or the place a `w+` token names) and wins over `location`. |
| `google_params` | object | no | Escape hatch: extra Google URL params (keys ≤40 chars of letters, digits, `.`, `-`, `_`; values strings ≤512 chars or numbers). |
| `jobs` | boolean | no | Jobs box on the main SERP. Alias `ibp: "htl;jobs"`. |
| `place_id` | string | no | `place_details`. |
| `data_id` | string | no | `place_details` / `reviews` (feature id 0x…:0x…). |
| `product_id` | string \\| number | no | `product`: the seller list of one shopping result. |
| `departure_id` | string | no | `flights`: airport/city code. |
| `arrival_id` | string | no |  |
| `outbound_date` | string | no | YYYY-MM-DD. |
| `return_date` | string | no |  |
| `check_in_date` | string | no | `hotels`. |
| `check_out_date` | string | no |  |
| `adults` | number | no | `hotels`, clamped 1–30. |
| `children_ages` | array of number | no |  |
| `free_cancellation` | boolean | no |  |
| `accommodation_type` | string: `hotels`, `vacation_rentals` | no |  |
| `currency` | string | no | `hotels`/`flights` price currency (USD, EUR…). |
| `gps_coordinates` | string | no | `maps`/`places`: map center `lat,lon[,zoom]`. Wins over `uule` and `location`. |
| `image_url` | string | no | `lens`: http(s) URL of the image to search by. |
| `exact_matches` | boolean | no | `lens`. |
| `sort_by` | string: `relevance`, `newest`, `highest_rating`, `lowest_rating` | no | `reviews`. |
| `filter` | string | no | `reviews`: keyword filter. |
| `next_page_token` | string | no | `reviews`: continuation token from `serpapi_pagination`. |
| `wait_for` | string | no | Render tier: CSS selector to wait for before capture. |
| `include_html` | boolean | no | Also return the page HTML under `html` (scripts stripped). |
| `product_ids` | boolean | no | `shopping`: resolve product ids for each result (slower). |

Example:

```json
{
  "query": "best coffee grinder",
  "engine": "google",
  "country": "us",
  "lang": "en",
  "num": 10
}
```

#### Examples

**curl**

```bash
curl -X POST 'https://api.quanticdata.io/v1/scraper/serp' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"query":"best coffee grinder","engine":"google","country":"us","lang":"en","num":10}'
```

**Python (requests)**

```python
import requests

r = requests.post(
    'https://api.quanticdata.io/v1/scraper/serp',
    headers={"Authorization": "Bearer qd_live_YOUR_API_KEY"},
    json={
        "query": "best coffee grinder",
        "engine": "google",
        "country": "us",
        "lang": "en",
        "num": 10
    },
    timeout=120,
)
data = r.json()
if data["type"] != "response":
    raise SystemExit(data["message"])
print(data["payload"])
```

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/scraper/serp", {
  method: "POST",
  headers: {
    Authorization: "Bearer qd_live_YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "query": "best coffee grinder",
    "engine": "google",
    "country": "us",
    "lang": "en",
    "num": 10
  })
});
const data = await res.json();
if (data.type !== "response") throw new Error(data.message);
console.log(data.payload);
```

**PHP (curl)**

```php
<?php
$ch = curl_init('https://api.quanticdata.io/v1/scraper/serp');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode([
    'query' => 'best coffee grinder',
    'engine' => 'google',
    'country' => 'us',
    'lang' => 'en',
    'num' => 10
  ]),
]);
$raw = curl_exec($ch);
curl_close($ch);
$data = json_decode($raw, true);
if ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }
print_r($data['payload']);
```

#### Responses

- `200` — Search succeeded. The envelope's `pagination` mirrors `payload.pagination`.
- `400` — Malformed input. `message` names the parameter and the rule it broke.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `402` — The free tier plus wallet balance cannot cover the worst-case estimate of this call (`INSUFFICIENT_FUNDS`), or the account's monthly spend cap is reached (`BUDGET_REACHED`). Nothing was run or charged. When the missing credit is more than one top-up may add, or on `BUDGET_REACHED`, the envelope also carries `escalation` (`type` `contact`): an agent asks for a higher limit at `contact_api` (`POST /agent/contact`, same API key), a person uses `contact_url`. When card top-ups for agents are enabled on this host, `INSUFFICIENT_FUNDS` answered to an API key also carries `WWW-Authenticate: Payment …` (`method="stripe"`): an agent holding a Stripe Shared Payment Token can repeat the same request with `Authorization: Payment <credential>` and pay a balance top-up by itself, $0.50 to $1,000 of credit per request plus 22% VAT on a numbered invoice; the call then runs from the balance at list price. `BUDGET_REACHED` carries no challenge. Step by step: tag Agents, "How an agent pays a top-up without a human".
- `403` — No proxy pool is available to serve the call (no house plan and no residential/datacenter/IPv6 plan on the account).
- `429` — Key/plan rate limit, or the engine blocked every attempt (retryable, never billed). When the engine blocked every attempt, `payload` also says what was tried: `code` (the block, e.g. `bing-decoy`: Bing answered with results for another query), `attempts`, and `retries`, one entry per attempt with `attempt`, `tier`, `outcome`, `reason`, `error`, `time_taken` and `page` where known. A block met on every tier is not fixed by an immediate retry: retry later, or use another engine.
- `500` — Our side: the scraper service is unavailable or the call timed out. Never billed.
- `503` — The Data API group is switched off for non-admin keys (early-access kill switch).

Example `200` response:

```json
{
  "type": "response",
  "message": "SERP successful",
  "payload": {
    "search_metadata": {
      "status": "Success",
      "engine": "google",
      "search_url": "https://www.google.com/search?q=best+coffee+grinder&gl=us&hl=en",
      "created_at": "2026-10-07T09:12:44.000Z",
      "total_time_taken": 2.8,
      "attempts": 1,
      "bytes": 212544,
      "path": "http"
    },
    "search_parameters": {
      "engine": "google",
      "q": "best coffee grinder",
      "search_type": "search",
      "device": "desktop",
      "country": "us",
      "language": "en",
      "page": 1
    },
    "organic": [
      {
        "rank": 1,
        "title": "The 6 Best Coffee Grinders of 2026",
        "link": "https://example.com/reviews/coffee-grinders",
        "display_link": "example.com › reviews",
        "source": "example.com",
        "description": "We tested 24 burr grinders…",
        "date": "12 Sep 2026"
      }
    ],
    "ads": [],
    "people_also_ask": [
      {
        "question": "Is a burr grinder worth it?"
      }
    ],
    "related_searches": [
      {
        "query": "best coffee grinder under 100"
      }
    ],
    "ai_overview": null,
    "knowledge_graph": null,
    "pagination": {
      "current": 1,
      "next": 2,
      "total_pages": null,
      "other_pages": {
        "2": "https://www.google.com/search?q=best+coffee+grinder&start=10"
      },
      "available_pages": [
        1,
        2,
        3,
        4,
        5
      ],
      "has_next": true
    },
    "usage": {
      "cost_usd": 0.0009,
      "free_usd": 0.0009,
      "paid_usd": 0
    }
  },
  "pagination": {
    "current": 1,
    "next": 2,
    "total_pages": null,
    "available_pages": [
      1,
      2,
      3,
      4,
      5
    ],
    "has_next": true
  }
}
```

Example `400`:

```json
{
  "type": "error",
  "message": "Invalid format. Must be one of: markdown, html, text (or data_format markdown/screenshot, format raw)"
}
```

Example `401`:

```json
{
  "type": "error",
  "message": "Missing or invalid Authorization header. Use: Authorization: Bearer qd_live_YOUR_API_KEY"
}
```

Example `402`:

```json
{
  "type": "error",
  "message": "Your free tier for this month is used up and your balance can't cover this call (estimated $0.002). Add pay-as-you-go credit or pick a plan — your API key stays the same: https://app.quanticdata.io/plans?utm_source=api&utm_medium=402&utm_campaign=free-tier",
  "payload": {
    "code": "INSUFFICIENT_FUNDS",
    "balance": 0,
    "free_remaining": 0,
    "estimated_cost": 0.002,
    "plans_url": "https://app.quanticdata.io/plans?utm_source=api&utm_medium=402&utm_campaign=free-tier",
    "billing_mode": "free_first"
  }
}
```

Example `403`:

```json
{
  "type": "error",
  "message": "Scraper API is not available: no proxy credentials found. Contact support or purchase a residential, datacenter or IPv6 plan."
}
```

Example `500`:

```json
{
  "type": "error",
  "message": "Scraper service unavailable. Please try again later."
}
```

Example `503`:

```json
{
  "type": "error",
  "message": "This API is temporarily unavailable while we finalize pricing. Contact support for early access."
}
```

Try it: https://app.quanticdata.io/data-api/playground

### Start a multi-page search job

`POST /scraper/serp/bulk`

**Price:** `serp_render` $0.002 per call · `serp` $0.0009 per call. Google: `serp_render` × max_pages up front; Bing/DuckDuckGo: `serp` × max_pages. Unfetched pages refunded at settlement. _(list of 2026-10-19)_  
**Rate limit:** Per API key, by tier (see Rate limits and tiers).  
**Short alias:** `POST https://api.quanticdata.io/v1/serp/bulk` (same handler, primary host only)  
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/data-api.md)

Paginates one query across up to 10 result pages asynchronously, riding real pagination on one session. Returns a job id immediately; poll `GET /scraper/serp/bulk/{jobId}` for the merged, de-duplicated organic results as pages land, or pass a `webhook` to receive the finished job. Only web-type verticals (search, news, videos, images, shopping) are supported here. Charged up front for `max_pages`; pages the query does not have are refunded when the job settles.

#### Request body (required)

`Content-Type: application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | yes |  |
| `engine` | string: `google`, `bing`, `duckduckgo` | no |  Default `"google"`. |
| `search_type` | string: `search`, `news`, `videos`, `images`, `shopping` | no | Alias `type`. Default `"search"`. |
| `max_pages` | integer | no |  Default `5`. |
| `country` | string | no | Country code or place name: letters, digits, spaces, dots, hyphens, underscores; max 56 characters. `all` means no targeting. |
| `lang` | string | no | Alias `hl`. |
| `device` | string: `desktop`, `mobile`, `ios`, `android` | no | Device to search as. `desktop` (default) gets the computer page; `mobile`, `ios` and `android` get the phone page. Google web, news and videos are fetched as Edge: on an Android phone for every phone value, on Windows or macOS for `desktop`. Every page of one query (`num` above 10, every page of a bulk job) comes from the same device and browser; identities rotate between queries, among current versions and phone models. `search_metadata.served_device` says which page came back (phone or computer layout), `served_platform` and `served_browser` which device and browser fetched it. Desktop and phone results are cached separately. Also accepted as `brd_mobile`: `1` (mobile), `ios` or `android`. |
| `render` | boolean | no |  |
| `wait_for` | string | no |  |
| `browser` | string: `chrome`, `firefox`, `safari` | no | Browser to search as: `chrome`, `firefox` or `safari` (Safari is iPhone or macOS, Chrome is Android or desktop, Firefox desktop only). Bing and DuckDuckGo fetch as that browser; Google web, news and videos always fetch as Edge (`search_metadata.served_browser`). Without it the browser rotates between queries. Alias `brd_browser`. |
| `safe` | string: `active`, `off` | no |  |
| `nfpr` | boolean \\| integer: `1` | no |  |
| `uule` | string | no |  |
| `location` | string | no |  |
| `google_params` | object | no |  |
| `webhook` | string | no | Public http(s) URL that receives the finished job by POST. |

Example:

```json
{
  "query": "best coffee grinder",
  "engine": "google",
  "country": "us",
  "max_pages": 3
}
```

#### Examples

**curl**

```bash
curl -X POST 'https://api.quanticdata.io/v1/scraper/serp/bulk' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"query":"best coffee grinder","engine":"google","country":"us","max_pages":3}'
```

**Python (requests)**

```python
import requests

r = requests.post(
    'https://api.quanticdata.io/v1/scraper/serp/bulk',
    headers={"Authorization": "Bearer qd_live_YOUR_API_KEY"},
    json={
        "query": "best coffee grinder",
        "engine": "google",
        "country": "us",
        "max_pages": 3
    },
    timeout=120,
)
data = r.json()
if data["type"] != "response":
    raise SystemExit(data["message"])
print(data["payload"])
```

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/scraper/serp/bulk", {
  method: "POST",
  headers: {
    Authorization: "Bearer qd_live_YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "query": "best coffee grinder",
    "engine": "google",
    "country": "us",
    "max_pages": 3
  })
});
const data = await res.json();
if (data.type !== "response") throw new Error(data.message);
console.log(data.payload);
```

**PHP (curl)**

```php
<?php
$ch = curl_init('https://api.quanticdata.io/v1/scraper/serp/bulk');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode([
    'query' => 'best coffee grinder',
    'engine' => 'google',
    'country' => 'us',
    'max_pages' => 3
  ]),
]);
$raw = curl_exec($ch);
curl_close($ch);
$data = json_decode($raw, true);
if ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }
print_r($data['payload']);
```

#### Responses

- `200` — Job accepted.
- `400` — Malformed input. `message` names the parameter and the rule it broke.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `402` — The free tier plus wallet balance cannot cover the worst-case estimate of this call (`INSUFFICIENT_FUNDS`), or the account's monthly spend cap is reached (`BUDGET_REACHED`). Nothing was run or charged. When the missing credit is more than one top-up may add, or on `BUDGET_REACHED`, the envelope also carries `escalation` (`type` `contact`): an agent asks for a higher limit at `contact_api` (`POST /agent/contact`, same API key), a person uses `contact_url`. When card top-ups for agents are enabled on this host, `INSUFFICIENT_FUNDS` answered to an API key also carries `WWW-Authenticate: Payment …` (`method="stripe"`): an agent holding a Stripe Shared Payment Token can repeat the same request with `Authorization: Payment <credential>` and pay a balance top-up by itself, $0.50 to $1,000 of credit per request plus 22% VAT on a numbered invoice; the call then runs from the balance at list price. `BUDGET_REACHED` carries no challenge. Step by step: tag Agents, "How an agent pays a top-up without a human".
- `403` — No proxy pool is available to serve the call (no house plan and no residential/datacenter/IPv6 plan on the account).
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `500` — Our side: the scraper service is unavailable or the call timed out. Never billed.
- `503` — The Data API group is switched off for non-admin keys (early-access kill switch).

Example `200` response:

```json
{
  "type": "response",
  "message": "Bulk SERP started",
  "payload": {
    "id": "sb_4d1e9c",
    "status": "running",
    "query": "best coffee grinder",
    "total": 3,
    "completed": 0,
    "statusUrl": "/api/v1/scraper/serp/bulk/sb_4d1e9c",
    "usage": {
      "cost_usd": 0.006,
      "free_usd": 0.006,
      "paid_usd": 0
    }
  },
  "pagination": {}
}
```

Example `400`:

```json
{
  "type": "error",
  "message": "Invalid format. Must be one of: markdown, html, text (or data_format markdown/screenshot, format raw)"
}
```

Example `401`:

```json
{
  "type": "error",
  "message": "Missing or invalid Authorization header. Use: Authorization: Bearer qd_live_YOUR_API_KEY"
}
```

Example `402`:

```json
{
  "type": "error",
  "message": "Your free tier for this month is used up and your balance can't cover this call (estimated $0.002). Add pay-as-you-go credit or pick a plan — your API key stays the same: https://app.quanticdata.io/plans?utm_source=api&utm_medium=402&utm_campaign=free-tier",
  "payload": {
    "code": "INSUFFICIENT_FUNDS",
    "balance": 0,
    "free_remaining": 0,
    "estimated_cost": 0.002,
    "plans_url": "https://app.quanticdata.io/plans?utm_source=api&utm_medium=402&utm_campaign=free-tier",
    "billing_mode": "free_first"
  }
}
```

Example `403`:

```json
{
  "type": "error",
  "message": "Scraper API is not available: no proxy credentials found. Contact support or purchase a residential, datacenter or IPv6 plan."
}
```

Example `429`:

```json
{
  "type": "error",
  "message": "Rate limit exceeded. Resets in 23 minutes.",
  "payload": {
    "rateLimit": 1200,
    "requestCount": 1200,
    "resetAt": "2026-10-07T15:00:00.000Z"
  }
}
```

Example `500`:

```json
{
  "type": "error",
  "message": "Scraper service unavailable. Please try again later."
}
```

Example `503`:

```json
{
  "type": "error",
  "message": "This API is temporarily unavailable while we finalize pricing. Contact support for early access."
}
```

Try it: https://app.quanticdata.io/data-api/playground

### Poll a multi-page search job

`GET /scraper/serp/bulk/{jobId}`

**Price:** No charge.  
**Rate limit:** Per API key, by tier (see Rate limits and tiers).  
**Short alias:** `GET https://api.quanticdata.io/v1/serp/bulk/{jobId}` (same handler, primary host only)  
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/data-api.md)

Progress and merged organic results of a bulk search job you own. Pass the previous response's `nextCursor` as `since` to receive only new rows. Jobs are kept about an hour after they finish. Free to poll.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `jobId` | path | string | yes | Job id returned by the POST that started it. |
| `since` | query | integer | no | Organic cursor from the previous poll's `nextCursor`. |

#### Examples

**curl**

```bash
curl -X GET 'https://api.quanticdata.io/v1/scraper/serp/bulk/job_8f2c1a' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'
```

**Python (requests)**

```python
import requests

r = requests.get(
    'https://api.quanticdata.io/v1/scraper/serp/bulk/job_8f2c1a',
    headers={"Authorization": "Bearer qd_live_YOUR_API_KEY"},
    timeout=120,
)
data = r.json()
if data["type"] != "response":
    raise SystemExit(data["message"])
print(data["payload"])
```

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/scraper/serp/bulk/job_8f2c1a", {
  method: "GET",
  headers: {
    Authorization: "Bearer qd_live_YOUR_API_KEY"
  }
});
const data = await res.json();
if (data.type !== "response") throw new Error(data.message);
console.log(data.payload);
```

**PHP (curl)**

```php
<?php
$ch = curl_init('https://api.quanticdata.io/v1/scraper/serp/bulk/job_8f2c1a');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],
]);
$raw = curl_exec($ch);
curl_close($ch);
$data = json_decode($raw, true);
if ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }
print_r($data['payload']);
```

#### Responses

- `200` — Job view.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `404` — Unknown id — or an id that belongs to another account (ownership failures answer 404, never 403, so ids cannot be probed).
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `500` — Our side: the scraper service is unavailable or the call timed out. Never billed.
- `503` — The Data API group is switched off for non-admin keys (early-access kill switch).

Example `200` response:

```json
{
  "type": "response",
  "message": "Bulk SERP status",
  "payload": {
    "id": "sb_4d1e9c",
    "status": "completed",
    "query": "best coffee grinder",
    "total": 3,
    "completed": 3,
    "failed": 0,
    "pages": [
      {
        "page": 1,
        "organic_count": 10,
        "bytes": 210331,
        "path": "http"
      },
      {
        "page": 2,
        "organic_count": 10,
        "bytes": 198002,
        "path": "http"
      },
      {
        "page": 3,
        "organic_count": 9,
        "bytes": 190114,
        "path": "http"
      }
    ],
    "organic": [
      {
        "rank": 1,
        "title": "The 6 Best Coffee Grinders of 2026",
        "link": "https://example.com/reviews/coffee-grinders",
        "display_link": "example.com",
        "description": "…"
      }
    ],
    "related_searches": [],
    "ai_overview": null,
    "nextCursor": 29,
    "createdAt": 1759828364000,
    "finishedAt": 1759828391000
  },
  "pagination": {}
}
```

Example `401`:

```json
{
  "type": "error",
  "message": "Missing or invalid Authorization header. Use: Authorization: Bearer qd_live_YOUR_API_KEY"
}
```

Example `404`:

```json
{
  "type": "error",
  "message": "Job not found"
}
```

Example `429`:

```json
{
  "type": "error",
  "message": "Rate limit exceeded. Resets in 23 minutes.",
  "payload": {
    "rateLimit": 1200,
    "requestCount": 1200,
    "resetAt": "2026-10-07T15:00:00.000Z"
  }
}
```

Example `500`:

```json
{
  "type": "error",
  "message": "Scraper service unavailable. Please try again later."
}
```

Example `503`:

```json
{
  "type": "error",
  "message": "This API is temporarily unavailable while we finalize pricing. Contact support for early access."
}
```

Try it: https://app.quanticdata.io/data-api/playground

### Cancel a multi-page search job

`DELETE /scraper/serp/bulk/{jobId}`

**Price:** No charge.  
**Rate limit:** Per API key, by tier (see Rate limits and tiers).  
**Short alias:** `DELETE https://api.quanticdata.io/v1/serp/bulk/{jobId}` (same handler, primary host only)  
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/data-api.md)

Stops a running bulk search job you own. Pages never fetched are refunded at settlement.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `jobId` | path | string | yes | Job id returned by the POST that started it. |

#### Examples

**curl**

```bash
curl -X DELETE 'https://api.quanticdata.io/v1/scraper/serp/bulk/job_8f2c1a' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'
```

**Python (requests)**

```python
import requests

r = requests.delete(
    'https://api.quanticdata.io/v1/scraper/serp/bulk/job_8f2c1a',
    headers={"Authorization": "Bearer qd_live_YOUR_API_KEY"},
    timeout=120,
)
data = r.json()
if data["type"] != "response":
    raise SystemExit(data["message"])
print(data["payload"])
```

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/scraper/serp/bulk/job_8f2c1a", {
  method: "DELETE",
  headers: {
    Authorization: "Bearer qd_live_YOUR_API_KEY"
  }
});
const data = await res.json();
if (data.type !== "response") throw new Error(data.message);
console.log(data.payload);
```

**PHP (curl)**

```php
<?php
$ch = curl_init('https://api.quanticdata.io/v1/scraper/serp/bulk/job_8f2c1a');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'DELETE',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],
]);
$raw = curl_exec($ch);
curl_close($ch);
$data = json_decode($raw, true);
if ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }
print_r($data['payload']);
```

#### Responses

- `200` — Cancelled.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `404` — Unknown id — or an id that belongs to another account (ownership failures answer 404, never 403, so ids cannot be probed).
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `500` — Our side: the scraper service is unavailable or the call timed out. Never billed.
- `503` — The Data API group is switched off for non-admin keys (early-access kill switch).

Example `200` response:

```json
{
  "type": "response",
  "message": "Bulk SERP cancelled",
  "payload": {
    "id": "sb_4d1e9c",
    "status": "cancelled"
  },
  "pagination": {}
}
```

Example `401`:

```json
{
  "type": "error",
  "message": "Missing or invalid Authorization header. Use: Authorization: Bearer qd_live_YOUR_API_KEY"
}
```

Example `404`:

```json
{
  "type": "error",
  "message": "Job not found"
}
```

Example `429`:

```json
{
  "type": "error",
  "message": "Rate limit exceeded. Resets in 23 minutes.",
  "payload": {
    "rateLimit": 1200,
    "requestCount": 1200,
    "resetAt": "2026-10-07T15:00:00.000Z"
  }
}
```

Example `500`:

```json
{
  "type": "error",
  "message": "Scraper service unavailable. Please try again later."
}
```

Example `503`:

```json
{
  "type": "error",
  "message": "This API is temporarily unavailable while we finalize pricing. Contact support for early access."
}
```

Try it: https://app.quanticdata.io/data-api/playground

## Map & Crawl

URL discovery for a whole site and asynchronous site crawls.

### Discover a site's URLs

`POST /scraper/map`

**Price:** `map` $0.003 per call _(list of 2026-10-19)_  
**Rate limit:** Per API key, by tier (see Rate limits and tiers).  
**Short alias:** `POST https://api.quanticdata.io/v1/map` (same handler, primary host only)  
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/data-api.md)

Merges robots.txt sitemaps, /sitemap.xml (nested indexes included) and same-domain homepage links into one de-duplicated list, synchronously. Returns up to `limit` URLs plus the site-wide `total` and a per-section `summary`; `group_by: path` returns the path tree instead of the list. It does not fetch page bodies — pair it with /scraper/batch for that. One flat price per call.

#### Request body (required)

`Content-Type: application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | Seed URL. |
| `limit` | number | no | Max URLs to return (service cap 5000). Default `100`. |
| `search` | string | no | Only return URLs containing this substring. |
| `includeSubdomains` | boolean | no |  Default `false`. |
| `sitemapOnly` | boolean | no | Skip the homepage link scrape. Default `false`. |
| `group_by` | string: `path` | no | Return the path tree with counts instead of the URL list. Alias `groupBy`. |
| `country` | string | no | Country code or place name: letters, digits, spaces, dots, hyphens, underscores; max 56 characters. `all` means no targeting. |

Example:

```json
{
  "url": "https://example.com",
  "limit": 100,
  "search": "blog"
}
```

#### Examples

**curl**

```bash
curl -X POST 'https://api.quanticdata.io/v1/scraper/map' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com","limit":100,"search":"blog"}'
```

**Python (requests)**

```python
import requests

r = requests.post(
    'https://api.quanticdata.io/v1/scraper/map',
    headers={"Authorization": "Bearer qd_live_YOUR_API_KEY"},
    json={
        "url": "https://example.com",
        "limit": 100,
        "search": "blog"
    },
    timeout=120,
)
data = r.json()
if data["type"] != "response":
    raise SystemExit(data["message"])
print(data["payload"])
```

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/scraper/map", {
  method: "POST",
  headers: {
    Authorization: "Bearer qd_live_YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "url": "https://example.com",
    "limit": 100,
    "search": "blog"
  })
});
const data = await res.json();
if (data.type !== "response") throw new Error(data.message);
console.log(data.payload);
```

**PHP (curl)**

```php
<?php
$ch = curl_init('https://api.quanticdata.io/v1/scraper/map');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode([
    'url' => 'https://example.com',
    'limit' => 100,
    'search' => 'blog'
  ]),
]);
$raw = curl_exec($ch);
curl_close($ch);
$data = json_decode($raw, true);
if ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }
print_r($data['payload']);
```

#### Responses

- `200` — URLs discovered.
- `400` — Malformed input. `message` names the parameter and the rule it broke.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `402` — The free tier plus wallet balance cannot cover the worst-case estimate of this call (`INSUFFICIENT_FUNDS`), or the account's monthly spend cap is reached (`BUDGET_REACHED`). Nothing was run or charged. When the missing credit is more than one top-up may add, or on `BUDGET_REACHED`, the envelope also carries `escalation` (`type` `contact`): an agent asks for a higher limit at `contact_api` (`POST /agent/contact`, same API key), a person uses `contact_url`. When card top-ups for agents are enabled on this host, `INSUFFICIENT_FUNDS` answered to an API key also carries `WWW-Authenticate: Payment …` (`method="stripe"`): an agent holding a Stripe Shared Payment Token can repeat the same request with `Authorization: Payment <credential>` and pay a balance top-up by itself, $0.50 to $1,000 of credit per request plus 22% VAT on a numbered invoice; the call then runs from the balance at list price. `BUDGET_REACHED` carries no challenge. Step by step: tag Agents, "How an agent pays a top-up without a human".
- `403` — No proxy pool is available to serve the call (no house plan and no residential/datacenter/IPv6 plan on the account).
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `500` — Our side: the scraper service is unavailable or the call timed out. Never billed.
- `503` — The Data API group is switched off for non-admin keys (early-access kill switch).

Example `200` response:

```json
{
  "type": "response",
  "message": "Map successful",
  "payload": {
    "url": "https://example.com",
    "links": [
      "https://example.com/blog/",
      "https://example.com/blog/how-to-scrape"
    ],
    "count": 100,
    "total": 2417,
    "summary": {
      "/blog": 1988,
      "/docs": 240,
      "/": 1
    },
    "sources": {
      "sitemap": 2410,
      "homepage": 42
    },
    "durationMs": 3120,
    "geo": {
      "country": null
    },
    "usage": {
      "cost_usd": 0.003,
      "free_usd": 0.003,
      "paid_usd": 0
    }
  },
  "pagination": {}
}
```

Example `400`:

```json
{
  "type": "error",
  "message": "Invalid format. Must be one of: markdown, html, text (or data_format markdown/screenshot, format raw)"
}
```

Example `401`:

```json
{
  "type": "error",
  "message": "Missing or invalid Authorization header. Use: Authorization: Bearer qd_live_YOUR_API_KEY"
}
```

Example `402`:

```json
{
  "type": "error",
  "message": "Your free tier for this month is used up and your balance can't cover this call (estimated $0.002). Add pay-as-you-go credit or pick a plan — your API key stays the same: https://app.quanticdata.io/plans?utm_source=api&utm_medium=402&utm_campaign=free-tier",
  "payload": {
    "code": "INSUFFICIENT_FUNDS",
    "balance": 0,
    "free_remaining": 0,
    "estimated_cost": 0.002,
    "plans_url": "https://app.quanticdata.io/plans?utm_source=api&utm_medium=402&utm_campaign=free-tier",
    "billing_mode": "free_first"
  }
}
```

Example `403`:

```json
{
  "type": "error",
  "message": "Scraper API is not available: no proxy credentials found. Contact support or purchase a residential, datacenter or IPv6 plan."
}
```

Example `429`:

```json
{
  "type": "error",
  "message": "Rate limit exceeded. Resets in 23 minutes.",
  "payload": {
    "rateLimit": 1200,
    "requestCount": 1200,
    "resetAt": "2026-10-07T15:00:00.000Z"
  }
}
```

Example `500`:

```json
{
  "type": "error",
  "message": "Scraper service unavailable. Please try again later."
}
```

Example `503`:

```json
{
  "type": "error",
  "message": "This API is temporarily unavailable while we finalize pricing. Contact support for early access."
}
```

Try it: https://app.quanticdata.io/data-api/playground

### Start a site crawl

`POST /scraper/crawl`

**Price:** `crawl_page` $0.0003 per call · `extract_render` $0.0025 per call + $4/GB, max $0.05 per call. `crawl_page` × min(limit, 500) up front, or `extract_render` × pages when render is true. Refund of the unfetched share at settlement. _(list of 2026-10-19)_  
**Rate limit:** Per API key, by tier (see Rate limits and tiers).  
**Short alias:** `POST https://api.quanticdata.io/v1/crawl` (same handler, primary host only)  
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/data-api.md)

Breadth-first crawl from a seed URL through the residential pool, each page converted to the requested format. Returns a job id immediately; poll `GET /scraper/crawl/{jobId}`. Charged up front on `limit` pages (render price per page with `render: true`); unfetched or failed pages are refunded when the job settles. A render crawl takes one browser-render token at submission and its pages then queue on the plan's render concurrency.

#### Request body (required)

`Content-Type: application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | Seed URL. |
| `limit` | number | no | Max pages (cap 500). Billed on this up front. Default `50`. |
| `depth` | number | no | Max link depth from the seed (cap 10). Default `3`. |
| `format` | string: `markdown`, `html`, `text` | no |  Default `"markdown"`. |
| `contentMode` | string: `smart`, `article`, `full` | no | Alias `content_mode`. Default `"smart"`. |
| `render` | boolean | no | Render every page with the stealth browser (slower, rendered rate). Default `false`. |
| `sameDomain` | boolean | no |  Default `true`. |
| `allowSubdomains` | boolean | no |  Default `false`. |
| `include` | array of string | no | URL substrings/globs to include, e.g. ["/guides/*"]. |
| `exclude` | array of string | no |  |
| `country` | string | no | Country code or place name: letters, digits, spaces, dots, hyphens, underscores; max 56 characters. `all` means no targeting. |

Example:

```json
{
  "url": "https://docs.example.com",
  "limit": 50,
  "depth": 3,
  "include": [
    "/guides/*"
  ]
}
```

#### Examples

**curl**

```bash
curl -X POST 'https://api.quanticdata.io/v1/scraper/crawl' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://docs.example.com","limit":50,"depth":3,"include":["/guides/*"]}'
```

**Python (requests)**

```python
import requests

r = requests.post(
    'https://api.quanticdata.io/v1/scraper/crawl',
    headers={"Authorization": "Bearer qd_live_YOUR_API_KEY"},
    json={
        "url": "https://docs.example.com",
        "limit": 50,
        "depth": 3,
        "include": [
            "/guides/*"
        ]
    },
    timeout=120,
)
data = r.json()
if data["type"] != "response":
    raise SystemExit(data["message"])
print(data["payload"])
```

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/scraper/crawl", {
  method: "POST",
  headers: {
    Authorization: "Bearer qd_live_YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "url": "https://docs.example.com",
    "limit": 50,
    "depth": 3,
    "include": [
      "/guides/*"
    ]
  })
});
const data = await res.json();
if (data.type !== "response") throw new Error(data.message);
console.log(data.payload);
```

**PHP (curl)**

```php
<?php
$ch = curl_init('https://api.quanticdata.io/v1/scraper/crawl');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode([
    'url' => 'https://docs.example.com',
    'limit' => 50,
    'depth' => 3,
    'include' => ['/guides/*']
  ]),
]);
$raw = curl_exec($ch);
curl_close($ch);
$data = json_decode($raw, true);
if ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }
print_r($data['payload']);
```

#### Responses

- `200` — Crawl started.
- `400` — Malformed input. `message` names the parameter and the rule it broke.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `402` — The free tier plus wallet balance cannot cover the worst-case estimate of this call (`INSUFFICIENT_FUNDS`), or the account's monthly spend cap is reached (`BUDGET_REACHED`). Nothing was run or charged. When the missing credit is more than one top-up may add, or on `BUDGET_REACHED`, the envelope also carries `escalation` (`type` `contact`): an agent asks for a higher limit at `contact_api` (`POST /agent/contact`, same API key), a person uses `contact_url`. When card top-ups for agents are enabled on this host, `INSUFFICIENT_FUNDS` answered to an API key also carries `WWW-Authenticate: Payment …` (`method="stripe"`): an agent holding a Stripe Shared Payment Token can repeat the same request with `Authorization: Payment <credential>` and pay a balance top-up by itself, $0.50 to $1,000 of credit per request plus 22% VAT on a numbered invoice; the call then runs from the balance at list price. `BUDGET_REACHED` carries no challenge. Step by step: tag Agents, "How an agent pays a top-up without a human".
- `403` — No proxy pool is available to serve the call (no house plan and no residential/datacenter/IPv6 plan on the account).
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `500` — Our side: the scraper service is unavailable or the call timed out. Never billed.
- `503` — The Data API group is switched off for non-admin keys (early-access kill switch).

Example `200` response:

```json
{
  "type": "response",
  "message": "Crawl started",
  "payload": {
    "id": "cr_d5b8a1",
    "status": "running",
    "seed": "https://docs.example.com/",
    "limit": 50,
    "depth": 3,
    "format": "markdown",
    "pagesCrawled": 0,
    "pagesQueued": 1,
    "statusUrl": "/api/v1/scraper/crawl/cr_d5b8a1",
    "usage": {
      "cost_usd": 0.015,
      "free_usd": 0.015,
      "paid_usd": 0
    }
  },
  "pagination": {}
}
```

Example `400`:

```json
{
  "type": "error",
  "message": "Invalid format. Must be one of: markdown, html, text (or data_format markdown/screenshot, format raw)"
}
```

Example `401`:

```json
{
  "type": "error",
  "message": "Missing or invalid Authorization header. Use: Authorization: Bearer qd_live_YOUR_API_KEY"
}
```

Example `402`:

```json
{
  "type": "error",
  "message": "Your free tier for this month is used up and your balance can't cover this call (estimated $0.002). Add pay-as-you-go credit or pick a plan — your API key stays the same: https://app.quanticdata.io/plans?utm_source=api&utm_medium=402&utm_campaign=free-tier",
  "payload": {
    "code": "INSUFFICIENT_FUNDS",
    "balance": 0,
    "free_remaining": 0,
    "estimated_cost": 0.002,
    "plans_url": "https://app.quanticdata.io/plans?utm_source=api&utm_medium=402&utm_campaign=free-tier",
    "billing_mode": "free_first"
  }
}
```

Example `403`:

```json
{
  "type": "error",
  "message": "Scraper API is not available: no proxy credentials found. Contact support or purchase a residential, datacenter or IPv6 plan."
}
```

Example `429`:

```json
{
  "type": "error",
  "message": "Rate limit exceeded. Resets in 23 minutes.",
  "payload": {
    "rateLimit": 1200,
    "requestCount": 1200,
    "resetAt": "2026-10-07T15:00:00.000Z"
  }
}
```

Example `500`:

```json
{
  "type": "error",
  "message": "Scraper service unavailable. Please try again later."
}
```

Example `503`:

```json
{
  "type": "error",
  "message": "This API is temporarily unavailable while we finalize pricing. Contact support for early access."
}
```

Try it: https://app.quanticdata.io/data-api/playground

### Poll a crawl job

`GET /scraper/crawl/{jobId}`

**Price:** No charge.  
**Rate limit:** Per API key, by tier (see Rate limits and tiers).  
**Short alias:** `GET https://api.quanticdata.io/v1/crawl/{jobId}` (same handler, primary host only)  
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/data-api.md)

Progress and crawled pages of a job you own. Use `since` (the previous `nextCursor`) to page a large crawl and `include_content=false` for cheap status checks. Jobs are kept about an hour after they finish. Free to poll.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `jobId` | path | string | yes | Job id returned by the POST that started it. |
| `since` | query | integer | no | Page cursor from the previous poll's `nextCursor`. |
| `include_content` | query | string: `true`, `false` | no | Omit to get the full job; `false` strips page content. |

#### Examples

**curl**

```bash
curl -X GET 'https://api.quanticdata.io/v1/scraper/crawl/job_8f2c1a' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'
```

**Python (requests)**

```python
import requests

r = requests.get(
    'https://api.quanticdata.io/v1/scraper/crawl/job_8f2c1a',
    headers={"Authorization": "Bearer qd_live_YOUR_API_KEY"},
    timeout=120,
)
data = r.json()
if data["type"] != "response":
    raise SystemExit(data["message"])
print(data["payload"])
```

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/scraper/crawl/job_8f2c1a", {
  method: "GET",
  headers: {
    Authorization: "Bearer qd_live_YOUR_API_KEY"
  }
});
const data = await res.json();
if (data.type !== "response") throw new Error(data.message);
console.log(data.payload);
```

**PHP (curl)**

```php
<?php
$ch = curl_init('https://api.quanticdata.io/v1/scraper/crawl/job_8f2c1a');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],
]);
$raw = curl_exec($ch);
curl_close($ch);
$data = json_decode($raw, true);
if ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }
print_r($data['payload']);
```

#### Responses

- `200` — Job view.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `404` — Unknown id — or an id that belongs to another account (ownership failures answer 404, never 403, so ids cannot be probed).
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `500` — Our side: the scraper service is unavailable or the call timed out. Never billed.
- `503` — The Data API group is switched off for non-admin keys (early-access kill switch).

Example `200` response:

```json
{
  "type": "response",
  "message": "Crawl status",
  "payload": {
    "id": "cr_d5b8a1",
    "status": "completed",
    "seed": "https://docs.example.com/",
    "limit": 50,
    "depth": 3,
    "format": "markdown",
    "pagesCrawled": 37,
    "pagesQueued": 0,
    "pages": [
      {
        "url": "https://docs.example.com/guides/getting-started",
        "status": 200,
        "title": "Getting started",
        "depth": 1,
        "content": "# Getting started\n…"
      }
    ],
    "nextCursor": 37,
    "hasMore": false,
    "createdAt": 1759828364000,
    "finishedAt": 1759828512000
  },
  "pagination": {}
}
```

Example `401`:

```json
{
  "type": "error",
  "message": "Missing or invalid Authorization header. Use: Authorization: Bearer qd_live_YOUR_API_KEY"
}
```

Example `404`:

```json
{
  "type": "error",
  "message": "Job not found"
}
```

Example `429`:

```json
{
  "type": "error",
  "message": "Rate limit exceeded. Resets in 23 minutes.",
  "payload": {
    "rateLimit": 1200,
    "requestCount": 1200,
    "resetAt": "2026-10-07T15:00:00.000Z"
  }
}
```

Example `500`:

```json
{
  "type": "error",
  "message": "Scraper service unavailable. Please try again later."
}
```

Example `503`:

```json
{
  "type": "error",
  "message": "This API is temporarily unavailable while we finalize pricing. Contact support for early access."
}
```

Try it: https://app.quanticdata.io/data-api/playground

### Cancel a crawl job

`DELETE /scraper/crawl/{jobId}`

**Price:** No charge.  
**Rate limit:** Per API key, by tier (see Rate limits and tiers).  
**Short alias:** `DELETE https://api.quanticdata.io/v1/crawl/{jobId}` (same handler, primary host only)  
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/data-api.md)

Stops a running crawl you own; pages never fetched are refunded at settlement.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `jobId` | path | string | yes | Job id returned by the POST that started it. |

#### Examples

**curl**

```bash
curl -X DELETE 'https://api.quanticdata.io/v1/scraper/crawl/job_8f2c1a' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'
```

**Python (requests)**

```python
import requests

r = requests.delete(
    'https://api.quanticdata.io/v1/scraper/crawl/job_8f2c1a',
    headers={"Authorization": "Bearer qd_live_YOUR_API_KEY"},
    timeout=120,
)
data = r.json()
if data["type"] != "response":
    raise SystemExit(data["message"])
print(data["payload"])
```

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/scraper/crawl/job_8f2c1a", {
  method: "DELETE",
  headers: {
    Authorization: "Bearer qd_live_YOUR_API_KEY"
  }
});
const data = await res.json();
if (data.type !== "response") throw new Error(data.message);
console.log(data.payload);
```

**PHP (curl)**

```php
<?php
$ch = curl_init('https://api.quanticdata.io/v1/scraper/crawl/job_8f2c1a');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'DELETE',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],
]);
$raw = curl_exec($ch);
curl_close($ch);
$data = json_decode($raw, true);
if ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }
print_r($data['payload']);
```

#### Responses

- `200` — Cancelled.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `404` — Unknown id — or an id that belongs to another account (ownership failures answer 404, never 403, so ids cannot be probed).
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `500` — Our side: the scraper service is unavailable or the call timed out. Never billed.
- `503` — The Data API group is switched off for non-admin keys (early-access kill switch).

Example `200` response:

```json
{
  "type": "response",
  "message": "Crawl cancelled",
  "payload": {
    "id": "cr_d5b8a1",
    "status": "cancelled"
  },
  "pagination": {}
}
```

Example `401`:

```json
{
  "type": "error",
  "message": "Missing or invalid Authorization header. Use: Authorization: Bearer qd_live_YOUR_API_KEY"
}
```

Example `404`:

```json
{
  "type": "error",
  "message": "Job not found"
}
```

Example `429`:

```json
{
  "type": "error",
  "message": "Rate limit exceeded. Resets in 23 minutes.",
  "payload": {
    "rateLimit": 1200,
    "requestCount": 1200,
    "resetAt": "2026-10-07T15:00:00.000Z"
  }
}
```

Example `500`:

```json
{
  "type": "error",
  "message": "Scraper service unavailable. Please try again later."
}
```

Example `503`:

```json
{
  "type": "error",
  "message": "This API is temporarily unavailable while we finalize pricing. Contact support for early access."
}
```

Try it: https://app.quanticdata.io/data-api/playground

## Batch

Many known URLs scraped asynchronously.

### Scrape many URLs asynchronously

`POST /scraper/batch`

**Price:** `batch_url` $0.0004 per call · `extract_render` $0.0025 per call + $4/GB, max $0.05 per call. `batch_url` × urls up front (or `extract_render` × urls when rendering). Failed URLs refunded at settlement. _(list of 2026-10-19)_  
**Rate limit:** Per API key, by tier (see Rate limits and tiers).  
**Short alias:** `POST https://api.quanticdata.io/v1/batch` (same handler, primary host only)  
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/data-api.md)

Up to 5,000 URLs you already know, with shared options, run concurrently through the residential pool. Returns a job id immediately; poll `GET /scraper/batch/{jobId}` or pass a `webhook` to receive the finished job by POST. Charged up front per URL (render price with `render: true` or `engine: render`); the failed/blocked share is refunded when the job settles. A render batch takes one browser-render token at submission.

#### Request body (required)

`Content-Type: application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `urls` | array of string | yes |  |
| `format` | string: `markdown`, `html`, `text` | no |  Default `"markdown"`. |
| `engine` | string: `auto`, `tls`, `fetch`, `render` | no |  Default `"auto"`. |
| `render` | boolean | no | Force the headless browser for every URL. Default `false`. |
| `extract` | object (ExtractSchema) | no | Structured-extraction schema: field name → CSS selector, or an object with `selector`, optional `attr` (attribute to read instead of text) and `all` (true = every match as an array). |
| `contentMode` | string: `smart`, `article`, `full` | no | Alias `content_mode`. Default `"smart"`. |
| `fullPage` | boolean | no | Legacy: contentMode full. |
| `mode` | string: `full`, `summary` | no | `summary` stores per-URL metadata only (title, description, canonical, contentLength). Default `"full"`. |
| `concurrency` | number | no | Simultaneous fetches (clamped 1–20; your tier's batch concurrency also applies). Default `5`. |
| `webhook` | string | no | Public http(s) URL that receives the finished job by POST. |
| `country` | string | no | Country code or place name: letters, digits, spaces, dots, hyphens, underscores; max 56 characters. `all` means no targeting. |

Example:

```json
{
  "urls": [
    "https://example.com/a",
    "https://example.com/b"
  ],
  "format": "markdown",
  "mode": "summary"
}
```

#### Examples

**curl**

```bash
curl -X POST 'https://api.quanticdata.io/v1/scraper/batch' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"urls":["https://example.com/a","https://example.com/b"],"format":"markdown","mode":"summary"}'
```

**Python (requests)**

```python
import requests

r = requests.post(
    'https://api.quanticdata.io/v1/scraper/batch',
    headers={"Authorization": "Bearer qd_live_YOUR_API_KEY"},
    json={
        "urls": [
            "https://example.com/a",
            "https://example.com/b"
        ],
        "format": "markdown",
        "mode": "summary"
    },
    timeout=120,
)
data = r.json()
if data["type"] != "response":
    raise SystemExit(data["message"])
print(data["payload"])
```

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/scraper/batch", {
  method: "POST",
  headers: {
    Authorization: "Bearer qd_live_YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "urls": [
      "https://example.com/a",
      "https://example.com/b"
    ],
    "format": "markdown",
    "mode": "summary"
  })
});
const data = await res.json();
if (data.type !== "response") throw new Error(data.message);
console.log(data.payload);
```

**PHP (curl)**

```php
<?php
$ch = curl_init('https://api.quanticdata.io/v1/scraper/batch');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode([
    'urls' => ['https://example.com/a', 'https://example.com/b'],
    'format' => 'markdown',
    'mode' => 'summary'
  ]),
]);
$raw = curl_exec($ch);
curl_close($ch);
$data = json_decode($raw, true);
if ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }
print_r($data['payload']);
```

#### Responses

- `200` — Batch started.
- `400` — Malformed input. `message` names the parameter and the rule it broke.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `402` — The free tier plus wallet balance cannot cover the worst-case estimate of this call (`INSUFFICIENT_FUNDS`), or the account's monthly spend cap is reached (`BUDGET_REACHED`). Nothing was run or charged. When the missing credit is more than one top-up may add, or on `BUDGET_REACHED`, the envelope also carries `escalation` (`type` `contact`): an agent asks for a higher limit at `contact_api` (`POST /agent/contact`, same API key), a person uses `contact_url`. When card top-ups for agents are enabled on this host, `INSUFFICIENT_FUNDS` answered to an API key also carries `WWW-Authenticate: Payment …` (`method="stripe"`): an agent holding a Stripe Shared Payment Token can repeat the same request with `Authorization: Payment <credential>` and pay a balance top-up by itself, $0.50 to $1,000 of credit per request plus 22% VAT on a numbered invoice; the call then runs from the balance at list price. `BUDGET_REACHED` carries no challenge. Step by step: tag Agents, "How an agent pays a top-up without a human".
- `403` — No proxy pool is available to serve the call (no house plan and no residential/datacenter/IPv6 plan on the account).
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `500` — Our side: the scraper service is unavailable or the call timed out. Never billed.
- `503` — The Data API group is switched off for non-admin keys (early-access kill switch).

Example `200` response:

```json
{
  "type": "response",
  "message": "Batch started",
  "payload": {
    "id": "bt_91ac07",
    "status": "running",
    "total": 2,
    "completed": 0,
    "failed": 0,
    "statusUrl": "/api/v1/scraper/batch/bt_91ac07",
    "usage": {
      "cost_usd": 0.0004,
      "free_usd": 0.0004,
      "paid_usd": 0
    }
  },
  "pagination": {}
}
```

Example `400`:

```json
{
  "type": "error",
  "message": "Invalid format. Must be one of: markdown, html, text (or data_format markdown/screenshot, format raw)"
}
```

Example `401`:

```json
{
  "type": "error",
  "message": "Missing or invalid Authorization header. Use: Authorization: Bearer qd_live_YOUR_API_KEY"
}
```

Example `402`:

```json
{
  "type": "error",
  "message": "Your free tier for this month is used up and your balance can't cover this call (estimated $0.002). Add pay-as-you-go credit or pick a plan — your API key stays the same: https://app.quanticdata.io/plans?utm_source=api&utm_medium=402&utm_campaign=free-tier",
  "payload": {
    "code": "INSUFFICIENT_FUNDS",
    "balance": 0,
    "free_remaining": 0,
    "estimated_cost": 0.002,
    "plans_url": "https://app.quanticdata.io/plans?utm_source=api&utm_medium=402&utm_campaign=free-tier",
    "billing_mode": "free_first"
  }
}
```

Example `403`:

```json
{
  "type": "error",
  "message": "Scraper API is not available: no proxy credentials found. Contact support or purchase a residential, datacenter or IPv6 plan."
}
```

Example `429`:

```json
{
  "type": "error",
  "message": "Rate limit exceeded. Resets in 23 minutes.",
  "payload": {
    "rateLimit": 1200,
    "requestCount": 1200,
    "resetAt": "2026-10-07T15:00:00.000Z"
  }
}
```

Example `500`:

```json
{
  "type": "error",
  "message": "Scraper service unavailable. Please try again later."
}
```

Example `503`:

```json
{
  "type": "error",
  "message": "This API is temporarily unavailable while we finalize pricing. Contact support for early access."
}
```

Try it: https://app.quanticdata.io/data-api/playground

### Poll a batch job

`GET /scraper/batch/{jobId}`

**Price:** No charge.  
**Rate limit:** Per API key, by tier (see Rate limits and tiers).  
**Short alias:** `GET https://api.quanticdata.io/v1/batch/{jobId}` (same handler, primary host only)  
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/data-api.md)

Progress and per-URL results of a job you own. Polls return metadata only unless `include_content=true`; pass the previous `nextCursor` as `since` to receive only newer items. Jobs are kept about an hour after they finish. Free to poll.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `jobId` | path | string | yes | Job id returned by the POST that started it. |
| `since` | query | integer | no | Item cursor from the previous poll's `nextCursor`. |
| `include_content` | query | string: `true`, `false` | no | `true` includes each item's page content. |

#### Examples

**curl**

```bash
curl -X GET 'https://api.quanticdata.io/v1/scraper/batch/job_8f2c1a' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'
```

**Python (requests)**

```python
import requests

r = requests.get(
    'https://api.quanticdata.io/v1/scraper/batch/job_8f2c1a',
    headers={"Authorization": "Bearer qd_live_YOUR_API_KEY"},
    timeout=120,
)
data = r.json()
if data["type"] != "response":
    raise SystemExit(data["message"])
print(data["payload"])
```

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/scraper/batch/job_8f2c1a", {
  method: "GET",
  headers: {
    Authorization: "Bearer qd_live_YOUR_API_KEY"
  }
});
const data = await res.json();
if (data.type !== "response") throw new Error(data.message);
console.log(data.payload);
```

**PHP (curl)**

```php
<?php
$ch = curl_init('https://api.quanticdata.io/v1/scraper/batch/job_8f2c1a');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],
]);
$raw = curl_exec($ch);
curl_close($ch);
$data = json_decode($raw, true);
if ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }
print_r($data['payload']);
```

#### Responses

- `200` — Job view.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `404` — Unknown id — or an id that belongs to another account (ownership failures answer 404, never 403, so ids cannot be probed).
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `500` — Our side: the scraper service is unavailable or the call timed out. Never billed.
- `503` — The Data API group is switched off for non-admin keys (early-access kill switch).

Example `200` response:

```json
{
  "type": "response",
  "message": "Batch status",
  "payload": {
    "id": "bt_91ac07",
    "status": "completed",
    "total": 2,
    "completed": 2,
    "failed": 0,
    "contentTruncated": false,
    "items": [
      {
        "url": "https://example.com/a",
        "status": 200,
        "title": "Page A",
        "description": "…",
        "canonical": "https://example.com/a",
        "contentLength": 5120,
        "engine": "tls",
        "bytes": 31870
      },
      {
        "url": "https://example.com/b",
        "status": 200,
        "title": "Page B",
        "description": null,
        "canonical": null,
        "contentLength": 2210,
        "engine": "tls",
        "bytes": 12003
      }
    ],
    "nextCursor": 2,
    "hasMore": false,
    "createdAt": 1759828364000,
    "finishedAt": 1759828370000
  },
  "pagination": {}
}
```

Example `401`:

```json
{
  "type": "error",
  "message": "Missing or invalid Authorization header. Use: Authorization: Bearer qd_live_YOUR_API_KEY"
}
```

Example `404`:

```json
{
  "type": "error",
  "message": "Job not found"
}
```

Example `429`:

```json
{
  "type": "error",
  "message": "Rate limit exceeded. Resets in 23 minutes.",
  "payload": {
    "rateLimit": 1200,
    "requestCount": 1200,
    "resetAt": "2026-10-07T15:00:00.000Z"
  }
}
```

Example `500`:

```json
{
  "type": "error",
  "message": "Scraper service unavailable. Please try again later."
}
```

Example `503`:

```json
{
  "type": "error",
  "message": "This API is temporarily unavailable while we finalize pricing. Contact support for early access."
}
```

Try it: https://app.quanticdata.io/data-api/playground

### Cancel a batch job

`DELETE /scraper/batch/{jobId}`

**Price:** No charge.  
**Rate limit:** Per API key, by tier (see Rate limits and tiers).  
**Short alias:** `DELETE https://api.quanticdata.io/v1/batch/{jobId}` (same handler, primary host only)  
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/data-api.md)

Stops a running batch you own; URLs never fetched are refunded at settlement.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `jobId` | path | string | yes | Job id returned by the POST that started it. |

#### Examples

**curl**

```bash
curl -X DELETE 'https://api.quanticdata.io/v1/scraper/batch/job_8f2c1a' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'
```

**Python (requests)**

```python
import requests

r = requests.delete(
    'https://api.quanticdata.io/v1/scraper/batch/job_8f2c1a',
    headers={"Authorization": "Bearer qd_live_YOUR_API_KEY"},
    timeout=120,
)
data = r.json()
if data["type"] != "response":
    raise SystemExit(data["message"])
print(data["payload"])
```

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/scraper/batch/job_8f2c1a", {
  method: "DELETE",
  headers: {
    Authorization: "Bearer qd_live_YOUR_API_KEY"
  }
});
const data = await res.json();
if (data.type !== "response") throw new Error(data.message);
console.log(data.payload);
```

**PHP (curl)**

```php
<?php
$ch = curl_init('https://api.quanticdata.io/v1/scraper/batch/job_8f2c1a');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'DELETE',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],
]);
$raw = curl_exec($ch);
curl_close($ch);
$data = json_decode($raw, true);
if ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }
print_r($data['payload']);
```

#### Responses

- `200` — Cancelled.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `404` — Unknown id — or an id that belongs to another account (ownership failures answer 404, never 403, so ids cannot be probed).
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `500` — Our side: the scraper service is unavailable or the call timed out. Never billed.
- `503` — The Data API group is switched off for non-admin keys (early-access kill switch).

Example `200` response:

```json
{
  "type": "response",
  "message": "Batch cancelled",
  "payload": {
    "id": "bt_91ac07",
    "status": "cancelled"
  },
  "pagination": {}
}
```

Example `401`:

```json
{
  "type": "error",
  "message": "Missing or invalid Authorization header. Use: Authorization: Bearer qd_live_YOUR_API_KEY"
}
```

Example `404`:

```json
{
  "type": "error",
  "message": "Job not found"
}
```

Example `429`:

```json
{
  "type": "error",
  "message": "Rate limit exceeded. Resets in 23 minutes.",
  "payload": {
    "rateLimit": 1200,
    "requestCount": 1200,
    "resetAt": "2026-10-07T15:00:00.000Z"
  }
}
```

Example `500`:

```json
{
  "type": "error",
  "message": "Scraper service unavailable. Please try again later."
}
```

Example `503`:

```json
{
  "type": "error",
  "message": "This API is temporarily unavailable while we finalize pricing. Contact support for early access."
}
```

Try it: https://app.quanticdata.io/data-api/playground

## Video

A YouTube video as text and pictures for a model: the transcript in the spoken language with timestamps, the author's chapters and small storyboard frames placed at the moments that matter, in one timeline.

### Read a YouTube video for a model

`POST /scraper/video`

**Price:** `video` $0.02 per call. `video` per successful read, whatever the length; a window (`start`/`end`) or a transcript-only read (`max_frames: 0`) costs the same. _(list of 2026-10-19)_  
**Rate limit:** Per API key, by tier (see Rate limits and tiers).  
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/data-api.md)

One YouTube URL in; out come the metadata, the transcript in the language that is spoken with `[m:ss]` timestamps (never a translated track: a translation adds the translator's errors on top of the captioner's, and the reading model translates better from the original), the chapters the author wrote, and small storyboard frames picked where the words point at the screen ("as you can see", "come vedete"), where a price is said, at each chapter start and every so often in between, so no stretch goes unseen. `content` interleaves all of it in one Markdown timeline the model reads in order; the frames are base64 JPEGs you attach to the prompt next to their `[frame N]` marker. No model runs on our side. Use `start`/`end` to read a part of a long video and `max_tokens` to bound the text; `max_frames: 0` returns the transcript alone. Reads that the platform refuses from a datacenter address are retried through a residential exit automatically. Pay per success: a video that cannot be read (removed, private, sign-in gated, live not started) answers a stable `payload.code` and is never billed. The MCP server exposes the same call as the `read_video` tool.

#### Request body (required)

`Content-Type: application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | YouTube URL: watch, youtu.be, shorts, embed or live. |
| `languages` | array of string | no | Caption languages to prefer, e.g. `["en"]`. Leave it out to get the language spoken in the video (recommended: more accurate than a translated track). |
| `max_frames` | integer | no | Frames to include; 0 = transcript only. Default `12`. |
| `frames` | boolean | no | false = the frame list without image data (positions, reasons and quotes only). Default `true`. |
| `start` | number \\| string | no | Read from this point: seconds or `m:ss` / `h:mm:ss`. |
| `end` | number \\| string | no | Read up to this point: seconds or `m:ss` / `h:mm:ss`, after `start`. |
| `max_tokens` | integer | no | Budget for `content` (estimator chars/4). When the text is trimmed, `tokens.truncated` is true and a note says so: pass `start`/`end` to read the rest. |
| `segments` | boolean | no | true = also return the raw timed cues under `transcript.segments`. Default `false`. |

Example:

```json
{
  "url": "https://www.youtube.com/watch?v=aircAruvnKk",
  "max_frames": 6,
  "max_tokens": 4000
}
```

#### Examples

**curl**

```bash
curl -X POST 'https://api.quanticdata.io/v1/scraper/video' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://www.youtube.com/watch?v=aircAruvnKk","max_frames":6,"max_tokens":4000}'
```

**Python (requests)**

```python
import requests

r = requests.post(
    'https://api.quanticdata.io/v1/scraper/video',
    headers={"Authorization": "Bearer qd_live_YOUR_API_KEY"},
    json={
        "url": "https://www.youtube.com/watch?v=aircAruvnKk",
        "max_frames": 6,
        "max_tokens": 4000
    },
    timeout=120,
)
data = r.json()
if data["type"] != "response":
    raise SystemExit(data["message"])
print(data["payload"])
```

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/scraper/video", {
  method: "POST",
  headers: {
    Authorization: "Bearer qd_live_YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "url": "https://www.youtube.com/watch?v=aircAruvnKk",
    "max_frames": 6,
    "max_tokens": 4000
  })
});
const data = await res.json();
if (data.type !== "response") throw new Error(data.message);
console.log(data.payload);
```

**PHP (curl)**

```php
<?php
$ch = curl_init('https://api.quanticdata.io/v1/scraper/video');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode([
    'url' => 'https://www.youtube.com/watch?v=aircAruvnKk',
    'max_frames' => 6,
    'max_tokens' => 4000
  ]),
]);
$raw = curl_exec($ch);
curl_close($ch);
$data = json_decode($raw, true);
if ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }
print_r($data['payload']);
```

#### Responses

- `200` — The video, read.
- `400` — Malformed input. `message` names the parameter and the rule it broke.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `402` — The free tier plus wallet balance cannot cover the worst-case estimate of this call (`INSUFFICIENT_FUNDS`), or the account's monthly spend cap is reached (`BUDGET_REACHED`). Nothing was run or charged. When the missing credit is more than one top-up may add, or on `BUDGET_REACHED`, the envelope also carries `escalation` (`type` `contact`): an agent asks for a higher limit at `contact_api` (`POST /agent/contact`, same API key), a person uses `contact_url`. When card top-ups for agents are enabled on this host, `INSUFFICIENT_FUNDS` answered to an API key also carries `WWW-Authenticate: Payment …` (`method="stripe"`): an agent holding a Stripe Shared Payment Token can repeat the same request with `Authorization: Payment <credential>` and pay a balance top-up by itself, $0.50 to $1,000 of credit per request plus 22% VAT on a numbered invoice; the call then runs from the balance at list price. `BUDGET_REACHED` carries no challenge. Step by step: tag Agents, "How an agent pays a top-up without a human".
- `403` — The video needs a signed-in viewer (age or membership gated) and cannot be read. Not billed.
- `404` — The video was removed, is private, or the id is wrong. Not billed.
- `422` — Not readable in this version: a live stream that has not started (`video_live_offline`) or a platform other than YouTube (`video_platform_unsupported`). Not billed.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `502` — The video platform did not answer in a readable way, on the direct attempt and through a residential exit (`video_platform_error`, `video_captions_error`, `video_bad_payload`, `video_unplayable`). Try again in a minute. Not billed.
- `503` — The Video API is switched off for this key (`PRODUCT_DISABLED`), or the Data API group is switched off for non-admin keys.
- `504` — The read timed out. Pass `start`/`end` to read a shorter window. Not billed.

Example `200` response:

```json
{
  "type": "response",
  "message": "Video read successful",
  "payload": {
    "video": {
      "platform": "youtube",
      "id": "aircAruvnKk",
      "url": "https://www.youtube.com/watch?v=aircAruvnKk",
      "title": "But what is a neural network? | Deep learning chapter 1",
      "channel": "3Blue1Brown",
      "channel_id": "UCYO_jab_esuFRV4b17AJtAw",
      "duration_seconds": 1120,
      "view_count": 24894419,
      "keywords": [
        "neural network",
        "deep learning"
      ],
      "is_live": false,
      "thumbnail": "https://i.ytimg.com/vi/aircAruvnKk/hqdefault.jpg"
    },
    "transcript": {
      "source": "captions",
      "language": "en",
      "available": [
        {
          "code": "en",
          "kind": "manual"
        },
        {
          "code": "it",
          "kind": "manual"
        }
      ]
    },
    "chapters": [
      {
        "start": 0,
        "title": "Introduction example"
      },
      {
        "start": 67,
        "title": "Series preview"
      },
      {
        "start": 162,
        "title": "What are neurons?"
      }
    ],
    "frames": [
      {
        "n": 1,
        "t": 130,
        "at": "2:10",
        "reason": "cue",
        "quote": "and in recent years there's been sort of a boom in research towards these variants",
        "width": 160,
        "height": 90,
        "mime": "image/jpeg",
        "data": "/9j/4AAQSkZJRgABAQAAAQABAAD…"
      },
      {
        "n": 2,
        "t": 165,
        "at": "2:45",
        "reason": "chapter",
        "quote": "What are neurons?",
        "width": 160,
        "height": 90,
        "mime": "image/jpeg",
        "data": "/9j/4AAQSkZJRgABAQAAAQABAAD…"
      }
    ],
    "frame_size": {
      "width": 160,
      "height": 90,
      "interval": 10
    },
    "format": "markdown",
    "content": "# But what is a neural network? | Deep learning chapter 1\nChannel: 3Blue1Brown · Duration: 18:40 · Views: 24894419\nURL: https://www.youtube.com/watch?v=aircAruvnKk\nTranscript: en (captions), original language, timestamps [m:ss]\nFrames: 6 storyboard frames of 160×90 px, marked [frame N · m:ss · why]; low resolution — scenes and objects are visible, small text is not\n\n## Description\nWhat are the neurons, why are there layers, and what is the math underlying it?\n…\n\n## Timeline\n## [0:00] Introduction example\n\n[0:04] This is a 3. It's sloppily written and rendered at an extremely low resolution of 28x28 pixels, but your brain has no trouble recognizing it as a 3. …\n[frame 1 · 2:10 · the speaker points at the screen]\n[2:12] but in these two introductory videos you and I are just going to look at the simplest plain vanilla form …\n\n## [2:42] What are neurons?\n\n[frame 2 · 2:45 · chapter start]\n[2:42] So let's start by looking at an example of a neuron …",
    "tokens": {
      "estimated": 3996,
      "full": 5780,
      "truncated": true,
      "estimator": "chars/4 heuristic"
    },
    "notes": [
      "content trimmed to max_tokens: pass start/end to read the rest of the video"
    ],
    "meta": {
      "bytes": 502969,
      "via_proxy": false
    }
  },
  "pagination": {}
}
```

Example `400`:

```json
{
  "type": "error",
  "message": "Invalid format. Must be one of: markdown, html, text (or data_format markdown/screenshot, format raw)"
}
```

Example `401`:

```json
{
  "type": "error",
  "message": "Missing or invalid Authorization header. Use: Authorization: Bearer qd_live_YOUR_API_KEY"
}
```

Example `402`:

```json
{
  "type": "error",
  "message": "Your free tier for this month is used up and your balance can't cover this call (estimated $0.002). Add pay-as-you-go credit or pick a plan — your API key stays the same: https://app.quanticdata.io/plans?utm_source=api&utm_medium=402&utm_campaign=free-tier",
  "payload": {
    "code": "INSUFFICIENT_FUNDS",
    "balance": 0,
    "free_remaining": 0,
    "estimated_cost": 0.002,
    "plans_url": "https://app.quanticdata.io/plans?utm_source=api&utm_medium=402&utm_campaign=free-tier",
    "billing_mode": "free_first"
  }
}
```

Example `403`:

```json
{
  "type": "error",
  "message": "This video needs a signed-in viewer (age or membership gated) and cannot be read.",
  "payload": {
    "url": "https://www.youtube.com/watch?v=xxxxxxxxxxx",
    "code": "video_login_required"
  }
}
```

Example `404`:

```json
{
  "type": "error",
  "message": "Video not found: it was removed, is private, or the id is wrong.",
  "payload": {
    "url": "https://www.youtube.com/watch?v=xxxxxxxxxxx",
    "code": "video_unavailable"
  }
}
```

Example `422`:

```json
{
  "type": "error",
  "message": "This live stream has not started yet.",
  "payload": {
    "url": "https://www.youtube.com/watch?v=xxxxxxxxxxx",
    "code": "video_live_offline"
  }
}
```

Example `429`:

```json
{
  "type": "error",
  "message": "Rate limit exceeded. Resets in 23 minutes.",
  "payload": {
    "rateLimit": 1200,
    "requestCount": 1200,
    "resetAt": "2026-10-07T15:00:00.000Z"
  }
}
```

Example `502`:

```json
{
  "type": "error",
  "message": "The video platform did not answer. Try again in a minute.",
  "payload": {
    "url": "https://www.youtube.com/watch?v=aircAruvnKk",
    "code": "video_platform_error"
  }
}
```

Example `503`:

```json
{
  "type": "error",
  "message": "The Video API is not open yet. Ask support for early access, or read videos with the read_video tool of the MCP server.",
  "payload": {
    "code": "PRODUCT_DISABLED"
  }
}
```

Example `504`:

```json
{
  "type": "error",
  "message": "Video read timed out. Pass start/end to read a shorter window.",
  "payload": {
    "url": "https://www.youtube.com/watch?v=aircAruvnKk",
    "code": null
  }
}
```

Try it: https://app.quanticdata.io/data-api/playground

## Web Unlocker

Replay any HTTP request through a residential or mobile exit under a real browser fingerprint, with retries on fresh exits, a headless browser for JavaScript challenges and one error catalogue; prepaid per GB.

One engine, three entry points. All three spend the same prepaid Web Unlocker GB, one balance per tier (`premium` = residential exits, `mobile` = mobile exits), bought on the Web Unlocker tab of the [plans page](https://app.quanticdata.io/plans?network=UNLOCK) and paid from the wallet balance, separate from the Data API free credit. Same targeting, same diagnostics, same errors.

### Which endpoint

| Entry point | Use it when | Endpoint |
|---|---|---|
| **REST API** | You can change your code: one JSON call in, one JSON answer out, no certificate to install. | `POST https://app.quanticdata.io/api/v1/scraper/unlock` (the same call on the API host: `https://api.quanticdata.io/v1/scraper/unlock`) |
| **Proxy (CONNECT)** | You already have a scraper that speaks proxy: point it at the host and port with your unlocker user and password, and install the CA once. | `http://unlock.quanticdata.io:9000` |
| **Direct mode** | Proxy without a certificate: send the request to `http://unlock/` through the proxy and name the target in the `x-qp-url` header. | `http://unlock.quanticdata.io:9000`, then `http://unlock/` |

The REST call is `POST /scraper/unlock` below. The CA of the proxy is `GET /scraper/unlock/ca` (`https://app.quanticdata.io/api/v1/scraper/unlock/ca`). The [Web Unlocker page](https://app.quanticdata.io/unlock) of the dashboard shows the same three snippets filled with your own key, proxy user and password.

Many URLs at once go through the batch endpoints (see Batch). The price per GB of each tier, the pack sizes and the options that are switched on are published by `GET /public/unlock/offer` once the offer is public (`available: true`); `GET /public/unlock/status` publishes the latest canary run. Neither needs a key.

## Download a client

Two single-file clients cover the REST call and the batch endpoints. They have no dependency: download the file, put it next to your code and import it.

| Language | File | Needs |
|---|---|---|
| Node.js | [unlocker.mjs](https://quanticdata.io/docs/clients/unlocker.mjs) | Node 18 or later |
| Python | [unlocker.py](https://quanticdata.io/docs/clients/unlocker.py) | Python 3.9 or later |

**Node.js**

```javascript
import { Unlocker } from "./unlocker.mjs";

const client = new Unlocker({ apiKey: "qd_live_YOUR_API_KEY", retries: 2 });
const page = await client.unlock("https://example.com/", { country: "us", format: "markdown" });
console.log(page.status, page.tier_served, page.cost.bytes);
console.log(page.body.slice(0, 500));
```

**Python**

```python
from unlocker import Unlocker

client = Unlocker(api_key="qd_live_YOUR_API_KEY", retries=2)
page = client.unlock("https://example.com/", country="us", format="markdown")
print(page["status"], page["tier_served"], page["cost"]["bytes"])
print(page["body"][:500])
```

Both clients have `unlock(url, options)`, `batch(requests, options)`, `batchStatus(id)` and `batchCancel(id)` (also `batch_status` and `batch_cancel` in Python). Options are the REST fields in snake_case, `actions` and `cache_ttl` included. An error answer raises `UnlockerError` with `code`, `retryable`, `billed`, `hint`, `status` and `request_id`. `retries` (0 to 2, default 0) repeats a call whose error is retryable, after the `Retry-After` pause.

## Forward proxy

| | |
|---|---|
| Host | `unlock.quanticdata.io` |
| Port | `9000` (HTTP proxy) |
| Authentication | `Proxy-Authorization: Basic` with a **proxy user**: username `unlock-<12 hex>`, 32-character password. Your API key is not accepted by the proxy. |
| Targets | `http://` and `https://` URLs. HTTP/1.1 inside a CONNECT tunnel. |
| Limits | Request body up to 8 MB. Text responses up to 5 MB, binary up to 25 MB, or less with `x-qp-max-bytes`. At most 8 redirects are followed. One call, attempts and browser render included, fits in `x-qp-timeout` (default 60 s). |

### Proxy users

Create, rotate and delete proxy users on the [Web Unlocker page](https://app.quanticdata.io/unlock) of the dashboard, up to 20 per account; a proxy user can be created once the tier has GB. The password is shown when the user is created or rotated. The proxy caches a successful login for 60 seconds, so a rotated or deleted password can keep working for up to a minute. The same page builds ready-made proxy strings with the targeting below.

### Proxy (CONNECT)

The normal proxy setting of any HTTP client. The proxy re-issues your request itself, so it terminates TLS with its own certificate: download the CA once (`GET /scraper/unlock/ca`, saved as `unlocker-ca.pem` below) and trust it for the target host, or turn verification off (`curl -k`, `verify=False`).

**curl**

```bash
# once: curl -o unlocker-ca.pem https://app.quanticdata.io/api/v1/scraper/unlock/ca
curl --proxy http://unlock.quanticdata.io:9000 \
  --proxy-user "USER:PASS" \
  --cacert unlocker-ca.pem \
  https://example.com/
```

**Python (requests)**

```python
import requests

# once: download https://app.quanticdata.io/api/v1/scraper/unlock/ca as unlocker-ca.pem
proxy = "http://USER:PASS@unlock.quanticdata.io:9000"
r = requests.get(
    "https://example.com/",
    proxies={"http": proxy, "https": proxy},
    verify="unlocker-ca.pem",
    timeout=130,
)
print(r.status_code, r.headers.get("x-qp-unlocker-blocked", "ok"), r.headers.get("x-qp-unlocker-attempts"))
print(r.text[:500])
```

**Node (undici)**

```javascript
import { fetch, ProxyAgent } from "undici";
import { readFileSync } from "node:fs";

// once: download https://app.quanticdata.io/api/v1/scraper/unlock/ca as unlocker-ca.pem
const dispatcher = new ProxyAgent({
  uri: "http://unlock.quanticdata.io:9000",
  token: "Basic " + Buffer.from("USER:PASS").toString("base64"),
  requestTls: { ca: readFileSync("unlocker-ca.pem") },
});
const res = await fetch("https://example.com/", { dispatcher });
console.log(res.status, res.headers.get("x-qp-unlocker-blocked") ?? "ok", res.headers.get("x-qp-unlocker-attempts"));
console.log((await res.text()).slice(0, 500));
```

**PHP (curl)**

```php
<?php
// once: download https://app.quanticdata.io/api/v1/scraper/unlock/ca as unlocker-ca.pem
$ch = curl_init("https://example.com/");
curl_setopt_array($ch, [
  CURLOPT_PROXY => "http://unlock.quanticdata.io:9000",
  CURLOPT_PROXYUSERPWD => "USER:PASS",
  CURLOPT_CAINFO => "unlocker-ca.pem",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 130,
]);
$html = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), "\n", substr($html, 0, 500);
```

**Go**

```go
package main

import (
	"crypto/tls"
	"crypto/x509"
	"fmt"
	"io"
	"net/http"
	"net/url"
	"os"
)

func main() {
	// once: download https://app.quanticdata.io/api/v1/scraper/unlock/ca as unlocker-ca.pem
	ca, _ := os.ReadFile("unlocker-ca.pem")
	pool := x509.NewCertPool()
	pool.AppendCertsFromPEM(ca)
	proxy, _ := url.Parse("http://USER:PASS@unlock.quanticdata.io:9000")
	client := &http.Client{Transport: &http.Transport{Proxy: http.ProxyURL(proxy), TLSClientConfig: &tls.Config{RootCAs: pool}}}
	res, err := client.Get("https://example.com/")
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode, res.Header.Get("x-qp-unlocker-blocked"), res.Header.Get("x-qp-unlocker-attempts"), len(body))
}
```

### Direct mode

Nothing to install: address the proxy itself with plain HTTP at `http://unlock/` and put the target in `x-qp-url`. The proxy makes the TLS connection to the site. The method and body of your call are forwarded; `x-qp-method` overrides the method.

**curl**

```bash
curl --proxy http://unlock.quanticdata.io:9000 \
  --proxy-user "USER:PASS" \
  -H "x-qp-url: https://example.com/" \
  http://unlock/
```

**Python (requests)**

```python
import requests

proxy = "http://USER:PASS@unlock.quanticdata.io:9000"
r = requests.get(
    "http://unlock/",
    proxies={"http": proxy},
    headers={"x-qp-url": "https://example.com/"},
    timeout=130,
)
print(r.status_code, r.headers.get("x-qp-unlocker-blocked", "ok"), r.headers.get("x-qp-unlocker-attempts"))
print(r.text[:500])
```

**Node (undici)**

```javascript
import { fetch, ProxyAgent } from "undici";

const dispatcher = new ProxyAgent({
  uri: "http://unlock.quanticdata.io:9000",
  token: "Basic " + Buffer.from("USER:PASS").toString("base64"),
});
const res = await fetch("http://unlock/", { dispatcher, headers: { "x-qp-url": "https://example.com/" } });
console.log(res.status, res.headers.get("x-qp-unlocker-blocked") ?? "ok", res.headers.get("x-qp-unlocker-attempts"));
console.log((await res.text()).slice(0, 500));
```

**PHP (curl)**

```php
<?php
$ch = curl_init("http://unlock/");
curl_setopt_array($ch, [
  CURLOPT_PROXY => "http://unlock.quanticdata.io:9000",
  CURLOPT_PROXYUSERPWD => "USER:PASS",
  CURLOPT_HTTPHEADER => ["x-qp-url: https://example.com/"],
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 130,
]);
$html = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), "\n", substr($html, 0, 500);
```

**Go**

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"net/url"
)

func main() {
	proxy, _ := url.Parse("http://USER:PASS@unlock.quanticdata.io:9000")
	client := &http.Client{Transport: &http.Transport{Proxy: http.ProxyURL(proxy)}}
	req, _ := http.NewRequest("GET", "http://unlock/", nil)
	req.Header.Set("x-qp-url", "https://example.com/")
	res, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode, res.Header.Get("x-qp-unlocker-blocked"), res.Header.Get("x-qp-unlocker-attempts"), len(body))
}
```

A plain `http://` target works through the proxy as well, as an absolute-URI request (`GET http://example.com/ HTTP/1.1`), the way any client sends an `http://` URL through a proxy; no certificate involved.

### Targeting in the username

Append options to the proxy user, each as `-name-value`: `unlock-xxxxxxxxxxxx-country-us-session-abc123-ttl-30`. Unknown options are ignored.

| Option | Values | Effect |
|---|---|---|
| `country-xx` | 2-letter country code | Exit country. Without it, in order: the site's own country from its ccTLD (`.de`, `.fr`), then the country of your account, then US. |
| `state-<slug>`, `city-<slug>` | letters, digits, `_` (up to 32) | Exit region and city, e.g. `-state-new_york-city-new_york`. |
| `session-<id>` (or `sid-<id>`) | letters and digits (up to 32) | Keeps the same exit IP across requests and connections. |
| `ttl-<minutes>` | 3 to 1440 | How long that session's exit is kept; only together with `session`. |
| `profile-<name>` | `chrome` (default), `firefox`, `safari`, `safari_ios`, `edge`, `brave`, `mobile` | Browser fingerprint. Other values fall back to the default. |
| `mobile` | — | Mobile browser fingerprint on the same exits. It does not switch to the mobile network. |
| `tier-<name>` | `premium` (default), `mobile` | Product: exit network and GB balance the request is billed on. |
| `policy-<name>` | `browser` (default), `passthrough` | `passthrough` sends your own identity headers instead of the fingerprint's. |

### Control headers

Optional request headers, read by the proxy and removed before the request reaches the site (any other header, including other `x-qp-*` names, is forwarded). They work on every way of sending a request, inside a CONNECT tunnel too, and mirror the fields of the REST call. True values: `1`, `true`, `yes`, `on`; false: `0`, `false`, `no`, `off`, `none` or empty. An invalid value is ignored and reported in `x-qp-warning`. The header names used by other unlocker services for the same options are accepted as aliases, so existing code keeps working: they are listed under Coming from another unlocker.

| Header | Values | Effect |
|---|---|---|
| `x-qp-url` | absolute `http(s)` URL | Target in direct mode; wins over the request line. |
| `x-qp-method` | HTTP verb | Method sent to the site. |
| `x-qp-mode` | `auto` (default), `tls`, `browser` | Same as `mode` of the REST call: `auto` climbs from the TLS tier to the browser when blocked, `tls` never opens the browser, `browser` renders straight away. |
| `x-qp-max-bytes` | integer, at least 1024 | Same as `max_bytes`: cap on the bytes this call may move; over it the answer is 403 `max_bytes_exceeded`. |
| `x-qp-fail-on-block` | true/false | Same as `fail_on_block`: a refusal the site sent under its own status (403, 429, 503) answers 424 `target_blocked` instead of being relayed; a block page served as 2xx/3xx is 424 anyway (see Blocked pages). |
| `x-qp-timeout` | milliseconds, 1000 to 120000 | Same as `timeout_ms`: total budget of the call (default 60000), attempts and browser render included. |
| `x-qp-cache-ttl` | seconds, 0 to 86400 | Same as `cache_ttl`: an identical GET is answered from a stored copy younger than this (see Cache). 0 or absent: no cache. |
| `x-qp-country` (or `x-qp-geo`) | 2-letter code | Exit country for this request. |
| `x-qp-session` (or `x-qp-session-id`) | letters and digits (up to 32) | Exit session for this request. |
| `x-qp-rotation` | `sticky`, `rotating` | Session behaviour. |
| `x-qp-profile` (or `x-qp-tls-profile`) | profile name | Browser fingerprint. |
| `x-qp-keep-headers` | true/false | Send your own identity headers verbatim. |
| `x-qp-render` | `html` or true, `png`, false | `html`/true is `x-qp-mode: browser`; `png` returns a screenshot (GET/HEAD); false is `x-qp-mode: tls`. |
| `x-qp-auto-render` (or `x-qp-escalate`) | true/false | Deprecated, use `x-qp-mode`: false is `tls`, true is `auto`. |
| `x-qp-success-status` | comma-separated codes, 100 to 599 | Origin statuses relayed as success, never retried. |
| `x-qp-wait-for` (or `x-qp-wait-for-selector`) | CSS selector (up to 256) | Browser waits for this element before capturing. |
| `x-qp-wait-ms` (or `x-qp-wait`) | 0 to 15000 | Extra settle time in the browser. |
| `x-qp-return-cookies` | true | Return the site's cookie jar in `x-qp-cookies`. |

### Response headers

The site's status, headers and body are relayed (the body decompressed, `Set-Cookie` lines from every redirect kept), plus the same diagnostics the REST payload carries:

| Header | Meaning |
|---|---|
| `x-qp-request-id` | Id of this exchange (`request_id` of the REST payload), to quote to support. |
| `x-qp-latency-ms` | Milliseconds from your request to the answer (`latency_ms`). |
| `x-qp-tier-served` | `tls` or `browser`: the tier that produced the answer (`tier_served`). |
| `x-qp-cost-bytes`, `x-qp-cost-usd` | Bytes moved for this call and what they cost at your tier's price per GB (`cost.bytes`, `cost.usd`). |
| `x-qp-attempt-log` | `attempt_log` as URL-encoded JSON: one entry per attempt with tier, profile, exit country, outcome, ms and bytes. |
| `x-qp-cache`, `x-qp-cached-at` | `hit`, `miss` or `off` (`cache` of the REST payload) and, on a hit, when the copy was stored (`cached_at`). |
| `x-qp-unlocker-attempts` | Attempts across every tier. |
| `x-qp-unlocker-profile` | Fingerprint that served the response. |
| `x-qp-session` | Exit session used. |
| `x-qp-country` | Exit country used. |
| `x-qp-final-url` | URL after redirects. |
| `x-qp-unlocker-rendered`, `x-qp-unlocker-escalated` | `1` when the headless browser served it, or was reached by escalation. |
| `x-qp-clearance` | `hit`, `miss`, `minted`, `stale` or `off`. |
| `x-qp-unlocker-blocked` | Block reason, when every attempt came back blocked (the status depends on how the site served the block, see Blocked pages). |
| `x-qp-block-class` | `js_challenge`, `captcha`, `access_denied`, `rate_limited`, `fingerprint`, `geo`, `timeout` or `unknown`. |
| `x-qp-vendor` | Anti-bot system, when recognised. |
| `x-qp-hint` | Suggestion when blocked, e.g. try the `mobile` tier. |
| `x-qp-origin-status` | The status the site really sent, when the proxy answered 424 `target_blocked` instead: a block page served as 2xx/3xx, or a refusal turned into 424 by `x-qp-fail-on-block`. |
| `x-qp-cookies` | URL-encoded JSON cookie jar, with `x-qp-return-cookies`. |
| `x-qp-ratelimit-limit`, `x-qp-ratelimit-remaining` | Requests per minute and what is left. |
| `x-qp-warning` | A control header or option that was ignored, and why. |

### Modes, retries and sessions

In `auto` mode (the default) a GET, HEAD or OPTIONS is retried up to three times on a new exit with a different fingerprint, then escalated to a headless browser that can start in parallel when the first attempts come back blocked; `tier_served` (or `x-qp-tier-served`) says which tier produced the answer. `tls` never opens the browser and returns the block page as-is; `browser` renders straight away. Everything fits in the call's total budget (`timeout_ms` / `x-qp-timeout`, default 60 s): a budget that runs out is a 504 `timeout`. Any other method gets exactly one attempt and no browser fallback: a response means the site saw the request, and replaying a POST could submit it twice. With a `session` in the username the exit cannot change, so there is one normal attempt; the browser fallback still runs.

### Browser actions

`actions` (REST call only) is an ordered list of up to 20 interactions the browser runs before the page is captured: click an element or a text, type into a field, scroll, wait. Actions force the browser tier, so they work on GET and HEAD only, and `mode: "tls"` together with `actions` is a 400 `bad_request`. The shapes are listed in the request body of `POST /scraper/unlock`. An action that cannot run ends the call with 422 `action_failed`, and the message names it: `Action 2 failed ({"waitForSelector":".results"}): nothing on the page matched it within 15000 ms`. An action marked `optional: true` is skipped instead, and the call goes on.

### Cache

`cache_ttl` (REST) or `x-qp-cache-ttl` (proxy) is a number of seconds from 0 to 86400; 0, the default, is off. A GET that the site answered 2xx and that was not blocked is kept for your account for that long. A later call with the same URL, mode, format, country, tier, render kind and actions is answered from the copy. That answer says `cache: "hit"` and `cached_at` (`x-qp-cache` and `x-qp-cached-at` on the proxy), with `attempts: 0` and one `attempt_log` entry of tier `cache`; `tier_served` is the tier that produced the stored page. A hit moves no bytes and costs nothing: `cost` is `{"bytes": 0, "usd": 0, "billed": false}`. The cache is best effort: a copy can be dropped before its time, and a page over 5 MB is not kept.

### Billing and limits

The price per GB of each tier is on the [plans page](https://app.quanticdata.io/plans?network=UNLOCK) of the dashboard and, when the offer is published, in `GET /public/unlock/offer`. Every byte the exit network carries for your request is debited from the tier's prepaid GB: retries, blocked pages, failed attempts and the browser's page load included (request bodies and response bodies; headers are not counted). 1 GB = 10^9 bytes. 429 answers and requests refused before they ran are not billed, and a cache hit moves no bytes. When `pay_per_success` of `GET /public/unlock/offer` is true, a blocked page or a failed call debits nothing on the REST call and in a batch; the forward proxy is metered on every byte either way. `max_bytes` / `x-qp-max-bytes` caps what one call may move. The balance is checked when the proxy logs you in, so a session can run for up to a minute past the end of the GB. Requests per minute and concurrent requests follow the account's Data API tier (see Rate limits and tiers).

## Batch

Up to 100 URLs in one asynchronous job. `POST /scraper/unlock/batch` takes the list and answers 202 with a `batch_id` at once. `GET /scraper/unlock/batch/{batch_id}` returns the progress and one result per item. `DELETE /scraper/unlock/batch/{batch_id}` cancels the items that have not started. Each item is a REST call: any field of `POST /scraper/unlock` can be set per item, or once for all of them in `defaults`. `concurrency` (1 to 5, default 3) is how many items run at the same time. With `webhook_url` the finished batch is also sent to your server in one POST. Results are kept for one hour after the batch ends.

Billing: a batch spends the same prepaid GB, and every item is metered like a single call. The tier needs usable GB when the batch starts, otherwise the answer is 402 `no_credit`.

## Errors

One catalogue for the REST call and the proxy. A REST error is the usual envelope, `{"type":"error","message":"…","payload":{…}}`, where `payload` carries `code`, `retryable`, `billed`, `hint` and `doc_url` (this section) plus the details named below; the code is repeated in the `x-qp-unlocker` header and retryable answers carry `Retry-After` with a suggested pause. The proxy answers the same status and JSON body with the same headers; a CONNECT that is refused gets no body, only the status line plus `X-Qp-Unlocker` (code) and, for 402, `X-Qp-Unlocker-Message` (curl prints "Received HTTP code 402 from proxy after CONNECT").

### Unlock errors

| Code | HTTP | Retryable | Billed | When | What to do |
|---|---|---|---|---|---|
| `bad_request` | 400 | no | no | A parameter is invalid; `message` names it and the rule it broke. | Fix the parameter named in the message and send the request again. |
| `unauthorized` | 401 | no | no | API key missing, wrong or disabled. On the proxy: 407 with `Proxy-Authenticate: Basic`, only for a missing or wrong proxy user. | Use the API key from the dashboard (REST) or the unlocker proxy user and password (proxy). |
| `no_credit` | 402 | no | no | The tier has no usable GB: never bought, used up or expired. `payload.reason` says which; `payload.buy_url` is the page to buy GB. | Buy GB from the dashboard, then retry with the same key or proxy user. |
| `target_forbidden` | 403 | no | no | Private, reserved or internal address. | The unlocker only fetches public hosts. |
| `target_denied` | 403 | no | no | A destination the unlocker does not serve (banking, payments, login providers, crypto sites). | Pick another target; this one is on the deny list. |
| `no_exit_pool` | 403 | no | no | The account has no exit pool for the tier (e.g. `mobile` without a mobile sub-user); `payload.tier` names it. On the proxy the same answer is 503 (see Proxy-only answers). | Buy GB on that tier so its pool is set up, or use `tier: "premium"`; retry once the pool exists. |
| `max_bytes_exceeded` | 403 | no | yes | The bytes moved went over `max_bytes`; `payload.usage` and `payload.cost` say how many. | Raise `max_bytes`, or leave it out to accept the full page. |
| `action_failed` | 422 | no | no | REST call with `actions`: the page loaded but one of the actions could not run, for example its selector matched nothing in time. `message` names the action by its position and shape and says why. | Check the selector or the text of that action, or mark it `optional` if the page may not have it. |
| `target_blocked` | 424 | yes | yes | The target refused every attempt and you asked `fail_on_block` (REST) or `x-qp-fail-on-block` (proxy), or, on the proxy, the site served its block page under a 2xx/3xx status; `payload` carries `status`, `blockReason`, `blockClass`, `vendor`, `attempts`, `attempt_log`, `usage` and `cost`. | Retry with `mode: "browser"`, another country, or a sticky session; drop `fail_on_block` to receive the blocked page as a 200. |
| `rate_limited` | 429 | yes | no | Requests per minute or concurrent requests of the account's tier. | Wait for `Retry-After` seconds, lower your concurrency, or move to a plan with a higher limit. |
| `render_failed` | 503 | yes | no | The browser could not load the page. | Retry; if it keeps failing use `mode: "tls"` or a longer `timeout_ms`. |
| `upstream_failed` | 503 | yes | no | The exit or the target could not be reached. | Retry: the next attempt runs on a fresh exit. |
| `service_unavailable` | 503 | yes | no | The engine or the API is not answering (on the proxy: 503, never 407). | Retry in a few seconds. |
| `timeout` | 504 | yes | no | `timeout_ms` ran out before a response. | Raise `timeout_ms` (up to 120000) or use `mode: "tls"` for a faster first answer. |
| `internal_error` | 500 | yes | no | An error on our side. | Retry; if it persists contact support with the `request_id`. |

### Proxy-only answers

Answers only the forward proxy gives (the REST call has no equivalent), same JSON body and `x-qp-unlocker` header as the catalogue:

| Code | HTTP | Retryable | Billed | When |
|---|---|---|---|---|
| `proxy_auth_required` | 407 | no | no | No `Proxy-Authorization` header. Comes with `Proxy-Authenticate: Basic realm="Web Unlocker"`. |
| `proxy_auth_invalid` | 407 | no | no | Wrong proxy user or password. |
| `not_a_proxy_request` | 400 | no | no | A request that is neither proxy-shaped (CONNECT, or an absolute URI) nor direct mode (`x-qp-url`). |
| `body_too_large` | 413 | no | no | Request body over 8 MB. |
| `too_many_connections` | 429 | yes | no | More concurrent connections than the account's tier allows; `Retry-After` says when to retry. |
| `sensitive_rate_limited` | 429 | yes | no | Non-GET requests to login-like paths over the limit; `Retry-After`. |
| `auth_rate_limited` | 429 | yes | no | More than 30 failed logins per minute from one IP; `Retry-After`. |
| `no_exit_pool` | 503 | no, until a pool exists | no | The account has no exit pool for the tier (e.g. `tier-mobile` without a mobile sub-user). The REST call answers 403 `no_exit_pool` for the same situation. |

### Blocked pages

On the REST call a page that is still blocked after every attempt is not an error unless you ask for one: the answer is 200 with `blocked: true`, `blockClass`, `vendor` and `hint`, and the block page is in `body` for inspection; `fail_on_block: true` turns it into 424 `target_blocked`. On the proxy the answer depends on how the site served the block. A block page the site served under a 2xx/3xx status is answered 424 `target_blocked` straight away, with the site's body and the headers `x-qp-unlocker: target_blocked`, `x-qp-origin-status` (the status the site sent), `x-qp-unlocker-blocked`, `x-qp-block-class` and `x-qp-vendor`. A refusal the site sent under its own status (403, 429, 503) is relayed with that status and the same diagnostic headers, and becomes 424 only with `x-qp-fail-on-block: 1`. Captchas: when the service has the captcha solver enabled (`captcha_solver` of `GET /public/unlock/offer`), DataDome and AWS WAF challenges are handed to it, and `attempt_log` shows that step as a `solver` entry. Any other interactive captcha is returned as `blockClass: "captcha"`.

### Reading a block: vendor and blockClass

When an attempt meets a wall, the engine names the system it recognised in `vendor` and the kind of stop in `blockClass`. Both are on the REST answer when `blocked` is `true`, on the entries of `attempt_log`, on each result of a batch, and on the proxy as the headers `x-qp-vendor` and `x-qp-block-class`.

| `vendor` | System | What the block of that system looks like |
| --- | --- | --- |
| `cloudflare` | Cloudflare | 403 with "Just a moment..." and the header `cf-mitigated: challenge`; errors 1020, 1015, 1010, 1009 |
| `datadome` | DataDome | 403 with "Please enable JS and disable any ad blocker" and a script from `captcha-delivery.com` |
| `akamai` | Akamai Bot Manager | 403 "Access Denied ... Reference #18..." |
| `perimeterx` | PerimeterX (HUMAN) | 403 with "Press & Hold to confirm you are a human"; on API calls a JSON body with `appId` |
| `kasada` | Kasada | 429 on the first request, with an almost empty page that loads `ips.js` |
| `imperva` | Imperva (Incapsula) | "Pardon Our Interruption" or "Request unsuccessful. Incapsula incident ID", often with status 200 |
| `shape` | F5 (BIG-IP, Shape) | "Request Rejected ... Your support ID is", often with status 200 |
| `awswaf` | AWS WAF | 202 (Challenge) or 405 (CAPTCHA), with the header `x-amzn-waf-action` |
| `amazon`, `google`, `reddit`, `yandex` | The site's own wall | The page that site shows to automated traffic |
| `hcaptcha`, `recaptcha` | A captcha widget | An interactive captcha on the page |
| `unknown` | Not recognised | Read `blockReason` and the body |

| `blockClass` | What stopped the call | What to do |
| --- | --- | --- |
| `js_challenge` | A check that a real browser clears by running a script | Leave `mode` on `auto`, or use `browser`. With `mode: "tls"` no browser is opened |
| `captcha` | The page asks a person: a puzzle, a slider, press and hold | Retry later or from another `country`. See the captcha rule above |
| `access_denied` | A flat refusal, with no challenge offered | Retry; try another `country` or the mobile tier |
| `rate_limited` | A plain 429 | Slow down or spread the calls. Do not pin one session |
| `fingerprint` | The client itself was judged automated | Leave `mode` on `auto`: the browser tier is the next step |
| `geo` | The site does not serve the country of the exit | Set `country` to one the site serves |
| `timeout` | The site or the exit never answered | Retry |
| `unknown` | Not classified | Read `blockReason` and the body |

Two things worth knowing when you read the answer:

- The status code of the site is not proof. Imperva and F5 often serve their block page with status 200, and Kasada answers a new visitor with 429 before any rate was exceeded. `blocked` is the field to trust; `fail_on_block: true` turns a blocked answer into 424 `target_blocked`.
- `clearance` says what happened to the session of that site. `minted`: this call passed the site's check and the session was kept. `hit`: this call reused a kept session, so no new check was run. `stale`: a kept session was refused and dropped. `miss`: there was none. The first call to a protected site is the slow one; the next calls from the same account reuse the session until the site asks again.


## Coming from another unlocker

Code written for another unlocker needs a new host, port and credentials. After that, most options keep working or need one rename: the proxy already reads several header names such code sends, and the rest map one to one to ours.

### Our names

| Option | REST field | Proxy header | Proxy username |
|---|---|---|---|
| Country | `country` | `x-qp-country` | `-country-xx` |
| Session | `session_id` | `x-qp-session` | `-session-<id>` |
| Render | `mode: "browser"`; `render: "png"` for a screenshot | `x-qp-mode: browser`; `x-qp-render: png` |  |
| Device | `mobile: true` or `tls_profile` | `x-qp-profile` | `-mobile`, `-profile-<name>` |
| Custom success codes | `success_status_codes` | `x-qp-success-status` |  |
| Markdown | `format: "markdown"` |  |  |
| Wait for an element | `wait_for_selector` | `x-qp-wait-for` |  |
| Timeout | `timeout_ms` | `x-qp-timeout` |  |

### Names the proxy reads unchanged

A request that already carries one of these needs no change for that option. The `-country-xx` suffix of the proxy username is read as it is too.

| Option | Our header | Also read |
|---|---|---|
| Country | `x-qp-country` | `x-oxylabs-geo-location`, `x-brd-country`, `x-unblock-country` |
| Session | `x-qp-session` | `x-oxylabs-session-id`, `x-brd-session`, `x-unblock-session` |
| Render | `x-qp-render` | `x-oxylabs-render`, `x-brd-render`, `x-unblock-render` |
| Custom success codes | `x-qp-success-status` | `x-oxylabs-successful-status-codes`, `x-unblock-success-status` |
| Own headers sent as they are | `x-qp-keep-headers` | `x-oxylabs-force-headers`, `x-unblock-keep-headers` |
| Target URL in direct mode | `x-qp-url` | `x-oxylabs-url`, `x-brd-url`, `x-unblock-url` |

The country value must be a 2-letter code: a value such as `City,State,US` is reduced to `us`, and a country name is ignored and reported in `x-qp-warning`.

### Names to rename

These are not read: replace each with ours.

| Option | A name your code may send | Ours |
|---|---|---|
| Country | `X-SU-Geo` | `x-qp-country`, `country` |
| Session | `X-SU-Session-Id` | `x-qp-session`, `session_id` |
| Render | `-render` in the proxy username; `X-SU-Headless: html` or `png` | `x-qp-mode: browser` or `x-qp-render: png`; `mode: "browser"`, `render: "png"` |
| Device | `-ua-mobile` in the proxy username; `X-SU-Device-Type: mobile` | `-mobile` in the proxy username, `x-qp-profile: mobile`, `mobile: true` |
| Custom success codes | `X-SU-Status-Code` | `x-qp-success-status`, `success_status_codes` |
| Markdown | `x-unblock-data-format: markdown`; `data_format` in a REST body; `X-SU-Markdown` | `format: "markdown"` on the REST call |
| Wait for an element | `x-unblock-expect`; `wait_for_element` in `x-oxylabs-browser-instructions` | `x-qp-wait-for`, `wait_for_selector`; other steps go in `actions` on the REST call |

### Replay a request through the Web Unlocker

`POST /scraper/unlock`

**Price:** `unlock_request`. Billed per GB on `usage.bytes`, debited from the prepaid Web Unlocker GB of the chosen tier, never from the wallet. The price per GB of each tier is on the [plans page](https://app.quanticdata.io/plans?network=UNLOCK) of the dashboard and, when the offer is published, in `GET /public/unlock/offer`. 402 when the tier has no usable GB (never bought, used up or expired).  
**Rate limit:** Per API key, by tier (see Rate limits and tiers).  
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/data-api.md)

Send a request the way your own HTTP client would (`url`, `method`, `headers`, `body`) and get it back replayed through a residential or mobile exit under a real browser TLS fingerprint. `mode` decides how far the engine goes: `auto` (default) retries a blocked GET/HEAD/OPTIONS on a fresh exit under a different fingerprint and escalates to a headless browser that answers JavaScript challenges; `tls` never opens the browser; `browser` renders straight away. Any other method gets exactly one attempt (a response means the target saw it, and replaying a POST could double-submit). `format` returns `body` as HTML, Markdown or plain text (`bodyBase64` stays the raw page); `max_bytes` caps what one call may move; `timeout_ms` is the total budget, attempts and render included. `actions` runs clicks, typing, scrolls and waits in the browser before the capture; `cache_ttl` answers a repeated GET from a stored copy, which moves no bytes and costs nothing. A page still blocked after every attempt comes back as 200 with `blocked: true`, `blockClass`, `vendor` and `hint`, never as a silent success; `fail_on_block: true` turns it into 424 `target_blocked`. Every answer carries `request_id`, `latency_ms`, `tier_served`, `attempt_log` and `cost`. When the service has the captcha solver enabled, DataDome and AWS WAF challenges are handed to it; any other interactive captcha is returned as `blockClass: "captcha"`. This is the same engine as the forward proxy (top of this section), without the proxy protocol: no certificate to install; the same call works on `https://app.quanticdata.io/api/v1/scraper/unlock`. Billing is different from every other Data API call: it is metered in bytes against the tier's prepaid Web Unlocker GB (`premium` = residential exits, `mobile` = mobile exits), not the wallet, and every attempt counts (retries, a blocked page, the browser's page load). Errors: one catalogue for the REST call and the proxy, see Unlock errors above. Field names: every camelCase field is also accepted in snake_case (`fail_on_block`, `success_status_codes`, `tls_profile`, `session_id`, `session_duration`, `keep_headers`, `wait_for_selector`, `wait_ms`, `return_cookies`, `auto_render`), and `max_bytes` / `timeout_ms` / `cache_ttl` are also accepted as `maxBytes` / `timeoutMs` / `cacheTtl`. Many URLs at once: `POST /scraper/unlock/batch`.

#### Request body (required)

`Content-Type: application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | Target URL, `http://` or `https://`. Private, reserved and internal addresses are refused (403 `target_forbidden`); some destinations are not served (403 `target_denied`). |
| `method` | string | no |  Default `"GET"`. |
| `headers` | object \\| string | no | Extra headers replayed to the target. Either a JSON object (name → value) or a raw `Header: Value` block, one per line (lines starting with `//` or `#` are ignored). Max 32 headers, names must be RFC 7230 tokens, values ≤ 4096 characters; hop-by-hop and framing headers (host, content-length, transfer-encoding, connection, …) are rejected. |
| `body` | string | no | Request body as UTF-8 text (JSON, form data…). Use this OR `bodyBase64`. |
| `bodyBase64` | string | no | Request body as base64 for binary payloads. Max 8 MB decoded. |
| `tier` | string: `premium`, `mobile` | no | Which prepaid pool pays and which exits are used. Anything other than `mobile` is `premium`. Default `"premium"`. |
| `mode` | string: `auto`, `tls`, `browser` | no | How far the engine goes. `auto`: TLS tier first, a new exit and fingerprint on each blocked attempt, then the headless browser (it can start in parallel after repeated blocks); `tls`: TLS tier only, never the browser, a blocked page is returned as-is; `browser`: straight to the headless browser (GET/HEAD). The answer says which tier produced it in `tier_served`. Replaces `autoRender` (`mode: "tls"` is the old `autoRender: false`) and `render: "html"` (`mode: "browser"`). Default `"auto"`. |
| `format` | string: `html`, `markdown`, `text` | no | Format of `body` for HTML responses: the page as HTML, converted to Markdown, or reduced to its text. `bodyBase64` is always the raw page. Ignored when the response is not HTML (JSON, XML, binary); the format served is echoed in `format`. Default `"html"`. |
| `max_bytes` | integer | no | Cap on the bytes this call may move across every attempt (request and response bodies, the browser's page load included). The TLS tier stops downloading past the cap; when the bytes moved exceed it the answer is 403 `max_bytes_exceeded` with `usage` and `cost`: the bytes moved are debited. Also accepted as `maxBytes`. |
| `timeout_ms` | integer | no | Total budget of the call in milliseconds: every attempt, the browser render and its settle time fit inside it, never in addition. When it runs out before a response the answer is 504 `timeout`. Also accepted as `timeoutMs`. Default `60000`. |
| `fail_on_block` | boolean | no | `true`: a page still blocked after every attempt answers 424 `target_blocked` (same diagnostics in `payload`) instead of a 200 with `blocked: true`. The GB moved are debited either way. Also accepted as `failOnBlock`. Default `false`. |
| `actions` | array of object (UnlockAction) | no | Browser interactions to run, in order, before the page is captured: at most 20. Actions force the browser tier (`tier_served: "browser"`), so they work on GET and HEAD only; together with `mode: "tls"` (or `render: false`, `autoRender: false`) they are refused with 400 `bad_request`. REST only: the proxy has no header for them. |
| `actions[].click` | string | no | Click the element matching this CSS selector (up to 256 characters, like every selector here). |
| `actions[].clickText` | string | no | Click the element whose visible text contains this string (up to 256 characters), case-insensitive. Useful for a consent or accept button whose CSS is unknown. |
| `actions[].within` | string | no | With `clickText` only: CSS selector of the area to search in. |
| `actions[].type` | object | no | Type text into a field: `{"selector": "#search", "text": "running shoes"}`. The text can be up to 2000 characters. |
| `actions[].scroll` | string: `bottom`, `top` \\| integer | no | Scroll the window to the `bottom`, to the `top`, or by a whole number of pixels (up to 100000 either way). |
| `actions[].scrollIn` | object | no | Scroll inside a scrollable element, for example a results pane, instead of the window: `{"selector": ".feed", "passes": 5}`. Each pass scrolls it to its bottom and waits for new content; it stops early when nothing more loads. `passes` is 1 to 15. |
| `actions[].wait` | integer | no | Wait this many milliseconds, 0 to 15000. |
| `actions[].waitForSelector` | string | no | Wait until an element matching this CSS selector appears. |
| `actions[].optional` | boolean | no | `true`: when the action fails (element missing, timeout) the run goes on instead of failing. Default `false`. |
| `actions[].timeoutMs` | integer | no | How long this action waits for its element, in milliseconds, 100 to 30000. The whole call still fits in `timeout_ms`. |
| `cache_ttl` | integer | no | Seconds a usable answer may be served from the cache; 0 is off. A GET the site answered 2xx and that was not blocked is kept for your account for that long. A later call with the same `url`, `mode`, `format`, `country`, `tier`, render kind and `actions` is answered from the copy: `cache: "hit"`, no bytes moved, nothing billed. Also accepted as `cacheTtl`; `x-qp-cache-ttl` on the proxy. Default `0`. |
| `country` | string | no | Country code or place name: letters, digits, spaces, dots, hyphens, underscores; max 56 characters. `all` means no targeting. |
| `state` | string | no | Country code or place name: letters, digits, spaces, dots, hyphens, underscores; max 56 characters. `all` means no targeting. |
| `city` | string | no | Country code or place name: letters, digits, spaces, dots, hyphens, underscores; max 56 characters. `all` means no targeting. |
| `rotation` | string: `rotating`, `sticky` | no |  Default `"rotating"`. |
| `sessionId` | string | no | Sticky session id — reuse it across calls to keep one exit IP. |
| `sessionDuration` | number | no | Sticky session lifetime in minutes. |
| `tlsProfile` | string: `chrome`, `firefox`, `safari`, `safari_ios`, `edge`, `brave`, `mobile` | no |  Default `"chrome"`. |
| `mobile` | boolean | no | Mobile Safari fingerprint (fingerprint only — the product tier is `tier`). Default `false`. |
| `render` | string: `html`, `png` \\| boolean | no | `png` returns a screenshot of the page from the headless browser (GET/HEAD, one render token). `html` or `true` is the same as `mode: "browser"`; `false` is the same as `mode: "tls"`. `mode` wins when both are sent. |
| `autoRender` | boolean | no | Deprecated, use `mode`: `autoRender: false` is `mode: "tls"` (no browser escalation of a blocked GET). Still accepted, also as `auto_render`. Default `true`. |
| `keepHeaders` | boolean | no | Send your own identity headers (User-Agent, Accept, Sec-Fetch-*) verbatim instead of the fingerprint's. Default `false`. |
| `successStatusCodes` | array of integer | no | Origin statuses to accept as success — never treated as a block, never retried. |
| `timeoutMs` | integer | no | Same as `timeout_ms` (older spelling): the total budget of the call, not a per-attempt timeout. |
| `failOnBlock` | boolean | no | Same as `fail_on_block` (older spelling). Default `false`. |
| `waitForSelector` | string | no | Browser tier: CSS selector to wait for before capture. |
| `waitMs` | integer | no | Browser tier: extra settle time in milliseconds after the page loads. |
| `returnCookies` | boolean | no | Return the origin's cookie jar under `cookies`. Default `false`. |
| `cookies` | object | no | Cookies merged into the Cookie header sent to the target (e.g. a clearance obtained earlier). |

Example:

```json
{
  "url": "https://example.com/",
  "country": "us",
  "tier": "premium",
  "mode": "auto",
  "format": "html",
  "timeout_ms": 60000,
  "max_bytes": 5000000
}
```

#### Examples

**curl**

```bash
curl -X POST https://app.quanticdata.io/api/v1/scraper/unlock \
  -H "Authorization: Bearer qd_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/", "country": "us"}'
```

**Python (requests)**

```python
import requests

r = requests.post(
    "https://app.quanticdata.io/api/v1/scraper/unlock",
    headers={"Authorization": "Bearer qd_live_YOUR_API_KEY"},
    json={"url": "https://example.com/", "country": "us"},
    timeout=130,
)
page = r.json()["payload"]
print(page["status"], page["blocked"], page["latency_ms"], page["cost"])
print(page["body"][:500])
```

**Node (fetch)**

```javascript
const res = await fetch("https://app.quanticdata.io/api/v1/scraper/unlock", {
  method: "POST",
  headers: { Authorization: "Bearer qd_live_YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ url: "https://example.com/", country: "us" }),
});
const { payload: page } = await res.json();
console.log(page.status, page.blocked, page.latency_ms, page.cost);
console.log(page.body.slice(0, 500));
```

**PHP (curl)**

```php
<?php
$ch = curl_init("https://app.quanticdata.io/api/v1/scraper/unlock");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 130,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer qd_live_YOUR_API_KEY", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode(["url" => "https://example.com/", "country" => "us"]),
]);
$page = json_decode(curl_exec($ch), true)["payload"];
echo $page["status"], " ", $page["blocked"] ? "blocked" : "ok", " ", $page["latency_ms"], " ms\n";
echo substr($page["body"], 0, 500);
```

**Go**

```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	body, _ := json.Marshal(map[string]string{"url": "https://example.com/", "country": "us"})
	req, _ := http.NewRequest("POST", "https://app.quanticdata.io/api/v1/scraper/unlock", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer qd_live_YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	var out struct {
		Payload struct {
			Status    int    `json:"status"`
			Blocked   bool   `json:"blocked"`
			LatencyMs int    `json:"latency_ms"`
			Body      string `json:"body"`
		} `json:"payload"`
	}
	json.NewDecoder(res.Body).Decode(&out)
	fmt.Println(out.Payload.Status, out.Payload.Blocked, out.Payload.LatencyMs, len(out.Payload.Body))
}
```

#### Responses

- `200` — The target's response, replayed, or the block page it answered with (`blocked: true`, see the second example). Both carry the diagnostics (`request_id`, `latency_ms`, `tier_served`, `attempt_log`) and the cost of the call (`usage`, `cost`). The third example is an answer served from the cache. The `cost.usd` figures in the examples are example values, not a price list.
- `400` — `bad_request`: a parameter is invalid; `message` names it and the rule it broke. Nothing ran, nothing billed.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `402` — `no_credit`: the tier has no usable Web Unlocker GB, never bought, used up or expired. `message` says which and ends with the link to buy GB (paid from the wallet, separate from the Data API free credit); `payload.reason` is `never_bought`, `used_up` or `expired` and `payload.buy_url` is the same link. Nothing billed.
- `403` — `target_forbidden` (private, reserved or internal address), `target_denied` (a destination the unlocker does not serve) or `no_exit_pool` (the account has no exit pool for the tier, e.g. `mobile` without a mobile sub-user): the request did not run, nothing billed. `max_bytes_exceeded`: the bytes moved went over `max_bytes`; `payload.usage` and `payload.cost` say how many, and they are debited.
- `422` — `action_failed`, only with `actions`: the page loaded but one of the actions could not run. `message` names the action by its position and shape and says why. Not retryable as it is, nothing billed.
- `424` — `target_blocked`, only with `fail_on_block: true`: every attempt came back blocked. Same diagnostics as the 200 form (`status` of the block page, `blockReason`, `blockClass`, `vendor`, `attempts`, `attempt_log`, `tier_served`); the GB moved are debited (`usage`, `cost`). Retryable: later, on the `mobile` tier, from another country or with `mode: "browser"`.
- `429` — `rate_limited`: the requests per minute or the concurrent requests of the account's tier (see Rate limits and tiers). Back off for `Retry-After` seconds. Not billed.
- `500` — `internal_error`: an error on our side. Retryable; not billed. Quote `request_id` to support when it persists.
- `503` — Temporary, retryable, never billed: `upstream_failed` (the exit or the target could not be reached), `render_failed` (the browser could not load the page) or `service_unavailable` (the engine or the API is not answering; also while the Data API is switched off for the account). On the proxy the same codes answer 503, never 407.
- `504` — `timeout`: `timeout_ms` ran out before a response (every attempt and the browser render share that budget). Retryable; not billed.

Example `200` response:

```json
{
  "type": "response",
  "message": "Unlocker request successful",
  "payload": {
    "request_id": "7c1f1b2e-5d3a-4a9e-9c0b-2f6e8a1d4b73",
    "status": 200,
    "headers": {
      "content-type": "text/html; charset=utf-8",
      "cache-control": "max-age=600"
    },
    "body": "<!doctype html><html><head><title>Example Domain</title></head><body><p>This domain is for use in illustrative examples in documents.</p></body></html>",
    "bodyBase64": "PCFkb2N0eXBlIGh0bWw+PGh0bWw+PGhlYWQ+PHRpdGxlPkV4YW1wbGUgRG9tYWluPC90aXRsZT48L2hlYWQ+PGJvZHk+PGgxPkV4YW1wbGUgRG9tYWluPC9oMT48cD5UaGlzIGRvbWFpbiBpcyBmb3IgdXNlIGluIGlsbHVzdHJhdGl2ZSBleGFtcGxlcyBpbiBkb2N1bWVudHMuPC9wPjwvYm9keT48L2h0bWw+",
    "finalUrl": "https://example.com/",
    "contentType": "text/html; charset=utf-8",
    "profile": "chrome",
    "attempts": 1,
    "cache": "off",
    "blocked": false,
    "clearance": "miss",
    "exitSessionId": "s_2f91",
    "strategy": {
      "startTier": "tls",
      "hedged": false
    },
    "rendered": false,
    "escalated": false,
    "mode": "auto",
    "tier_served": "tls",
    "format": "html",
    "tier": "premium",
    "geo": {
      "country": "us",
      "state": null,
      "city": null,
      "rotation": "rotating"
    },
    "latency_ms": 1840,
    "attempt_log": [
      {
        "tier": "tls",
        "profile": "chrome",
        "exit_country": "us",
        "outcome": "ok",
        "ms": 1840,
        "bytes": 18432
      }
    ],
    "usage": {
      "bytes": 18432,
      "unlock_gb_remaining": 4.98,
      "unlock_gb_purchased": 5
    },
    "cost": {
      "bytes": 18432,
      "usd": 0.000044,
      "billed": true
    }
  },
  "pagination": {}
}
```

Example `400`:

```json
{
  "type": "error",
  "message": "Invalid timeout_ms. Must be an integer between 1000 and 120000",
  "payload": {
    "code": "bad_request",
    "retryable": false,
    "billed": false,
    "hint": "Fix the parameter named in the message and send the request again.",
    "doc_url": "https://quanticdata.io/docs/#unlock-errors"
  }
}
```

Example `401`:

```json
{
  "type": "error",
  "message": "Missing or invalid Authorization header. Use: Authorization: Bearer qd_live_YOUR_API_KEY"
}
```

Example `402`:

```json
{
  "type": "error",
  "message": "This account has no residential Web Unlocker GB yet. The unlocker is prepaid per GB, separate from the Data API free credit, and paid from your wallet balance. Buy GB, then retry, your API key stays the same: https://app.quanticdata.io/plans?network=UNLOCK&utm_source=api&utm_medium=402&utm_campaign=web-unlocker",
  "payload": {
    "code": "no_credit",
    "retryable": false,
    "billed": false,
    "hint": "Buy GB from the dashboard, then retry with the same key or proxy user.",
    "doc_url": "https://quanticdata.io/docs/#unlock-errors",
    "reason": "never_bought",
    "tier": "premium",
    "unlock_gb_remaining": 0,
    "unlock_gb_purchased": 0,
    "expires_at": null,
    "expired": false,
    "buy_url": "https://app.quanticdata.io/plans?network=UNLOCK&utm_source=api&utm_medium=402&utm_campaign=web-unlocker"
  }
}
```

Example `403`:

```json
{
  "type": "error",
  "message": "The mobile Web Unlocker has no exit pool for your account yet.",
  "payload": {
    "code": "no_exit_pool",
    "retryable": false,
    "billed": false,
    "hint": "Buy GB on this tier so its exit pool is set up, or use tier \"premium\".",
    "doc_url": "https://quanticdata.io/docs/#unlock-errors",
    "tier": "mobile"
  }
}
```

Example `422`:

```json
{
  "type": "error",
  "message": "Action 2 failed ({\"waitForSelector\":\".results\"}): nothing on the page matched it within 15000 ms",
  "payload": {
    "code": "action_failed",
    "retryable": false,
    "billed": false,
    "hint": "The page loaded but one of your actions could not run. Check the selector or the text of the action named in the message.",
    "doc_url": "https://quanticdata.io/docs/#unlock-errors",
    "url": "https://example.com/search?q=shoes",
    "request_id": "7c1f0a9e2b4d6e80",
    "latency_ms": 17480,
    "mode": "auto",
    "attempt_log": []
  }
}
```

Example `424`:

```json
{
  "type": "error",
  "message": "The target refused the request on every tier.",
  "payload": {
    "code": "target_blocked",
    "retryable": true,
    "billed": true,
    "hint": "Retry with mode \"browser\", another country, or a sticky session; drop fail_on_block to receive the blocked page as a 200.",
    "doc_url": "https://quanticdata.io/docs/#unlock-errors",
    "request_id": "0b7d9e42-1c35-4f8a-b6d2-9e4f3a7c5d11",
    "status": 403,
    "blockReason": "js_challenge",
    "blockClass": "js_challenge",
    "vendor": "cloudflare",
    "attempts": 4,
    "tier_served": "browser",
    "rendered": true,
    "escalated": true,
    "latency_ms": 13095,
    "attempt_log": [
      {
        "tier": "tls",
        "profile": "chrome",
        "exit_country": "us",
        "outcome": "blocked",
        "ms": 1210,
        "bytes": 42010,
        "block_class": "js_challenge",
        "reason": "js_challenge"
      },
      {
        "tier": "tls",
        "profile": "firefox",
        "exit_country": "us",
        "outcome": "blocked",
        "ms": 980,
        "bytes": 41366,
        "block_class": "js_challenge",
        "reason": "js_challenge"
      },
      {
        "tier": "tls",
        "profile": "safari",
        "exit_country": "us",
        "outcome": "blocked",
        "ms": 1105,
        "bytes": 41620,
        "block_class": "js_challenge",
        "reason": "js_challenge"
      },
      {
        "tier": "browser",
        "profile": "chrome",
        "exit_country": "us",
        "outcome": "blocked",
        "ms": 9800,
        "bytes": 309504,
        "block_class": "js_challenge",
        "reason": "challenge:challenge-platform"
      }
    ],
    "usage": {
      "bytes": 434500,
      "unlock_gb_remaining": 4.979,
      "unlock_gb_purchased": 5
    },
    "cost": {
      "bytes": 434500,
      "usd": 0.001043,
      "billed": true
    }
  }
}
```

Example `429`:

```json
{
  "type": "error",
  "message": "Too many requests for this account right now.",
  "payload": {
    "code": "rate_limited",
    "retryable": true,
    "billed": false,
    "hint": "Wait for Retry-After seconds, lower your concurrency, or move to a plan with a higher limit.",
    "doc_url": "https://quanticdata.io/docs/#unlock-errors",
    "retry_after": 5
  }
}
```

Example `500`:

```json
{
  "type": "error",
  "message": "The unlocker hit an internal error.",
  "payload": {
    "code": "internal_error",
    "retryable": true,
    "billed": false,
    "hint": "Retry; if it persists contact support with the request_id.",
    "doc_url": "https://quanticdata.io/docs/#unlock-errors",
    "request_id": "e4d1c6a0-2b7f-4c58-9a13-7f0e5b2d8c91"
  }
}
```

Example `503`:

```json
{
  "type": "error",
  "message": "The exit or the target could not be reached.",
  "payload": {
    "code": "upstream_failed",
    "retryable": true,
    "billed": false,
    "hint": "Retry: the next attempt runs on a fresh exit.",
    "doc_url": "https://quanticdata.io/docs/#unlock-errors",
    "request_id": "9f2b4d6e-0a1c-4e83-b5d7-3c8e1f6a2d40"
  }
}
```

Example `504`:

```json
{
  "type": "error",
  "message": "No response before timeout_ms ran out.",
  "payload": {
    "code": "timeout",
    "retryable": true,
    "billed": false,
    "hint": "Raise timeout_ms (up to 120000) or use mode \"tls\" for a faster first answer.",
    "doc_url": "https://quanticdata.io/docs/#unlock-errors",
    "request_id": "6b0c2e4d-9a8f-4d17-b3e5-2f1a7c9d0e68",
    "timeout_ms": 60000
  }
}
```

Try it: https://app.quanticdata.io/data-api/playground

### Unlock many URLs asynchronously

`POST /scraper/unlock/batch`

**Price:** `unlock_request`. Every item is billed like a single call: per GB on the bytes it moved, from the prepaid Web Unlocker GB of the tier. The price per GB of each tier is on the [plans page](https://app.quanticdata.io/plans?network=UNLOCK) of the dashboard and, when the offer is published, in `GET /public/unlock/offer`.  
**Rate limit:** Per API key, by tier (see Rate limits and tiers).  
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/data-api.md)

Starts an asynchronous job of 1 to 100 unlock calls and answers 202 with its `batch_id` at once. Each entry of `requests` is a REST call: `url` plus any field of `POST /scraper/unlock`, `actions` and `cache_ttl` included. `defaults` holds fields applied to every item; an item's own field wins. `urls` is a shorthand for `requests` when the items are plain URLs: send one or the other. One batch runs on one tier and one exit setup, so `tier` is set at the top level, and `state`, `city`, `rotation`, `session_id` and `session_duration` only in `defaults`; `country` may differ per item unless `defaults` sets a state or a city. `fail_on_block` has no effect: every result carries `blocked`. `concurrency` (1 to 5, default 3) is how many items run at the same time. Poll `GET /scraper/unlock/batch/{batch_id}` for the results, or pass `webhook_url` to receive the finished batch in one POST. Same API key, same gate and same rate limits as the REST call; a batch with browser items takes one browser-render token when it is submitted. Billing: a batch spends the same prepaid GB of the tier, and every item is metered like a single call. The tier needs usable GB when the batch starts: without them the answer is 402 `no_credit`, and a batch never runs on a trial. Errors use the Unlock errors catalogue above.

#### Request body (required)

`Content-Type: application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `requests` | array of object (UnlockBatchItemRequest) | no | The unlock calls to run. |
| `requests[].url` | string | yes | Target URL, `http://` or `https://`. |
| `urls` | array of string | no | Shorthand for `requests` when every item is only a URL. |
| `defaults` | object | no | Fields of `POST /scraper/unlock` applied to every item (`country`, `mode`, `format`, `cache_ttl`, `timeout_ms`...); an item's own field wins. `state`, `city`, `rotation`, `session_id` and `session_duration` can only be set here. `url` cannot. |
| `webhook_url` | string | no | Public `http://` or `https://` URL, at most 2048 characters. When the batch ends it receives one POST with the batch view: the same JSON as `GET /scraper/unlock/batch/{batch_id}`, without bodies. |
| `concurrency` | integer | no | How many items run at the same time. Default `3`. |
| `tier` | string: `premium`, `mobile` | no | Which prepaid pool pays the batch and which exits are used, for every item. `defaults.tier` is read the same way. Default `"premium"`. |

Example:

```json
{
  "requests": [
    {
      "url": "https://example.com/a"
    },
    {
      "url": "https://example.com/b",
      "mode": "browser",
      "wait_for_selector": "#prices"
    },
    {
      "url": "https://example.com/c"
    }
  ],
  "defaults": {
    "country": "us",
    "format": "markdown",
    "cache_ttl": 3600
  },
  "concurrency": 3,
  "webhook_url": "https://hooks.example.com/unlock-batch"
}
```

#### Examples

**curl**

```bash
curl -X POST 'https://api.quanticdata.io/v1/scraper/unlock/batch' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"requests":[{"url":"https://example.com/a"},{"url":"https://example.com/b","mode":"browser","wait_for_selector":"#prices"},{"url":"https://example.com/c"}],"defaults":{"country":"us","format":"markdown","cache_ttl":3600},"concurrency":3,"webhook_url":"https://hooks.example.com/unlock-batch"}'
```

**Python (requests)**

```python
import requests

r = requests.post(
    'https://api.quanticdata.io/v1/scraper/unlock/batch',
    headers={"Authorization": "Bearer qd_live_YOUR_API_KEY"},
    json={
        "requests": [
            {
                "url": "https://example.com/a"
            },
            {
                "url": "https://example.com/b",
                "mode": "browser",
                "wait_for_selector": "#prices"
            },
            {
                "url": "https://example.com/c"
            }
        ],
        "defaults": {
            "country": "us",
            "format": "markdown",
            "cache_ttl": 3600
        },
        "concurrency": 3,
        "webhook_url": "https://hooks.example.com/unlock-batch"
    },
    timeout=120,
)
data = r.json()
if data["type"] != "response":
    raise SystemExit(data["message"])
print(data["payload"])
```

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/scraper/unlock/batch", {
  method: "POST",
  headers: {
    Authorization: "Bearer qd_live_YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "requests": [
      {
        "url": "https://example.com/a"
      },
      {
        "url": "https://example.com/b",
        "mode": "browser",
        "wait_for_selector": "#prices"
      },
      {
        "url": "https://example.com/c"
      }
    ],
    "defaults": {
      "country": "us",
      "format": "markdown",
      "cache_ttl": 3600
    },
    "concurrency": 3,
    "webhook_url": "https://hooks.example.com/unlock-batch"
  })
});
const data = await res.json();
if (data.type !== "response") throw new Error(data.message);
console.log(data.payload);
```

**PHP (curl)**

```php
<?php
$ch = curl_init('https://api.quanticdata.io/v1/scraper/unlock/batch');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode([
    'requests' => [[
      'url' => 'https://example.com/a'
    ], [
      'url' => 'https://example.com/b',
      'mode' => 'browser',
      'wait_for_selector' => '#prices'
    ], [
      'url' => 'https://example.com/c'
    ]],
    'defaults' => [
      'country' => 'us',
      'format' => 'markdown',
      'cache_ttl' => 3600
    ],
    'concurrency' => 3,
    'webhook_url' => 'https://hooks.example.com/unlock-batch'
  ]),
]);
$raw = curl_exec($ch);
curl_close($ch);
$data = json_decode($raw, true);
if ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }
print_r($data['payload']);
```

#### Responses

- `202` — Batch accepted and running.
- `400` — `bad_request`: the body or an item is invalid; `message` names the item (`requests[3]: …`) and the rule it broke. Nothing ran, nothing billed.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `402` — `no_credit`: the tier has no usable Web Unlocker GB, never bought, used up or expired. `payload.reason` says which and `payload.buy_url` is the page to buy GB. A batch never runs on a trial. Nothing ran, nothing billed.
- `403` — `no_exit_pool`: the account has no exit pool for the tier (e.g. `mobile` without mobile GB). Nothing ran, nothing billed.
- `429` — `rate_limited`: the requests per minute, the concurrent requests or the browser-render budget of the account's tier (see Rate limits and tiers). Back off for `Retry-After` seconds. Not billed.
- `500` — `internal_error`: an error on our side. Retryable; not billed.
- `503` — `service_unavailable`: the engine or the API is not answering. Retryable; nothing was started or billed.
- `504` — `timeout`: the engine did not accept the request in time. Retryable; not billed.

Example `202` response:

```json
{
  "type": "response",
  "message": "Batch accepted",
  "payload": {
    "batch_id": "ub_5e1c9a40d27f",
    "status": "running",
    "total": 3,
    "status_url": "/api/v1/scraper/unlock/batch/ub_5e1c9a40d27f"
  },
  "pagination": {}
}
```

Example `400`:

```json
{
  "type": "error",
  "message": "requests[1]: rotation applies to the whole batch; set it in defaults",
  "payload": {
    "code": "bad_request",
    "retryable": false,
    "billed": false,
    "hint": "Fix the parameter named in the message and send the request again.",
    "doc_url": "https://quanticdata.io/docs/#unlock-errors"
  }
}
```

Example `401`:

```json
{
  "type": "error",
  "message": "Missing or invalid Authorization header. Use: Authorization: Bearer qd_live_YOUR_API_KEY"
}
```

Example `402`:

```json
{
  "type": "error",
  "message": "This account has no residential Web Unlocker GB yet. The unlocker is prepaid per GB, separate from the Data API free credit, and paid from your wallet balance. Buy GB, then retry, your API key stays the same: https://app.quanticdata.io/plans?network=UNLOCK&utm_source=api&utm_medium=402&utm_campaign=web-unlocker",
  "payload": {
    "code": "no_credit",
    "retryable": false,
    "billed": false,
    "hint": "Buy GB from the dashboard, then retry with the same key or proxy user.",
    "doc_url": "https://quanticdata.io/docs/#unlock-errors",
    "reason": "never_bought",
    "tier": "premium",
    "unlock_gb_remaining": 0,
    "unlock_gb_purchased": 0,
    "expires_at": null,
    "expired": false,
    "buy_url": "https://app.quanticdata.io/plans?network=UNLOCK&utm_source=api&utm_medium=402&utm_campaign=web-unlocker"
  }
}
```

Example `403`:

```json
{
  "type": "error",
  "message": "The mobile Web Unlocker has no exit pool for your account yet. Buy mobile unlocker GB, or use the premium tier.",
  "payload": {
    "code": "no_exit_pool",
    "retryable": false,
    "billed": false,
    "hint": "Buy GB on this tier so its exit pool is set up, or use tier \"premium\".",
    "doc_url": "https://quanticdata.io/docs/#unlock-errors",
    "tier": "mobile"
  }
}
```

Example `429`:

```json
{
  "type": "error",
  "message": "Too many requests for this account right now.",
  "payload": {
    "code": "rate_limited",
    "retryable": true,
    "billed": false,
    "hint": "Wait for Retry-After seconds, lower your concurrency, or move to a plan with a higher limit.",
    "doc_url": "https://quanticdata.io/docs/#unlock-errors",
    "retry_after": 5
  }
}
```

Example `500`:

```json
{
  "type": "error",
  "message": "The unlocker hit an internal error.",
  "payload": {
    "code": "internal_error",
    "retryable": true,
    "billed": false,
    "hint": "Retry; if it persists contact support with the request_id.",
    "doc_url": "https://quanticdata.io/docs/#unlock-errors"
  }
}
```

Example `503`:

```json
{
  "type": "error",
  "message": "The unlocker service is not responding.",
  "payload": {
    "code": "service_unavailable",
    "retryable": true,
    "billed": false,
    "hint": "Retry in a few seconds.",
    "doc_url": "https://quanticdata.io/docs/#unlock-errors"
  }
}
```

Example `504`:

```json
{
  "type": "error",
  "message": "No response before timeout_ms ran out.",
  "payload": {
    "code": "timeout",
    "retryable": true,
    "billed": false,
    "hint": "Raise timeout_ms (up to 120000) or use mode \"tls\" for a faster first answer.",
    "doc_url": "https://quanticdata.io/docs/#unlock-errors"
  }
}
```

Try it: https://app.quanticdata.io/data-api/playground

### Poll an unlock batch

`GET /scraper/unlock/batch/{batch_id}`

**Price:** No charge.  
**Rate limit:** Per API key, by tier (see Rate limits and tiers).  
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/data-api.md)

Progress and results of a batch you own: `status`, the counters (`total`, `completed`, `ok`, `blocked`, `failed`) and `results`, one entry per item with the diagnostics and the cost of a single call. Bodies are left out unless you ask `include=body`; then each item carries `body` (text, in the `format` it asked for) or `body_base64`. `offset` and `limit` page through `results`: 50 per page by default, at most 100. A batch is kept for one hour after it ends. Free to poll.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `batch_id` | path | string | yes | Batch id returned by `POST /scraper/unlock/batch`. |
| `include` | query | string: `body` | no | `body` adds each item's page to `results`. |
| `offset` | query | integer | no | First result to return. Default `0`. |
| `limit` | query | integer | no | How many results to return. Default `50`. |

#### Examples

**curl**

```bash
curl -X GET 'https://api.quanticdata.io/v1/scraper/unlock/batch/ub_5e1c9a40d27f' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'
```

**Python (requests)**

```python
import requests

r = requests.get(
    'https://api.quanticdata.io/v1/scraper/unlock/batch/ub_5e1c9a40d27f',
    headers={"Authorization": "Bearer qd_live_YOUR_API_KEY"},
    timeout=120,
)
data = r.json()
if data["type"] != "response":
    raise SystemExit(data["message"])
print(data["payload"])
```

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/scraper/unlock/batch/ub_5e1c9a40d27f", {
  method: "GET",
  headers: {
    Authorization: "Bearer qd_live_YOUR_API_KEY"
  }
});
const data = await res.json();
if (data.type !== "response") throw new Error(data.message);
console.log(data.payload);
```

**PHP (curl)**

```php
<?php
$ch = curl_init('https://api.quanticdata.io/v1/scraper/unlock/batch/ub_5e1c9a40d27f');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],
]);
$raw = curl_exec($ch);
curl_close($ch);
$data = json_decode($raw, true);
if ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }
print_r($data['payload']);
```

#### Responses

- `200` — The batch view. The `cost.usd` figures in the example are example values, not a price list.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `404` — The batch id is unknown, belongs to another account, or the batch ended more than one hour ago: one and the same answer, so an id cannot be probed. The payload has the shape of the Unlock errors catalogue, with `code: "bad_request"`.
- `429` — `rate_limited`: the requests per minute, the concurrent requests or the browser-render budget of the account's tier (see Rate limits and tiers). Back off for `Retry-After` seconds. Not billed.
- `500` — `internal_error`: an error on our side. Retryable; not billed.
- `503` — `service_unavailable`: the engine or the API is not answering. Retryable; nothing was started or billed.

Example `200` response:

```json
{
  "type": "response",
  "message": "Batch status",
  "payload": {
    "batch_id": "ub_5e1c9a40d27f",
    "status": "completed",
    "total": 3,
    "completed": 3,
    "ok": 1,
    "blocked": 1,
    "failed": 1,
    "created_at": "2026-11-11T09:30:00.000Z",
    "finished_at": "2026-11-11T09:31:02.000Z",
    "results": [
      {
        "index": 0,
        "url": "https://example.com/a",
        "status": 200,
        "blocked": false,
        "request_id": "7c1f1b2e-5d3a-4a9e-9c0b-2f6e8a1d4b73",
        "latency_ms": 1840,
        "tier_served": "tls",
        "attempts": 1,
        "cost": {
          "bytes": 18432,
          "usd": 0.000044,
          "billed": true
        },
        "content_type": "text/html; charset=utf-8"
      },
      {
        "index": 1,
        "url": "https://example.com/b",
        "status": 403,
        "blocked": true,
        "block_class": "js_challenge",
        "vendor": "cloudflare",
        "request_id": "0b7d9e42-1c35-4f8a-b6d2-9e4f3a7c5d11",
        "latency_ms": 13095,
        "tier_served": "browser",
        "attempts": 4,
        "cost": {
          "bytes": 434500,
          "usd": 0.001043,
          "billed": true
        },
        "content_type": "text/html; charset=utf-8"
      },
      {
        "index": 2,
        "url": "https://example.com/c",
        "status": null,
        "blocked": false,
        "request_id": "6b0c2e4d-9a8f-4d17-b3e5-2f1a7c9d0e68",
        "latency_ms": 60000,
        "tier_served": null,
        "attempts": 1,
        "cost": {
          "bytes": 0,
          "usd": 0,
          "billed": false
        },
        "error": {
          "code": "timeout",
          "message": "No response before timeout_ms ran out."
        }
      }
    ]
  },
  "pagination": {}
}
```

Example `401`:

```json
{
  "type": "error",
  "message": "Missing or invalid Authorization header. Use: Authorization: Bearer qd_live_YOUR_API_KEY"
}
```

Example `404`:

```json
{
  "type": "error",
  "message": "Batch not found. A batch is kept for one hour after it finishes.",
  "payload": {
    "code": "bad_request",
    "retryable": false,
    "billed": false,
    "hint": "Fix the parameter named in the message and send the request again.",
    "doc_url": "https://quanticdata.io/docs/#unlock-errors"
  }
}
```

Example `429`:

```json
{
  "type": "error",
  "message": "Too many requests for this account right now.",
  "payload": {
    "code": "rate_limited",
    "retryable": true,
    "billed": false,
    "hint": "Wait for Retry-After seconds, lower your concurrency, or move to a plan with a higher limit.",
    "doc_url": "https://quanticdata.io/docs/#unlock-errors",
    "retry_after": 5
  }
}
```

Example `500`:

```json
{
  "type": "error",
  "message": "The unlocker hit an internal error.",
  "payload": {
    "code": "internal_error",
    "retryable": true,
    "billed": false,
    "hint": "Retry; if it persists contact support with the request_id.",
    "doc_url": "https://quanticdata.io/docs/#unlock-errors"
  }
}
```

Example `503`:

```json
{
  "type": "error",
  "message": "The unlocker service is not responding.",
  "payload": {
    "code": "service_unavailable",
    "retryable": true,
    "billed": false,
    "hint": "Retry in a few seconds.",
    "doc_url": "https://quanticdata.io/docs/#unlock-errors"
  }
}
```

Try it: https://app.quanticdata.io/data-api/playground

### Cancel an unlock batch

`DELETE /scraper/unlock/batch/{batch_id}`

**Price:** No charge.  
**Rate limit:** Per API key, by tier (see Rate limits and tiers).  
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/data-api.md)

Cancels the items of a batch you own that have not started. Items already running finish and are metered like any call; items never started move no bytes and cost nothing. The answer is the batch view without `results`; what was gathered so far stays readable with `GET /scraper/unlock/batch/{batch_id}`. Free.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `batch_id` | path | string | yes | Batch id returned by `POST /scraper/unlock/batch`. |

#### Examples

**curl**

```bash
curl -X DELETE 'https://api.quanticdata.io/v1/scraper/unlock/batch/ub_5e1c9a40d27f' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'
```

**Python (requests)**

```python
import requests

r = requests.delete(
    'https://api.quanticdata.io/v1/scraper/unlock/batch/ub_5e1c9a40d27f',
    headers={"Authorization": "Bearer qd_live_YOUR_API_KEY"},
    timeout=120,
)
data = r.json()
if data["type"] != "response":
    raise SystemExit(data["message"])
print(data["payload"])
```

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/scraper/unlock/batch/ub_5e1c9a40d27f", {
  method: "DELETE",
  headers: {
    Authorization: "Bearer qd_live_YOUR_API_KEY"
  }
});
const data = await res.json();
if (data.type !== "response") throw new Error(data.message);
console.log(data.payload);
```

**PHP (curl)**

```php
<?php
$ch = curl_init('https://api.quanticdata.io/v1/scraper/unlock/batch/ub_5e1c9a40d27f');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'DELETE',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],
]);
$raw = curl_exec($ch);
curl_close($ch);
$data = json_decode($raw, true);
if ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }
print_r($data['payload']);
```

#### Responses

- `200` — Cancelled: the counters of the batch, without `results`.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `404` — The batch id is unknown, belongs to another account, or the batch ended more than one hour ago: one and the same answer, so an id cannot be probed. The payload has the shape of the Unlock errors catalogue, with `code: "bad_request"`.
- `429` — `rate_limited`: the requests per minute, the concurrent requests or the browser-render budget of the account's tier (see Rate limits and tiers). Back off for `Retry-After` seconds. Not billed.
- `500` — `internal_error`: an error on our side. Retryable; not billed.
- `503` — `service_unavailable`: the engine or the API is not answering. Retryable; nothing was started or billed.

Example `200` response:

```json
{
  "type": "response",
  "message": "Batch cancelled",
  "payload": {
    "batch_id": "ub_5e1c9a40d27f",
    "status": "cancelled",
    "total": 3,
    "completed": 1,
    "ok": 1,
    "blocked": 0,
    "failed": 0,
    "created_at": "2026-11-11T09:30:00.000Z",
    "finished_at": "2026-11-11T09:30:05.000Z"
  },
  "pagination": {}
}
```

Example `401`:

```json
{
  "type": "error",
  "message": "Missing or invalid Authorization header. Use: Authorization: Bearer qd_live_YOUR_API_KEY"
}
```

Example `404`:

```json
{
  "type": "error",
  "message": "Batch not found. A batch is kept for one hour after it finishes.",
  "payload": {
    "code": "bad_request",
    "retryable": false,
    "billed": false,
    "hint": "Fix the parameter named in the message and send the request again.",
    "doc_url": "https://quanticdata.io/docs/#unlock-errors"
  }
}
```

Example `429`:

```json
{
  "type": "error",
  "message": "Too many requests for this account right now.",
  "payload": {
    "code": "rate_limited",
    "retryable": true,
    "billed": false,
    "hint": "Wait for Retry-After seconds, lower your concurrency, or move to a plan with a higher limit.",
    "doc_url": "https://quanticdata.io/docs/#unlock-errors",
    "retry_after": 5
  }
}
```

Example `500`:

```json
{
  "type": "error",
  "message": "The unlocker hit an internal error.",
  "payload": {
    "code": "internal_error",
    "retryable": true,
    "billed": false,
    "hint": "Retry; if it persists contact support with the request_id.",
    "doc_url": "https://quanticdata.io/docs/#unlock-errors"
  }
}
```

Example `503`:

```json
{
  "type": "error",
  "message": "The unlocker service is not responding.",
  "payload": {
    "code": "service_unavailable",
    "retryable": true,
    "billed": false,
    "hint": "Retry in a few seconds.",
    "doc_url": "https://quanticdata.io/docs/#unlock-errors"
  }
}
```

Try it: https://app.quanticdata.io/data-api/playground

### Download the unlocker CA certificate

`GET /scraper/unlock/ca`

**Price:** No charge.  
**Rate limit:** Per API key, by tier (see Rate limits and tiers).  
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/data-api.md)

The interception CA used by the Web Unlocker forward proxy (CONNECT mode). The proxy terminates your TLS to read and rewrite the request, so an HTTP client that keeps certificate verification on must trust this file for the target host: save it once as `unlocker-ca.pem` and pass it to the client (`curl --cacert unlocker-ca.pem …`, `verify="unlocker-ca.pem"`), as in the proxy snippets at the top of this section. Not needed for POST /scraper/unlock, nor for the proxy's direct mode. Public by nature, kept behind the key so downloads are attributable. Free.

#### Examples

**curl**

```bash
curl -X GET 'https://api.quanticdata.io/v1/scraper/unlock/ca' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'
```

**Python (requests)**

```python
import requests

r = requests.get(
    'https://api.quanticdata.io/v1/scraper/unlock/ca',
    headers={"Authorization": "Bearer qd_live_YOUR_API_KEY"},
    timeout=120,
)
r.raise_for_status()
open("response.out", "wb").write(r.content)
```

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/scraper/unlock/ca", {
  method: "GET",
  headers: {
    Authorization: "Bearer qd_live_YOUR_API_KEY"
  }
});
const bytes = Buffer.from(await res.arrayBuffer());
require("node:fs").writeFileSync("response.out", bytes);
```

**PHP (curl)**

```php
<?php
$ch = curl_init('https://api.quanticdata.io/v1/scraper/unlock/ca');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],
]);
$raw = curl_exec($ch);
curl_close($ch);
file_put_contents('response.out', $raw);
```

#### Responses

- `200` — PEM certificate (attachment `qp-unlocker-ca.pem`, cacheable 1h).
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `503` — The certificate could not be fetched from the unlocker service right now.

Example `200` response:

```json
"-----BEGIN CERTIFICATE-----\nMIIB…\n-----END CERTIFICATE-----\n"
```

Example `401`:

```json
{
  "type": "error",
  "message": "Missing or invalid Authorization header. Use: Authorization: Bearer qd_live_YOUR_API_KEY"
}
```

Example `429`:

```json
{
  "type": "error",
  "message": "Rate limit exceeded. Resets in 23 minutes.",
  "payload": {
    "rateLimit": 1200,
    "requestCount": 1200,
    "resetAt": "2026-10-07T15:00:00.000Z"
  }
}
```

Example `503`:

```json
{
  "type": "error",
  "message": "Unlocker certificate is temporarily unavailable"
}
```

Try it: https://app.quanticdata.io/data-api/playground

### Price per GB, packs and options on sale

`GET /public/unlock/offer`

**Price:** No charge.  
**Rate limit:** No key and no limit of its own; the answer is cached for 5 minutes.  
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/data-api.md)

What the Web Unlocker sells right now, without a key. `available` says whether it is on sale and its offer is published: while it is `false` the answer holds only `available` and `updated_at`, and the price is on the plans page of the dashboard. `price_per_gb` is the price of 1 GB on each tier, `null` for a tier that is not on sale. `packs_gb` lists the pack sizes and `validity_days` how long a pack lasts. Three switches follow: `pay_per_success`, `free_trial` and `captcha_solver`. The plans page of the dashboard and, when the offer is published, this endpoint are where the price is: these docs do not print it. The numbers in the example below are placeholders (`0`), not prices. The answer is the JSON object itself, without the `type` / `message` / `payload` envelope of the other endpoints. Cached for 5 minutes. Free.

#### Examples

**curl**

```bash
curl -X GET 'https://api.quanticdata.io/v1/public/unlock/offer'
```

**Python (requests)**

```python
import requests

r = requests.get(
    'https://api.quanticdata.io/v1/public/unlock/offer',
    timeout=120,
)
r.raise_for_status()
print(r.json())
```

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/public/unlock/offer", {
  method: "GET"
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
console.log(await res.json());
```

**PHP (curl)**

```php
<?php
$ch = curl_init('https://api.quanticdata.io/v1/public/unlock/offer');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
]);
$raw = curl_exec($ch);
curl_close($ch);
print_r(json_decode($raw, true));
```

#### Responses

- `200` — The current offer.

Example `200` response:

```json
{
  "available": true,
  "currency": "USD",
  "price_per_gb": {
    "premium": 0,
    "mobile": 0
  },
  "packs_gb": [
    1,
    5,
    25,
    100,
    500
  ],
  "validity_days": 30,
  "pay_per_success": false,
  "free_trial": false,
  "captcha_solver": false,
  "updated_at": "2026-11-11T00:00:00.000Z"
}
```

Try it: https://app.quanticdata.io/data-api/playground

### Health of the Web Unlocker from our canary

`GET /public/unlock/status`

**Price:** No charge.  
**Rate limit:** No key and no limit of its own; the answer is cached for 5 minutes.  
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/data-api.md)

The health of the Web Unlocker as our own canary measures it: a scheduled run of real unlock calls against a fixed list of public test targets, grouped by anti-bot system. `state` is `operational` when the latest run is younger than 9 days and its success rate is at least 70 percent, `degraded` when it is younger and below, `unknown` when there is no run or it is older. `canary` is the latest run and `history` the last 12, newest first. Only canary traffic is published, never customer traffic. The answer is the JSON object itself, without the `type` / `message` / `payload` envelope of the other endpoints. The numbers in the example below are those of the canary of 4 November 2026, shown as an example: the endpoint returns the latest run. No key. Cached for 5 minutes. Free.

#### Examples

**curl**

```bash
curl -X GET 'https://api.quanticdata.io/v1/public/unlock/status'
```

**Python (requests)**

```python
import requests

r = requests.get(
    'https://api.quanticdata.io/v1/public/unlock/status',
    timeout=120,
)
r.raise_for_status()
print(r.json())
```

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/public/unlock/status", {
  method: "GET"
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
console.log(await res.json());
```

**PHP (curl)**

```php
<?php
$ch = curl_init('https://api.quanticdata.io/v1/public/unlock/status');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
]);
$raw = curl_exec($ch);
curl_close($ch);
print_r(json_decode($raw, true));
```

#### Responses

- `200` — The current state, the latest canary and the history.

Example `200` response:

```json
{
  "state": "operational",
  "canary": {
    "measuredAt": "2026-11-11",
    "runs": 3,
    "targets": 27,
    "channel": "engine-local",
    "provisional": false,
    "note": "Captcha demo pages (hCaptcha, reCAPTCHA) are run but excluded: interactive captchas are not solved.",
    "summary": {
      "calls": 81,
      "ok": 72,
      "rate": 88.9,
      "p50Ms": 4103,
      "p95Ms": 28793
    },
    "vendors": {
      "datadome": {
        "label": "DataDome",
        "calls": 9,
        "ok": 8,
        "rate": 88.9,
        "p50Ms": 3557,
        "p95Ms": 14903
      }
    }
  },
  "history": [
    {
      "measuredAt": "2026-11-11",
      "calls": 81,
      "ok": 72,
      "rate": 88.9,
      "p50Ms": 4103,
      "p95Ms": 28793
    },
    {
      "measuredAt": "2026-11-04",
      "calls": 51,
      "ok": 43,
      "rate": 84.3,
      "p50Ms": 7212,
      "p95Ms": 35325
    }
  ],
  "updated_at": "2026-11-11T00:00:00.000Z"
}
```

Try it: https://app.quanticdata.io/data-api/playground
