# 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-10-29 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

## 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.

#### 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). Bing/DuckDuckGo never render by default. |
| `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 exit with a real browser fingerprint; prepaid per GB.

The same engine answers in two ways: the REST call below (`POST /scraper/unlock`, API key, JSON in and out) and a **forward proxy** you point an existing HTTP client or scraper at. Both spend the same prepaid Web Unlocker GB, one balance per tier (`premium` = residential exits, `mobile` = mobile exits). The GB are bought on the Web Unlocker tab of the [plans page](https://app.quanticdata.io/plans?network=UNLOCK), paid from the wallet balance, and are separate from the Data API free credit.

Use the REST call when you can change the code that sends the request. Use the forward proxy when the code already speaks to a proxy (host, port, user, password) and should keep working unchanged.

## 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. At most 8 redirects are followed. |

### 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. 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.

### Three ways to send a request

**1. HTTPS target through CONNECT** — the normal proxy setting of any client. The proxy re-issues your request itself, so it terminates TLS with its own certificate: trust the interception CA (`GET /scraper/unlock/ca`) or turn verification off (`curl -k`, `verify=False`).

```bash
curl -x http://unlock.quanticdata.io:9000 -U 'unlock-xxxxxxxxxxxx:PROXY_PASSWORD' \
  --cacert qp-unlocker-ca.pem 'https://example.com/'
```

```python
import requests

proxy = "http://unlock-xxxxxxxxxxxx-country-us:PROXY_PASSWORD@unlock.quanticdata.io:9000"
r = requests.get("https://example.com/", proxies={"http": proxy, "https": proxy}, verify="qp-unlocker-ca.pem")
print(r.status_code, r.headers.get("x-qp-unlocker-attempts"))
```

**2. Direct mode, no certificate** — send the target in `x-qp-url` and address the proxy itself with plain HTTP. The proxy makes the TLS connection to the site, so nothing has to be installed. The method and body of your call are forwarded; `x-qp-method` overrides the method.

```bash
curl -x http://unlock.quanticdata.io:9000 -U 'unlock-xxxxxxxxxxxx:PROXY_PASSWORD' \
  -H 'x-qp-url: https://example.com/api/search' \
  -H 'content-type: application/json' -d '{"q":"shoes"}' http://unlock/
```

**3. Plain-HTTP target** — an absolute-URI request (`GET http://example.com/ HTTP/1.1`), what any client sends for 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: the country of a 2-letter domain ending (`.de`, `.fr`), otherwise 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. 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.

| 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-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 | Run the page in a headless browser (GET/HEAD); false turns the browser off, escalation included. |
| `x-qp-auto-render` (or `x-qp-escalate`) | true/false | Browser escalation of a blocked GET (on by default). |
| `x-qp-success-status` | comma-separated codes, 100 to 599 | Origin statuses relayed as success, never retried. |
| `x-qp-timeout` | milliseconds | Per-attempt timeout at the site. |
| `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:

| Header | Meaning |
|---|---|
| `x-qp-request-id` | Id of this exchange, to quote to support. |
| `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. |
| `x-qp-block-class` | `js_challenge`, `captcha`, `access_denied`, `rate_limited`, `fingerprint`, `geo`, `timeout` or `unknown`. |
| `x-qp-vendor` | Anti-bot vendor, when recognised. |
| `x-qp-hint` | Suggestion when blocked, e.g. try the `mobile` tier. |
| `x-qp-origin-status` | The site's real status, when the proxy changed it (a block page that came back as 2xx/3xx is relayed as 502). |
| `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. |

### Retries and sessions

GET, HEAD and OPTIONS are retried up to three times on a new exit with a different fingerprint, then escalated to a headless browser that can start in parallel. 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.

### Errors from the proxy itself

Errors generated by the proxy (not relayed from the site) are JSON, `{"error":{"code":"…","message":"…"}}`, with the code repeated in the `x-qp-unlocker` header. A CONNECT that is refused gets no body: 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").

| Status | Code | When |
|---|---|---|
| 400 | `bad_target`, `not_a_proxy_request` | Malformed or non-absolute target URL, credentials in the URL, or a request that is neither proxy-shaped nor direct mode. |
| 402 | `no_credit` | The tier has no usable GB: never bought, used up or expired. The message says which and links the plans page. After buying, a cached 402 can last up to 30 seconds. |
| 403 | `target_forbidden`, `target_denied` | Private or internal address, or a destination that is not reachable through the unlocker (banking, payments, login providers, crypto sites). |
| 407 | `proxy_auth_required`, `proxy_auth_invalid` | Missing or wrong proxy user, or a suspended account. Comes with `Proxy-Authenticate: Basic`. |
| 413 | `body_too_large` | Request body over 8 MB. |
| 429 | `rate_limited`, `too_many_connections`, `sensitive_rate_limited`, `auth_rate_limited` | Requests per minute, concurrent connections, non-GET requests to login-like paths, or more than 30 failed logins per minute from one IP. `retry-after` says when to retry. Not billed. |
| 502, 504 | `upstream_failed`, `render_failed` | The site could not be reached in time, or the browser render failed. |
| 503 | `no_exit_pool` | The tier has no exit network for this account (e.g. `tier-mobile` without mobile GB). |

### Billing and limits

Every byte the exit network carries for your request is debited from the tier's 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 responses and failed logins are not billed. 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 connections follow the account's Data API tier (see Rate limits and tiers).

### Replay a request through the Web Unlocker

`POST /scraper/unlock`

**Price:** `unlock_request` $2.40/GB of transferred data. Flat base is 0; the whole charge is the `unlock_request` perGb meter applied to `usage.bytes`, debited from the prepaid unlocker GB of the chosen tier. No wallet charge, no free tier. 402 when the tier has no usable GB (never bought, used up or expired). _(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)

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. GET/HEAD/OPTIONS retry on a fresh exit IP under a different fingerprint when blocked and finally escalate to a headless browser that answers JavaScript challenges; any other method gets exactly one attempt (a response means the target saw it, and replaying a POST could double-submit). A still-blocked page is returned with `blocked: true`, `blockClass` and `vendor`, never as a silent success; `failOnBlock: true` turns that into a 502. It does not solve interactive captchas. This is the same engine as the forward proxy (documented at the top of this section), without the proxy protocol — no certificate to install. 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 escalation's page load.

#### Request body (required)

`Content-Type: application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes |  |
| `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"`. |
| `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 | `html`/`png` (or `true` = html) runs the page in a headless browser instead of the TLS tier, GET/HEAD only, one render token. `false` pins the TLS tier: a blocked page is returned as-is, never escalated. |
| `autoRender` | boolean | no | Escalate a blocked GET to the browser. Default `true`. |
| `keepHeaders` | boolean | no |  Default `false`. |
| `successStatusCodes` | array of integer | no | Origin statuses to accept as success — never treated as a block, never retried. |
| `timeoutMs` | integer | no | Per-attempt timeout at the target (capped by the service's 90 s total budget). |
| `failOnBlock` | boolean | no | 502 instead of a 200 with `blocked: true`. GB are debited either way. Default `false`. |
| `waitForSelector` | string | no | Browser tier: CSS selector to wait for before capture. |
| `waitMs` | integer | no |  |
| `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). |
| `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. |

Example:

```json
{
  "url": "https://example.com/api/search?q=shoes",
  "method": "GET",
  "headers": {
    "Accept": "application/json"
  },
  "country": "us",
  "tier": "premium"
}
```

#### Examples

**curl**

```bash
curl -X POST 'https://api.quanticdata.io/v1/scraper/unlock' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/api/search?q=shoes","method":"GET","headers":{"Accept":"application/json"},"country":"us","tier":"premium"}'
```

**Python (requests)**

```python
import requests

r = requests.post(
    'https://api.quanticdata.io/v1/scraper/unlock',
    headers={"Authorization": "Bearer qd_live_YOUR_API_KEY"},
    json={
        "url": "https://example.com/api/search?q=shoes",
        "method": "GET",
        "headers": {
            "Accept": "application/json"
        },
        "country": "us",
        "tier": "premium"
    },
    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", {
  method: "POST",
  headers: {
    Authorization: "Bearer qd_live_YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "url": "https://example.com/api/search?q=shoes",
    "method": "GET",
    "headers": {
      "Accept": "application/json"
    },
    "country": "us",
    "tier": "premium"
  })
});
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');
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/api/search?q=shoes',
    'method' => 'GET',
    'headers' => [
      'Accept' => 'application/json'
    ],
    'country' => 'us',
    'tier' => 'premium'
  ]),
]);
$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 origin's response (possibly a block page, see `blocked`).
- `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 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.code` is `UNLOCK_NO_CREDIT`, `payload.reason` is `never_bought`, `used_up` or `expired`, and `payload.buy_url` is the same link.
- `403` — No exit pool for the requested tier (e.g. no mobile unlocker GB 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.
- `502` — Only with `failOnBlock: true`: every tier came back blocked. Same diagnostics as the 200 form; the GB moved are debited.
- `503` — The Data API group is switched off for non-admin keys (early-access kill switch).

Example `200` response:

```json
{
  "type": "response",
  "message": "Unlocker request successful",
  "payload": {
    "status": 200,
    "headers": {
      "content-type": "application/json; charset=utf-8",
      "cache-control": "no-store"
    },
    "body": "{\"results\":[{\"id\":1,\"name\":\"Runner\"}]}",
    "bodyBase64": "eyJyZXN1bHRzIjpbeyJpZCI6MSwibmFtZSI6IlJ1bm5lciJ9XX0=",
    "finalUrl": "https://example.com/api/search?q=shoes",
    "contentType": "application/json; charset=utf-8",
    "profile": "chrome",
    "attempts": 1,
    "blocked": false,
    "clearance": "miss",
    "exitSessionId": "s_2f91",
    "strategy": {
      "startTier": "tls",
      "hedged": false
    },
    "rendered": false,
    "escalated": false,
    "tier": "premium",
    "geo": {
      "country": "us",
      "state": null,
      "city": null,
      "rotation": "rotating"
    },
    "usage": {
      "bytes": 18432,
      "unlock_gb_remaining": 4.98,
      "unlock_gb_purchased": 5
    }
  },
  "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": "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": "UNLOCK_NO_CREDIT",
    "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 `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 `502`:

```json
{
  "type": "error",
  "message": "Target blocked the request: js_challenge",
  "payload": {
    "status": 403,
    "blockReason": "js_challenge",
    "blockClass": "js_challenge",
    "vendor": "cloudflare",
    "attempts": 3,
    "rendered": true,
    "escalated": true,
    "usage": {
      "bytes": 90112,
      "unlock_gb_remaining": 4.97,
      "unlock_gb_purchased": 5
    }
  }
}
```

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

### 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 (`curl --proxy-cacert qp-unlocker-ca.pem --cacert qp-unlocker-ca.pem …`). 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
