{
  "openapi": "3.1.0",
  "info": {
    "title": "QuanticData API",
    "version": "2026-11-11",
    "summary": "Scrape, search, crawl, unlock, run collectors and build datasets — one host, one Bearer key, one JSON envelope.",
    "description": "This specification is generated from the application source (route handlers, auth middleware, billing config). Every endpoint answers the same envelope: `{\"type\":\"response\",\"message\":\"…\",\"payload\":{…}}` on success and `{\"type\":\"error\",\"message\":\"…\",\"payload\":{…}}` on failure. Data API calls are pay-per-success: a blocked page, a target 4xx/5xx, a timeout or an error on our side is never charged. The Web Unlocker is the exception: it spends prepaid GB on all the traffic it moves, blocked pages included (see its section). Billed responses carry `payload.usage` (`cost_usd`, `free_usd`, `paid_usd`, `balance`). Prices are referenced by key (`x-price-key`) and resolved from `pricing.json`; rate limits per tier live in `tiers.json`. Brand placeholders (`quanticdata.io`, `QuanticData`) are resolved from `brands.json`.",
    "contact": {
      "name": "QuanticData support",
      "url": "https://quanticdata.io/"
    },
    "termsOfService": "https://quanticdata.io/terms/"
  },
  "servers": [
    {
      "url": "https://api.quanticdata.io/v1",
      "description": "Primary API host. Short aliases (/scrape, /serp, /map, /crawl, /batch, /seo-audit, /serp/bulk and their job ids) are rewritten to the /scraper/* paths at the edge."
    },
    {
      "url": "https://app.quanticdata.io/api/v1",
      "description": "Same API on the dashboard host (no short aliases)."
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Scrape",
      "description": "One URL in, Markdown/HTML/text out, with optional structured and AI extraction."
    },
    {
      "name": "Search",
      "description": "Structured search-engine results (Google, Bing, DuckDuckGo) and async multi-page jobs."
    },
    {
      "name": "Map & Crawl",
      "description": "URL discovery for a whole site and asynchronous site crawls."
    },
    {
      "name": "Batch",
      "description": "Many known URLs scraped asynchronously."
    },
    {
      "name": "Web Unlocker",
      "description": "Replay any HTTP request through a residential or mobile exit under a real browser fingerprint, with retries on fresh exits, a headless browser for JavaScript challenges and one error catalogue; prepaid per GB.\n\nOne engine, three entry points. All three spend the same prepaid Web Unlocker GB, one balance per tier (`premium` = residential exits, `mobile` = mobile exits), bought on the Web Unlocker tab of the [plans page](https://app.quanticdata.io/plans?network=UNLOCK) and paid from the wallet balance, separate from the Data API free credit. Same targeting, same diagnostics, same errors.\n\n### Which endpoint\n\n| Entry point | Use it when | Endpoint |\n|---|---|---|\n| **REST API** | You can change your code: one JSON call in, one JSON answer out, no certificate to install. | `POST https://app.quanticdata.io/api/v1/scraper/unlock` (the same call on the API host: `https://api.quanticdata.io/v1/scraper/unlock`) |\n| **Proxy (CONNECT)** | You already have a scraper that speaks proxy: point it at the host and port with your unlocker user and password, and install the CA once. | `http://unlock.quanticdata.io:9000` |\n| **Direct mode** | Proxy without a certificate: send the request to `http://unlock/` through the proxy and name the target in the `x-qp-url` header. | `http://unlock.quanticdata.io:9000`, then `http://unlock/` |\n\nThe REST call is `POST /scraper/unlock` below. The CA of the proxy is `GET /scraper/unlock/ca` (`https://app.quanticdata.io/api/v1/scraper/unlock/ca`). The [Web Unlocker page](https://app.quanticdata.io/unlock) of the dashboard shows the same three snippets filled with your own key, proxy user and password.\n\nMany URLs at once go through the batch endpoints (see Batch). The price per GB of each tier, the pack sizes and the options that are switched on are published by `GET /public/unlock/offer` once the offer is public (`available: true`); `GET /public/unlock/status` publishes the latest canary run. Neither needs a key.\n\n## Download a client\n\nTwo single-file clients cover the REST call and the batch endpoints. They have no dependency: download the file, put it next to your code and import it.\n\n| Language | File | Needs |\n|---|---|---|\n| Node.js | [unlocker.mjs](https://quanticdata.io/docs/clients/unlocker.mjs) | Node 18 or later |\n| Python | [unlocker.py](https://quanticdata.io/docs/clients/unlocker.py) | Python 3.9 or later |\n\n**Node.js**\n\n```javascript\nimport { Unlocker } from \"./unlocker.mjs\";\n\nconst client = new Unlocker({ apiKey: \"qd_live_YOUR_API_KEY\", retries: 2 });\nconst page = await client.unlock(\"https://example.com/\", { country: \"us\", format: \"markdown\" });\nconsole.log(page.status, page.tier_served, page.cost.bytes);\nconsole.log(page.body.slice(0, 500));\n```\n\n**Python**\n\n```python\nfrom unlocker import Unlocker\n\nclient = Unlocker(api_key=\"qd_live_YOUR_API_KEY\", retries=2)\npage = client.unlock(\"https://example.com/\", country=\"us\", format=\"markdown\")\nprint(page[\"status\"], page[\"tier_served\"], page[\"cost\"][\"bytes\"])\nprint(page[\"body\"][:500])\n```\n\nBoth clients have `unlock(url, options)`, `batch(requests, options)`, `batchStatus(id)` and `batchCancel(id)` (also `batch_status` and `batch_cancel` in Python). Options are the REST fields in snake_case, `actions` and `cache_ttl` included. An error answer raises `UnlockerError` with `code`, `retryable`, `billed`, `hint`, `status` and `request_id`. `retries` (0 to 2, default 0) repeats a call whose error is retryable, after the `Retry-After` pause.\n\n## Forward proxy\n\n| | |\n|---|---|\n| Host | `unlock.quanticdata.io` |\n| Port | `9000` (HTTP proxy) |\n| Authentication | `Proxy-Authorization: Basic` with a **proxy user**: username `unlock-<12 hex>`, 32-character password. Your API key is not accepted by the proxy. |\n| Targets | `http://` and `https://` URLs. HTTP/1.1 inside a CONNECT tunnel. |\n| Limits | Request body up to 8 MB. Text responses up to 5 MB, binary up to 25 MB, or less with `x-qp-max-bytes`. At most 8 redirects are followed. One call, attempts and browser render included, fits in `x-qp-timeout` (default 60 s). |\n\n### Proxy users\n\nCreate, rotate and delete proxy users on the [Web Unlocker page](https://app.quanticdata.io/unlock) of the dashboard, up to 20 per account; a proxy user can be created once the tier has GB. The password is shown when the user is created or rotated. The proxy caches a successful login for 60 seconds, so a rotated or deleted password can keep working for up to a minute. The same page builds ready-made proxy strings with the targeting below.\n\n### Proxy (CONNECT)\n\nThe normal proxy setting of any HTTP client. The proxy re-issues your request itself, so it terminates TLS with its own certificate: download the CA once (`GET /scraper/unlock/ca`, saved as `unlocker-ca.pem` below) and trust it for the target host, or turn verification off (`curl -k`, `verify=False`).\n\n<!-- unlocker-snippets:proxy -->\n**curl**\n\n```bash\n# once: curl -o unlocker-ca.pem https://app.quanticdata.io/api/v1/scraper/unlock/ca\ncurl --proxy http://unlock.quanticdata.io:9000 \\\n  --proxy-user \"USER:PASS\" \\\n  --cacert unlocker-ca.pem \\\n  https://example.com/\n```\n\n**Python (requests)**\n\n```python\nimport requests\n\n# once: download https://app.quanticdata.io/api/v1/scraper/unlock/ca as unlocker-ca.pem\nproxy = \"http://USER:PASS@unlock.quanticdata.io:9000\"\nr = requests.get(\n    \"https://example.com/\",\n    proxies={\"http\": proxy, \"https\": proxy},\n    verify=\"unlocker-ca.pem\",\n    timeout=130,\n)\nprint(r.status_code, r.headers.get(\"x-qp-unlocker-blocked\", \"ok\"), r.headers.get(\"x-qp-unlocker-attempts\"))\nprint(r.text[:500])\n```\n\n**Node (undici)**\n\n```javascript\nimport { fetch, ProxyAgent } from \"undici\";\nimport { readFileSync } from \"node:fs\";\n\n// once: download https://app.quanticdata.io/api/v1/scraper/unlock/ca as unlocker-ca.pem\nconst dispatcher = new ProxyAgent({\n  uri: \"http://unlock.quanticdata.io:9000\",\n  token: \"Basic \" + Buffer.from(\"USER:PASS\").toString(\"base64\"),\n  requestTls: { ca: readFileSync(\"unlocker-ca.pem\") },\n});\nconst res = await fetch(\"https://example.com/\", { dispatcher });\nconsole.log(res.status, res.headers.get(\"x-qp-unlocker-blocked\") ?? \"ok\", res.headers.get(\"x-qp-unlocker-attempts\"));\nconsole.log((await res.text()).slice(0, 500));\n```\n\n**PHP (curl)**\n\n```php\n<?php\n// once: download https://app.quanticdata.io/api/v1/scraper/unlock/ca as unlocker-ca.pem\n$ch = curl_init(\"https://example.com/\");\ncurl_setopt_array($ch, [\n  CURLOPT_PROXY => \"http://unlock.quanticdata.io:9000\",\n  CURLOPT_PROXYUSERPWD => \"USER:PASS\",\n  CURLOPT_CAINFO => \"unlocker-ca.pem\",\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_TIMEOUT => 130,\n]);\n$html = curl_exec($ch);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), \"\\n\", substr($html, 0, 500);\n```\n\n**Go**\n\n```go\npackage main\n\nimport (\n\t\"crypto/tls\"\n\t\"crypto/x509\"\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"net/url\"\n\t\"os\"\n)\n\nfunc main() {\n\t// once: download https://app.quanticdata.io/api/v1/scraper/unlock/ca as unlocker-ca.pem\n\tca, _ := os.ReadFile(\"unlocker-ca.pem\")\n\tpool := x509.NewCertPool()\n\tpool.AppendCertsFromPEM(ca)\n\tproxy, _ := url.Parse(\"http://USER:PASS@unlock.quanticdata.io:9000\")\n\tclient := &http.Client{Transport: &http.Transport{Proxy: http.ProxyURL(proxy), TLSClientConfig: &tls.Config{RootCAs: pool}}}\n\tres, err := client.Get(\"https://example.com/\")\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tbody, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.StatusCode, res.Header.Get(\"x-qp-unlocker-blocked\"), res.Header.Get(\"x-qp-unlocker-attempts\"), len(body))\n}\n```\n<!-- /unlocker-snippets:proxy -->\n\n### Direct mode\n\nNothing to install: address the proxy itself with plain HTTP at `http://unlock/` and put the target in `x-qp-url`. The proxy makes the TLS connection to the site. The method and body of your call are forwarded; `x-qp-method` overrides the method.\n\n<!-- unlocker-snippets:direct -->\n**curl**\n\n```bash\ncurl --proxy http://unlock.quanticdata.io:9000 \\\n  --proxy-user \"USER:PASS\" \\\n  -H \"x-qp-url: https://example.com/\" \\\n  http://unlock/\n```\n\n**Python (requests)**\n\n```python\nimport requests\n\nproxy = \"http://USER:PASS@unlock.quanticdata.io:9000\"\nr = requests.get(\n    \"http://unlock/\",\n    proxies={\"http\": proxy},\n    headers={\"x-qp-url\": \"https://example.com/\"},\n    timeout=130,\n)\nprint(r.status_code, r.headers.get(\"x-qp-unlocker-blocked\", \"ok\"), r.headers.get(\"x-qp-unlocker-attempts\"))\nprint(r.text[:500])\n```\n\n**Node (undici)**\n\n```javascript\nimport { fetch, ProxyAgent } from \"undici\";\n\nconst dispatcher = new ProxyAgent({\n  uri: \"http://unlock.quanticdata.io:9000\",\n  token: \"Basic \" + Buffer.from(\"USER:PASS\").toString(\"base64\"),\n});\nconst res = await fetch(\"http://unlock/\", { dispatcher, headers: { \"x-qp-url\": \"https://example.com/\" } });\nconsole.log(res.status, res.headers.get(\"x-qp-unlocker-blocked\") ?? \"ok\", res.headers.get(\"x-qp-unlocker-attempts\"));\nconsole.log((await res.text()).slice(0, 500));\n```\n\n**PHP (curl)**\n\n```php\n<?php\n$ch = curl_init(\"http://unlock/\");\ncurl_setopt_array($ch, [\n  CURLOPT_PROXY => \"http://unlock.quanticdata.io:9000\",\n  CURLOPT_PROXYUSERPWD => \"USER:PASS\",\n  CURLOPT_HTTPHEADER => [\"x-qp-url: https://example.com/\"],\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_TIMEOUT => 130,\n]);\n$html = curl_exec($ch);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), \"\\n\", substr($html, 0, 500);\n```\n\n**Go**\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"net/url\"\n)\n\nfunc main() {\n\tproxy, _ := url.Parse(\"http://USER:PASS@unlock.quanticdata.io:9000\")\n\tclient := &http.Client{Transport: &http.Transport{Proxy: http.ProxyURL(proxy)}}\n\treq, _ := http.NewRequest(\"GET\", \"http://unlock/\", nil)\n\treq.Header.Set(\"x-qp-url\", \"https://example.com/\")\n\tres, err := client.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tbody, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.StatusCode, res.Header.Get(\"x-qp-unlocker-blocked\"), res.Header.Get(\"x-qp-unlocker-attempts\"), len(body))\n}\n```\n<!-- /unlocker-snippets:direct -->\n\nA plain `http://` target works through the proxy as well, as an absolute-URI request (`GET http://example.com/ HTTP/1.1`), the way any client sends an `http://` URL through a proxy; no certificate involved.\n\n### Targeting in the username\n\nAppend options to the proxy user, each as `-name-value`: `unlock-xxxxxxxxxxxx-country-us-session-abc123-ttl-30`. Unknown options are ignored.\n\n| Option | Values | Effect |\n|---|---|---|\n| `country-xx` | 2-letter country code | Exit country. Without it, in order: the site's own country from its ccTLD (`.de`, `.fr`), then the country of your account, then US. |\n| `state-<slug>`, `city-<slug>` | letters, digits, `_` (up to 32) | Exit region and city, e.g. `-state-new_york-city-new_york`. |\n| `session-<id>` (or `sid-<id>`) | letters and digits (up to 32) | Keeps the same exit IP across requests and connections. |\n| `ttl-<minutes>` | 3 to 1440 | How long that session's exit is kept; only together with `session`. |\n| `profile-<name>` | `chrome` (default), `firefox`, `safari`, `safari_ios`, `edge`, `brave`, `mobile` | Browser fingerprint. Other values fall back to the default. |\n| `mobile` | — | Mobile browser fingerprint on the same exits. It does not switch to the mobile network. |\n| `tier-<name>` | `premium` (default), `mobile` | Product: exit network and GB balance the request is billed on. |\n| `policy-<name>` | `browser` (default), `passthrough` | `passthrough` sends your own identity headers instead of the fingerprint's. |\n\n### Control headers\n\nOptional request headers, read by the proxy and removed before the request reaches the site (any other header, including other `x-qp-*` names, is forwarded). They work on every way of sending a request, inside a CONNECT tunnel too, and mirror the fields of the REST call. True values: `1`, `true`, `yes`, `on`; false: `0`, `false`, `no`, `off`, `none` or empty. An invalid value is ignored and reported in `x-qp-warning`. The header names used by other unlocker services for the same options are accepted as aliases, so existing code keeps working: they are listed under Coming from another unlocker.\n\n| Header | Values | Effect |\n|---|---|---|\n| `x-qp-url` | absolute `http(s)` URL | Target in direct mode; wins over the request line. |\n| `x-qp-method` | HTTP verb | Method sent to the site. |\n| `x-qp-mode` | `auto` (default), `tls`, `browser` | Same as `mode` of the REST call: `auto` climbs from the TLS tier to the browser when blocked, `tls` never opens the browser, `browser` renders straight away. |\n| `x-qp-max-bytes` | integer, at least 1024 | Same as `max_bytes`: cap on the bytes this call may move; over it the answer is 403 `max_bytes_exceeded`. |\n| `x-qp-fail-on-block` | true/false | Same as `fail_on_block`: a refusal the site sent under its own status (403, 429, 503) answers 424 `target_blocked` instead of being relayed; a block page served as 2xx/3xx is 424 anyway (see Blocked pages). |\n| `x-qp-timeout` | milliseconds, 1000 to 120000 | Same as `timeout_ms`: total budget of the call (default 60000), attempts and browser render included. |\n| `x-qp-cache-ttl` | seconds, 0 to 86400 | Same as `cache_ttl`: an identical GET is answered from a stored copy younger than this (see Cache). 0 or absent: no cache. |\n| `x-qp-country` (or `x-qp-geo`) | 2-letter code | Exit country for this request. |\n| `x-qp-session` (or `x-qp-session-id`) | letters and digits (up to 32) | Exit session for this request. |\n| `x-qp-rotation` | `sticky`, `rotating` | Session behaviour. |\n| `x-qp-profile` (or `x-qp-tls-profile`) | profile name | Browser fingerprint. |\n| `x-qp-keep-headers` | true/false | Send your own identity headers verbatim. |\n| `x-qp-render` | `html` or true, `png`, false | `html`/true is `x-qp-mode: browser`; `png` returns a screenshot (GET/HEAD); false is `x-qp-mode: tls`. |\n| `x-qp-auto-render` (or `x-qp-escalate`) | true/false | Deprecated, use `x-qp-mode`: false is `tls`, true is `auto`. |\n| `x-qp-success-status` | comma-separated codes, 100 to 599 | Origin statuses relayed as success, never retried. |\n| `x-qp-wait-for` (or `x-qp-wait-for-selector`) | CSS selector (up to 256) | Browser waits for this element before capturing. |\n| `x-qp-wait-ms` (or `x-qp-wait`) | 0 to 15000 | Extra settle time in the browser. |\n| `x-qp-return-cookies` | true | Return the site's cookie jar in `x-qp-cookies`. |\n\n### Response headers\n\nThe site's status, headers and body are relayed (the body decompressed, `Set-Cookie` lines from every redirect kept), plus the same diagnostics the REST payload carries:\n\n| Header | Meaning |\n|---|---|\n| `x-qp-request-id` | Id of this exchange (`request_id` of the REST payload), to quote to support. |\n| `x-qp-latency-ms` | Milliseconds from your request to the answer (`latency_ms`). |\n| `x-qp-tier-served` | `tls` or `browser`: the tier that produced the answer (`tier_served`). |\n| `x-qp-cost-bytes`, `x-qp-cost-usd` | Bytes moved for this call and what they cost at your tier's price per GB (`cost.bytes`, `cost.usd`). |\n| `x-qp-attempt-log` | `attempt_log` as URL-encoded JSON: one entry per attempt with tier, profile, exit country, outcome, ms and bytes. |\n| `x-qp-cache`, `x-qp-cached-at` | `hit`, `miss` or `off` (`cache` of the REST payload) and, on a hit, when the copy was stored (`cached_at`). |\n| `x-qp-unlocker-attempts` | Attempts across every tier. |\n| `x-qp-unlocker-profile` | Fingerprint that served the response. |\n| `x-qp-session` | Exit session used. |\n| `x-qp-country` | Exit country used. |\n| `x-qp-final-url` | URL after redirects. |\n| `x-qp-unlocker-rendered`, `x-qp-unlocker-escalated` | `1` when the headless browser served it, or was reached by escalation. |\n| `x-qp-clearance` | `hit`, `miss`, `minted`, `stale` or `off`. |\n| `x-qp-unlocker-blocked` | Block reason, when every attempt came back blocked (the status depends on how the site served the block, see Blocked pages). |\n| `x-qp-block-class` | `js_challenge`, `captcha`, `access_denied`, `rate_limited`, `fingerprint`, `geo`, `timeout` or `unknown`. |\n| `x-qp-vendor` | Anti-bot system, when recognised. |\n| `x-qp-hint` | Suggestion when blocked, e.g. try the `mobile` tier. |\n| `x-qp-origin-status` | The status the site really sent, when the proxy answered 424 `target_blocked` instead: a block page served as 2xx/3xx, or a refusal turned into 424 by `x-qp-fail-on-block`. |\n| `x-qp-cookies` | URL-encoded JSON cookie jar, with `x-qp-return-cookies`. |\n| `x-qp-ratelimit-limit`, `x-qp-ratelimit-remaining` | Requests per minute and what is left. |\n| `x-qp-warning` | A control header or option that was ignored, and why. |\n\n### Modes, retries and sessions\n\nIn `auto` mode (the default) a GET, HEAD or OPTIONS is retried up to three times on a new exit with a different fingerprint, then escalated to a headless browser that can start in parallel when the first attempts come back blocked; `tier_served` (or `x-qp-tier-served`) says which tier produced the answer. `tls` never opens the browser and returns the block page as-is; `browser` renders straight away. Everything fits in the call's total budget (`timeout_ms` / `x-qp-timeout`, default 60 s): a budget that runs out is a 504 `timeout`. Any other method gets exactly one attempt and no browser fallback: a response means the site saw the request, and replaying a POST could submit it twice. With a `session` in the username the exit cannot change, so there is one normal attempt; the browser fallback still runs.\n\n### Browser actions\n\n`actions` (REST call only) is an ordered list of up to 20 interactions the browser runs before the page is captured: click an element or a text, type into a field, scroll, wait. Actions force the browser tier, so they work on GET and HEAD only, and `mode: \"tls\"` together with `actions` is a 400 `bad_request`. The shapes are listed in the request body of `POST /scraper/unlock`. An action that cannot run ends the call with 422 `action_failed`, and the message names it: `Action 2 failed ({\"waitForSelector\":\".results\"}): nothing on the page matched it within 15000 ms`. An action marked `optional: true` is skipped instead, and the call goes on.\n\n### Cache\n\n`cache_ttl` (REST) or `x-qp-cache-ttl` (proxy) is a number of seconds from 0 to 86400; 0, the default, is off. A GET that the site answered 2xx and that was not blocked is kept for your account for that long. A later call with the same URL, mode, format, country, tier, render kind and actions is answered from the copy. That answer says `cache: \"hit\"` and `cached_at` (`x-qp-cache` and `x-qp-cached-at` on the proxy), with `attempts: 0` and one `attempt_log` entry of tier `cache`; `tier_served` is the tier that produced the stored page. A hit moves no bytes and costs nothing: `cost` is `{\"bytes\": 0, \"usd\": 0, \"billed\": false}`. The cache is best effort: a copy can be dropped before its time, and a page over 5 MB is not kept.\n\n### Billing and limits\n\nThe price per GB of each tier is on the [plans page](https://app.quanticdata.io/plans?network=UNLOCK) of the dashboard and, when the offer is published, in `GET /public/unlock/offer`. Every byte the exit network carries for your request is debited from the tier's prepaid GB: retries, blocked pages, failed attempts and the browser's page load included (request bodies and response bodies; headers are not counted). 1 GB = 10^9 bytes. 429 answers and requests refused before they ran are not billed, and a cache hit moves no bytes. When `pay_per_success` of `GET /public/unlock/offer` is true, a blocked page or a failed call debits nothing on the REST call and in a batch; the forward proxy is metered on every byte either way. `max_bytes` / `x-qp-max-bytes` caps what one call may move. The balance is checked when the proxy logs you in, so a session can run for up to a minute past the end of the GB. Requests per minute and concurrent requests follow the account's Data API tier (see Rate limits and tiers).\n\n## Batch\n\nUp to 100 URLs in one asynchronous job. `POST /scraper/unlock/batch` takes the list and answers 202 with a `batch_id` at once. `GET /scraper/unlock/batch/{batch_id}` returns the progress and one result per item. `DELETE /scraper/unlock/batch/{batch_id}` cancels the items that have not started. Each item is a REST call: any field of `POST /scraper/unlock` can be set per item, or once for all of them in `defaults`. `concurrency` (1 to 5, default 3) is how many items run at the same time. With `webhook_url` the finished batch is also sent to your server in one POST. Results are kept for one hour after the batch ends.\n\nBilling: a batch spends the same prepaid GB, and every item is metered like a single call. The tier needs usable GB when the batch starts, otherwise the answer is 402 `no_credit`.\n\n## Errors\n\nOne catalogue for the REST call and the proxy. A REST error is the usual envelope, `{\"type\":\"error\",\"message\":\"…\",\"payload\":{…}}`, where `payload` carries `code`, `retryable`, `billed`, `hint` and `doc_url` (this section) plus the details named below; the code is repeated in the `x-qp-unlocker` header and retryable answers carry `Retry-After` with a suggested pause. The proxy answers the same status and JSON body with the same headers; a CONNECT that is refused gets no body, only the status line plus `X-Qp-Unlocker` (code) and, for 402, `X-Qp-Unlocker-Message` (curl prints \"Received HTTP code 402 from proxy after CONNECT\").\n\n### Unlock errors\n\n| Code | HTTP | Retryable | Billed | When | What to do |\n|---|---|---|---|---|---|\n| `bad_request` | 400 | no | no | A parameter is invalid; `message` names it and the rule it broke. | Fix the parameter named in the message and send the request again. |\n| `unauthorized` | 401 | no | no | API key missing, wrong or disabled. On the proxy: 407 with `Proxy-Authenticate: Basic`, only for a missing or wrong proxy user. | Use the API key from the dashboard (REST) or the unlocker proxy user and password (proxy). |\n| `no_credit` | 402 | no | no | The tier has no usable GB: never bought, used up or expired. `payload.reason` says which; `payload.buy_url` is the page to buy GB. | Buy GB from the dashboard, then retry with the same key or proxy user. |\n| `target_forbidden` | 403 | no | no | Private, reserved or internal address. | The unlocker only fetches public hosts. |\n| `target_denied` | 403 | no | no | A destination the unlocker does not serve (banking, payments, login providers, crypto sites). | Pick another target; this one is on the deny list. |\n| `no_exit_pool` | 403 | no | no | The account has no exit pool for the tier (e.g. `mobile` without a mobile sub-user); `payload.tier` names it. On the proxy the same answer is 503 (see Proxy-only answers). | Buy GB on that tier so its pool is set up, or use `tier: \"premium\"`; retry once the pool exists. |\n| `max_bytes_exceeded` | 403 | no | yes | The bytes moved went over `max_bytes`; `payload.usage` and `payload.cost` say how many. | Raise `max_bytes`, or leave it out to accept the full page. |\n| `action_failed` | 422 | no | no | REST call with `actions`: the page loaded but one of the actions could not run, for example its selector matched nothing in time. `message` names the action by its position and shape and says why. | Check the selector or the text of that action, or mark it `optional` if the page may not have it. |\n| `target_blocked` | 424 | yes | yes | The target refused every attempt and you asked `fail_on_block` (REST) or `x-qp-fail-on-block` (proxy), or, on the proxy, the site served its block page under a 2xx/3xx status; `payload` carries `status`, `blockReason`, `blockClass`, `vendor`, `attempts`, `attempt_log`, `usage` and `cost`. | Retry with `mode: \"browser\"`, another country, or a sticky session; drop `fail_on_block` to receive the blocked page as a 200. |\n| `rate_limited` | 429 | yes | no | Requests per minute or concurrent requests of the account's tier. | Wait for `Retry-After` seconds, lower your concurrency, or move to a plan with a higher limit. |\n| `render_failed` | 503 | yes | no | The browser could not load the page. | Retry; if it keeps failing use `mode: \"tls\"` or a longer `timeout_ms`. |\n| `upstream_failed` | 503 | yes | no | The exit or the target could not be reached. | Retry: the next attempt runs on a fresh exit. |\n| `service_unavailable` | 503 | yes | no | The engine or the API is not answering (on the proxy: 503, never 407). | Retry in a few seconds. |\n| `timeout` | 504 | yes | no | `timeout_ms` ran out before a response. | Raise `timeout_ms` (up to 120000) or use `mode: \"tls\"` for a faster first answer. |\n| `internal_error` | 500 | yes | no | An error on our side. | Retry; if it persists contact support with the `request_id`. |\n\n### Proxy-only answers\n\nAnswers only the forward proxy gives (the REST call has no equivalent), same JSON body and `x-qp-unlocker` header as the catalogue:\n\n| Code | HTTP | Retryable | Billed | When |\n|---|---|---|---|---|\n| `proxy_auth_required` | 407 | no | no | No `Proxy-Authorization` header. Comes with `Proxy-Authenticate: Basic realm=\"Web Unlocker\"`. |\n| `proxy_auth_invalid` | 407 | no | no | Wrong proxy user or password. |\n| `not_a_proxy_request` | 400 | no | no | A request that is neither proxy-shaped (CONNECT, or an absolute URI) nor direct mode (`x-qp-url`). |\n| `body_too_large` | 413 | no | no | Request body over 8 MB. |\n| `too_many_connections` | 429 | yes | no | More concurrent connections than the account's tier allows; `Retry-After` says when to retry. |\n| `sensitive_rate_limited` | 429 | yes | no | Non-GET requests to login-like paths over the limit; `Retry-After`. |\n| `auth_rate_limited` | 429 | yes | no | More than 30 failed logins per minute from one IP; `Retry-After`. |\n| `no_exit_pool` | 503 | no, until a pool exists | no | The account has no exit pool for the tier (e.g. `tier-mobile` without a mobile sub-user). The REST call answers 403 `no_exit_pool` for the same situation. |\n\n### Blocked pages\n\nOn the REST call a page that is still blocked after every attempt is not an error unless you ask for one: the answer is 200 with `blocked: true`, `blockClass`, `vendor` and `hint`, and the block page is in `body` for inspection; `fail_on_block: true` turns it into 424 `target_blocked`. On the proxy the answer depends on how the site served the block. A block page the site served under a 2xx/3xx status is answered 424 `target_blocked` straight away, with the site's body and the headers `x-qp-unlocker: target_blocked`, `x-qp-origin-status` (the status the site sent), `x-qp-unlocker-blocked`, `x-qp-block-class` and `x-qp-vendor`. A refusal the site sent under its own status (403, 429, 503) is relayed with that status and the same diagnostic headers, and becomes 424 only with `x-qp-fail-on-block: 1`. Captchas: when the service has the captcha solver enabled (`captcha_solver` of `GET /public/unlock/offer`), DataDome and AWS WAF challenges are handed to it, and `attempt_log` shows that step as a `solver` entry. Any other interactive captcha is returned as `blockClass: \"captcha\"`.\n\n### Reading a block: vendor and blockClass\n\nWhen an attempt meets a wall, the engine names the system it recognised in `vendor` and the kind of stop in `blockClass`. Both are on the REST answer when `blocked` is `true`, on the entries of `attempt_log`, on each result of a batch, and on the proxy as the headers `x-qp-vendor` and `x-qp-block-class`.\n\n| `vendor` | System | What the block of that system looks like |\n| --- | --- | --- |\n| `cloudflare` | Cloudflare | 403 with \"Just a moment...\" and the header `cf-mitigated: challenge`; errors 1020, 1015, 1010, 1009 |\n| `datadome` | DataDome | 403 with \"Please enable JS and disable any ad blocker\" and a script from `captcha-delivery.com` |\n| `akamai` | Akamai Bot Manager | 403 \"Access Denied ... Reference #18...\" |\n| `perimeterx` | PerimeterX (HUMAN) | 403 with \"Press & Hold to confirm you are a human\"; on API calls a JSON body with `appId` |\n| `kasada` | Kasada | 429 on the first request, with an almost empty page that loads `ips.js` |\n| `imperva` | Imperva (Incapsula) | \"Pardon Our Interruption\" or \"Request unsuccessful. Incapsula incident ID\", often with status 200 |\n| `shape` | F5 (BIG-IP, Shape) | \"Request Rejected ... Your support ID is\", often with status 200 |\n| `awswaf` | AWS WAF | 202 (Challenge) or 405 (CAPTCHA), with the header `x-amzn-waf-action` |\n| `amazon`, `google`, `reddit`, `yandex` | The site's own wall | The page that site shows to automated traffic |\n| `hcaptcha`, `recaptcha` | A captcha widget | An interactive captcha on the page |\n| `unknown` | Not recognised | Read `blockReason` and the body |\n\n| `blockClass` | What stopped the call | What to do |\n| --- | --- | --- |\n| `js_challenge` | A check that a real browser clears by running a script | Leave `mode` on `auto`, or use `browser`. With `mode: \"tls\"` no browser is opened |\n| `captcha` | The page asks a person: a puzzle, a slider, press and hold | Retry later or from another `country`. See the captcha rule above |\n| `access_denied` | A flat refusal, with no challenge offered | Retry; try another `country` or the mobile tier |\n| `rate_limited` | A plain 429 | Slow down or spread the calls. Do not pin one session |\n| `fingerprint` | The client itself was judged automated | Leave `mode` on `auto`: the browser tier is the next step |\n| `geo` | The site does not serve the country of the exit | Set `country` to one the site serves |\n| `timeout` | The site or the exit never answered | Retry |\n| `unknown` | Not classified | Read `blockReason` and the body |\n\nTwo things worth knowing when you read the answer:\n\n- The status code of the site is not proof. Imperva and F5 often serve their block page with status 200, and Kasada answers a new visitor with 429 before any rate was exceeded. `blocked` is the field to trust; `fail_on_block: true` turns a blocked answer into 424 `target_blocked`.\n- `clearance` says what happened to the session of that site. `minted`: this call passed the site's check and the session was kept. `hit`: this call reused a kept session, so no new check was run. `stale`: a kept session was refused and dropped. `miss`: there was none. The first call to a protected site is the slow one; the next calls from the same account reuse the session until the site asks again.\n\n<!-- other-unlockers -->\n\n## Coming from another unlocker\n\nCode written for another unlocker needs a new host, port and credentials. After that, most options keep working or need one rename: the proxy already reads several header names such code sends, and the rest map one to one to ours.\n\n### Our names\n\n| Option | REST field | Proxy header | Proxy username |\n|---|---|---|---|\n| Country | `country` | `x-qp-country` | `-country-xx` |\n| Session | `session_id` | `x-qp-session` | `-session-<id>` |\n| Render | `mode: \"browser\"`; `render: \"png\"` for a screenshot | `x-qp-mode: browser`; `x-qp-render: png` |  |\n| Device | `mobile: true` or `tls_profile` | `x-qp-profile` | `-mobile`, `-profile-<name>` |\n| Custom success codes | `success_status_codes` | `x-qp-success-status` |  |\n| Markdown | `format: \"markdown\"` |  |  |\n| Wait for an element | `wait_for_selector` | `x-qp-wait-for` |  |\n| Timeout | `timeout_ms` | `x-qp-timeout` |  |\n\n### Names the proxy reads unchanged\n\nA request that already carries one of these needs no change for that option. The `-country-xx` suffix of the proxy username is read as it is too.\n\n| Option | Our header | Also read |\n|---|---|---|\n| Country | `x-qp-country` | `x-oxylabs-geo-location`, `x-brd-country`, `x-unblock-country` |\n| Session | `x-qp-session` | `x-oxylabs-session-id`, `x-brd-session`, `x-unblock-session` |\n| Render | `x-qp-render` | `x-oxylabs-render`, `x-brd-render`, `x-unblock-render` |\n| Custom success codes | `x-qp-success-status` | `x-oxylabs-successful-status-codes`, `x-unblock-success-status` |\n| Own headers sent as they are | `x-qp-keep-headers` | `x-oxylabs-force-headers`, `x-unblock-keep-headers` |\n| Target URL in direct mode | `x-qp-url` | `x-oxylabs-url`, `x-brd-url`, `x-unblock-url` |\n\nThe country value must be a 2-letter code: a value such as `City,State,US` is reduced to `us`, and a country name is ignored and reported in `x-qp-warning`.\n\n### Names to rename\n\nThese are not read: replace each with ours.\n\n| Option | A name your code may send | Ours |\n|---|---|---|\n| Country | `X-SU-Geo` | `x-qp-country`, `country` |\n| Session | `X-SU-Session-Id` | `x-qp-session`, `session_id` |\n| Render | `-render` in the proxy username; `X-SU-Headless: html` or `png` | `x-qp-mode: browser` or `x-qp-render: png`; `mode: \"browser\"`, `render: \"png\"` |\n| Device | `-ua-mobile` in the proxy username; `X-SU-Device-Type: mobile` | `-mobile` in the proxy username, `x-qp-profile: mobile`, `mobile: true` |\n| Custom success codes | `X-SU-Status-Code` | `x-qp-success-status`, `success_status_codes` |\n| Markdown | `x-unblock-data-format: markdown`; `data_format` in a REST body; `X-SU-Markdown` | `format: \"markdown\"` on the REST call |\n| Wait for an element | `x-unblock-expect`; `wait_for_element` in `x-oxylabs-browser-instructions` | `x-qp-wait-for`, `wait_for_selector`; other steps go in `actions` on the REST call |\n\n<!-- /other-unlockers -->"
    },
    {
      "name": "AI extraction",
      "description": "Natural-language agents that drive the scraper and return JSON."
    },
    {
      "name": "AI visibility",
      "description": "Can AI assistants read and cite a page?"
    },
    {
      "name": "SEO audit",
      "description": "No-JS vs rendered view of a page and the diff between them."
    },
    {
      "name": "Collectors",
      "description": "Ready-made, versioned scrapers on a semantic input; billed per delivered row. The catalog is dynamic: read it from GET /scraper/collectors."
    },
    {
      "name": "Datasets",
      "description": "Prompt-driven dataset builder: one prompt, a validated table."
    },
    {
      "name": "Parser presets",
      "description": "Generate CSS selectors once with an LLM, replay them for free, let them self-heal."
    },
    {
      "name": "Proxies",
      "description": "List your proxy plans, generate endpoint strings, manage IP whitelists, and get a new IP on demand. Limits: `generate` returns 1 to 10000 lines per call; the number of whitelisted IPs per plan is the plan's `whitelistSlots`; `ip-info` answers from a 24-hour cache per IP, and new lookups share a daily cap (503 with `Retry-After` when it is reached). Every call also counts in the hourly window of your API key (see Rate limits and tiers).\n\n**New IP on demand.** A rotating string changes IP on every request. A sticky string keeps one IP for its session (`sessionTime` in `generate`). On Residential Basic and Datacenter traffic plans you can restart a sticky session at any time: the same string leaves from a new IP on its next request, so a saved anti-detect profile or a script keeps its proxy settings. Call `POST /public/proxies/{orderId}/rotate` with your API key, or create a rotation link: a URL with no key and no header that anti-detect browsers and scripts can call directly.\n\n| Plan type (`planType`) | Rotating strings | Sticky strings | New IP on demand |\n|---|---|---|---|\n| `residentialbasic`, `datacentertraffic` | New IP per request | Same IP for `sessionTime` | `rotate` or a rotation link: same string, new IP |\n| `residentialpremium`, `resiprivate`, `mobile_v2`, `mobile`, `ipv6` | New IP per request | Same IP for `sessionTime` | Request a new sticky string with `generate` |\n| `datacenter` | Assigned by the gateway | Assigned by the gateway | Not applicable |\n| `isp`, `isppremium` | Static IPs | Static IPs | Not applicable: dedicated static IPs |\n\n**Super sticky and UDP.** On Residential Premium and Mobile, `superSticky: true` in `generate` keeps one IP per string for up to 24 hours (it is `sessionTime: 1440`). On Residential Basic, `udp: true` with `protocol: \"socks5\"` adds UDP relay (SOCKS5 UDP ASSOCIATE) to the strings, rotating or sticky.\n\nBuild proxy strings with `generate` and use them as returned; do not edit them by hand."
    },
    {
      "name": "Premium ISP",
      "description": "Buy and manage Premium ISP dedicated IPs through the API, paid from the wallet balance: ready pools by country and category, or city plans where you pick the city and, optionally, the carrier (ASN). Catalog with live stock, quote, purchase, order status with the proxy lines, renewal and paid IP swaps."
    },
    {
      "name": "IPv6",
      "description": "Buy IPv6 speed plans through the API, paid from the wallet balance: traffic is not metered, the port speed is the cap. The grid of speeds (Mbps) and terms (1, 7 or 30 days) with the price of every cell, a quote, the purchase with an Idempotency-Key, order status. The endpoint strings of a bought plan come from `POST /public/proxies/generate` with the order id; per-GB IPv6 packs stay in `GET /public/plans` and `POST /public/purchase`. 1000 Mbps is a special plan sold on request (dashboard, Plans → IPv6 → Contact us)."
    },
    {
      "name": "Account",
      "description": "Usage, billing status and platform settings."
    },
    {
      "name": "Plans & orders",
      "description": "Buy proxy plans from the wallet balance and read your orders, so a script or an agent can go from API key to working proxies without the dashboard: `GET /public/plans` → `POST /public/purchase` → `POST /public/proxies/generate` with the order id (step by step in the guide Buy and use proxies via the API). Purchases are paid from the balance only, with 0% VAT; the balance is topped up in the dashboard. The plans listed here have a fixed size (GB and days). Products you configure at checkout, such as ISP proxies or unlimited-bandwidth plans, are bought in the dashboard, and Premium ISP has its own endpoints (see Premium ISP). Buying a plan again creates a separate order with new credentials: adding GB to an existing plan or renewing it is done in the dashboard."
    },
    {
      "name": "Proxy locations",
      "description": "The values `POST /public/proxies/generate` accepts as `country`, `state` (alias `region`), `city`, `isp` and `asn`. Which endpoint to read depends on the plan type:\n\n| Plan type | Location values |\n| --- | --- |\n| `residentialpremium` | `GET /public/generator/residential-premium/targeting-options`: the whole tree (country, region, city, ISP) in one call |\n| `mobile_v2` | `GET /public/generator/mobile/targeting-options`: the whole tree (country, region, city, carrier) in one call |\n| `residentialbasic`, `datacentertraffic` | `GET /public/geo/countries`, `/geo/states`, `/geo/cities` and `/geo/asns`, one level per call (needs one of these plans on the account) |\n| `ipv6` | `GET /public/geo/countries?planType=ipv6` |\n| `datacenter` (static gateways) | `GET /public/generator/datacenter/targeting-options`: the gateway hosts and ports |\n\nLocations follow the network and change over time: read them when you build a request instead of keeping a copy for months. All free."
    },
    {
      "name": "Video",
      "description": "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."
    },
    {
      "name": "Agents",
      "description": "Endpoints for an AI agent acting for a person: self-registration with a verified email (no browser, no password, no captcha; the person only reads a 6-digit code from their mailbox) and a checkout in the Universal Commerce Protocol (UCP) shape to buy a proxy plan, paid from the account balance by the agent or finished by the person on the dashboard. Discovery documents: `agent_auth` in `https://app.quanticdata.io/.well-known/oauth-authorization-server`, the UCP profile at `https://api.quanticdata.io/.well-known/ucp` (also on the dashboard host and the site), and the plain-text guide at `https://quanticdata.io/auth.md`. Registration and claim answer OAuth-style JSON (`error`, `error_description`), not the Data API envelope; the checkout answers UCP documents.\n\n**How an agent pays a top-up without a human (MPP, Stripe).** Every call made with an API key that answers 402 `INSUFFICIENT_FUNDS` (free allowance plus balance below the call's worst-case estimate) also carries a payment challenge in the HTTP Payment authentication scheme (paymentauth.org drafts draft-httpauth-payment-01 and draft-stripe-charge-00; method `stripe`, intent `charge`). The payment buys credit on the account balance, never the single call: no price changes, and the call is then billed from the balance at list price like any other.\n\n1. The 402 carries `WWW-Authenticate: Payment id=\"…\", realm=\"api.quanticdata.io\", method=\"stripe\", intent=\"charge\", request=\"<base64url JSON {amount, currency:\"usd\", decimals:2, methodDetails:{networkId, paymentMethodTypes}}>\", expires=\"<RFC 3339>\", description=\"…\", opaque=\"…\"`. `amount` is in cents and already includes 22% VAT (a $5.00 credit reads `\"610\"`). The body is the usual error envelope with `estimated_cost`, `balance` and `free_remaining`.\n2. The credit offered is the call's shortfall rounded up to the cent, never below $0.50 and never above $1,000 per request. Above $1,000 the challenge offers $1,000 and the envelope also carries `escalation`: the agent asks for a higher limit at `POST /agent/contact`.\n3. The agent obtains a Stripe Shared Payment Token (`spt_…`) for that amount from its payment provider and repeats the same request with `Authorization: Payment <credential>` (or `Payment-Authorization: Payment <credential>`), where `<credential>` is base64url JSON `{\"challenge\": {…the challenge parameters, id to opaque, unchanged…}, \"payload\": {\"spt\": \"spt_…\"}}`. The challenge is valid 5 minutes and single use.\n4. QuanticData charges the token at once, credits the balance, writes a numbered top-up invoice (the credit as taxable amount, 22% VAT, total = the amount charged) and emails it to the account, then runs the call from the balance. The response, whatever the call's own status, carries `Payment-Receipt` (base64url JSON `{status:\"success\", method:\"stripe\", reference:\"pi_…\", timestamp}`), `X-MPP-Credited` (credit added, in cents) and `X-MPP-Invoice` (the invoice id). The credit stays on the balance even if the call itself fails: a failed call is not billed.\n5. If the credit cannot be added after the charge, the payment is refunded in full. Payment errors come back as `application/problem+json` (`type` under `https://paymentauth.org/problems/`): 402 `payment-expired` and `verification-failed` (a declined token) with a fresh challenge to pay, `malformed-credential`, `invalid-payload` and `invalid-challenge` (repeat the request with the API key to get a new challenge), `payment-action-required` (the token needs a step an agent cannot do); 403 `invalid-challenge` for a credential already used; 429 `mpp_limit` with `Retry-After` beyond 30 payments a minute or 2,000 a day per account, or 60 a minute per IP.\n\nNo challenge without an API key (there is no account to credit), none on `BUDGET_REACHED` (the monthly spend cap the person set: a top-up would not lift it) and none on a plan purchase's `INSUFFICIENT_BALANCE`, where the checkout's `continue_url` remains the way. The person sees every top-up, invoice and ledger row on the dashboard and can revoke the key at any time.\n\n**When a 402 carries `escalation`.** `POST /agent/contact` (same API key) reaches the team when a 402 carries `escalation` (credit above the top-up limit, monthly budget cap reached) or when the person wants an enterprise plan or a dataset; the team answers that person by email, nothing is charged."
    }
  ],
  "x-tagGroups": [
    {
      "name": "Data API",
      "tags": [
        "Scrape",
        "Search",
        "Map & Crawl",
        "Batch",
        "Video",
        "Web Unlocker"
      ]
    },
    {
      "name": "AI",
      "tags": [
        "AI extraction",
        "AI visibility",
        "SEO audit"
      ]
    },
    {
      "name": "Collectors & datasets",
      "tags": [
        "Collectors",
        "Datasets",
        "Parser presets"
      ]
    },
    {
      "name": "Proxies",
      "tags": [
        "Proxies",
        "Premium ISP",
        "IPv6",
        "Plans & orders",
        "Proxy locations"
      ]
    },
    {
      "name": "Account",
      "tags": [
        "Account",
        "Agents"
      ]
    }
  ],
  "x-mcp-tools": {
    "$comment": "Tools exposed by the hosted MCP server (tools/list on https://api.quanticdata.io/mcp, 2026-10-07) and the REST endpoint each one calls. Same key, same prices.",
    "tools": [
      {
        "name": "scrape",
        "endpoint": "POST /scraper/extract"
      },
      {
        "name": "search",
        "endpoint": "POST /scraper/serp"
      },
      {
        "name": "search_and_read",
        "endpoint": "POST /scraper/serp + POST /scraper/extract"
      },
      {
        "name": "search_bulk",
        "endpoint": "POST /scraper/serp/bulk"
      },
      {
        "name": "search_bulk_status",
        "endpoint": "GET /scraper/serp/bulk/{jobId}"
      },
      {
        "name": "map",
        "endpoint": "POST /scraper/map"
      },
      {
        "name": "crawl",
        "endpoint": "POST /scraper/crawl"
      },
      {
        "name": "crawl_status",
        "endpoint": "GET /scraper/crawl/{jobId}"
      },
      {
        "name": "batch",
        "endpoint": "POST /scraper/batch"
      },
      {
        "name": "batch_status",
        "endpoint": "GET /scraper/batch/{jobId}"
      },
      {
        "name": "unlock",
        "endpoint": "POST /scraper/unlock"
      },
      {
        "name": "ai_visibility",
        "endpoint": "POST /scraper/ai-visibility"
      },
      {
        "name": "seo_audit",
        "endpoint": "POST /scraper/seo-audit"
      },
      {
        "name": "list_collectors",
        "endpoint": "GET /scraper/collectors"
      },
      {
        "name": "run_collector",
        "endpoint": "POST /scraper/collectors/{slug}/run"
      },
      {
        "name": "collector_run_status",
        "endpoint": "GET /scraper/collectors/runs/{runId}"
      },
      {
        "name": "create_dataset",
        "endpoint": "POST /scraper/datasets"
      },
      {
        "name": "dataset_status",
        "endpoint": "GET /scraper/datasets/{jobId}"
      },
      {
        "name": "generate_parser",
        "endpoint": "POST /scraper/parser/generate"
      },
      {
        "name": "list_parser_presets",
        "endpoint": "GET /scraper/parser/presets"
      },
      {
        "name": "save_parser_preset",
        "endpoint": "POST /scraper/parser/presets"
      },
      {
        "name": "heal_parser_preset",
        "endpoint": "POST /scraper/parser/presets/{id}/heal"
      },
      {
        "name": "parser_preset_stats",
        "endpoint": "GET /scraper/parser/presets/{id}/stats"
      },
      {
        "name": "list_proxies",
        "endpoint": "GET /public/proxies"
      },
      {
        "name": "generate_proxies",
        "endpoint": "POST /public/proxies/generate"
      },
      {
        "name": "proxy_locations",
        "endpoint": "GET /public/generator/{residential-premium|mobile|datacenter}/targeting-options"
      },
      {
        "name": "whitelist_ip",
        "endpoint": "POST /public/proxies/whitelist-ip"
      },
      {
        "name": "report",
        "endpoint": "(MCP only: usage report of the session)"
      }
    ]
  },
  "x-brands": "brands.json",
  "x-pricing": "pricing.json",
  "x-tiers": "tiers.json",
  "x-rate-limits": {
    "description": "Per API key. Two windows apply: the tier's requests/minute (tiers.json → rateLimitPerMin) and an hourly window of max(1000, rateLimitPerMin × 60). The hourly window counts every call made with the key, on every endpoint: Data API, proxy, plan and Premium ISP calls share one counter, so a large scraping job can use up the hour your proxy scripts need. The per-minute budget is per account and counts write calls (POST, PUT, PATCH, DELETE) only. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (hourly window); a 429 also carries Retry-After. Plan-level limiters (per-minute budget, browser-render concurrency) add X-RateLimit-Scope and X-RateLimit-Plan to their 429s.",
    "per_tier": "tiers.json"
  },
  "x-excluded": [
    {
      "path": "/scraper/extract/demo",
      "method": "POST",
      "reason": "Landing-page playground: requires a Turnstile token or a signed guard header issued by the public site, IP-capped (8/min, 15/day). Not callable from customer code."
    },
    {
      "path": "/scraper/ai/demo",
      "method": "POST",
      "reason": "Landing-page playground of the AI agent: Turnstile/guard-gated, IP-capped. Not callable from customer code."
    },
    {
      "path": "/scraper/ai-visibility/demo",
      "method": "POST",
      "reason": "Free tool behind /tools/ai-visibility-audit/: Turnstile/guard-gated, 6/min and 5/day per IP, one query on one engine. Not callable from customer code."
    },
    {
      "path": "/scraper/pdf/demo",
      "method": "POST",
      "reason": "Free tool behind /tools/pdf-to-markdown/: Turnstile/guard-gated, multipart upload, daily IP cap. No key-based equivalent exists as a separate endpoint (documents are handled by /scraper/extract)."
    },
    {
      "path": "/scraper/places-ai/demo",
      "method": "POST",
      "reason": "Landing-page playground: Turnstile/guard-gated, capped searches. Not callable from customer code."
    },
    {
      "path": "/scraper/shopping-ai/demo",
      "method": "POST",
      "reason": "Landing-page playground: Turnstile/guard-gated, capped searches. Not callable from customer code."
    },
    {
      "path": "/scraper/collectors/{slug}/demo",
      "method": "POST",
      "reason": "'Try it' widget on the public collector pages: signed guard header, CORS-locked to the brand sites, 5 rows, 8/min and 10/day per IP. Not callable from customer code."
    },
    {
      "path": "/scraper/collectors/{slug}/demo",
      "method": "OPTIONS",
      "reason": "CORS preflight of the widget endpoint above."
    },
    {
      "path": "/public/plans/price",
      "method": "POST",
      "reason": "Logged-out price of the Premium ISP configurator on the brand sites and in their build (ready-made pools and city plans): no key, 300 requests a minute per IP. With an API key the same price comes from POST /public/premium-isp/quote."
    },
    {
      "path": "/public/premium-isp/subnets",
      "method": "GET",
      "reason": "Logged-out list of the whole /24 subnets on sale (price of one /24 for 30 days, whole subnets in stock) for the ISP pages of the brand sites: no key, 120 requests a minute per IP, empty while subnets are not on sale. With an API key the same subnets come from GET /public/premium-isp/pools (subnet: true, stock)."
    },
    {
      "path": "/public/premium-isp/stock",
      "method": "GET",
      "reason": "Logged-out availability of the ready-made pools (IPs available and the most one order can take) and of the whole /24 subnets, for the ISP country pages of the brand sites: no key, 120 requests a minute per IP. With an API key the same figures come from GET /public/premium-isp/pools (stock, maxQuantity, subnet)."
    },
    {
      "path": "/public/rotate/{token}",
      "method": "HEAD",
      "reason": "Answers 405 without rotating, so link previews and uptime checkers that send HEAD cannot restart a session. Documented in the GET operation."
    },
    {
      "path": "/agent/auth",
      "method": "OPTIONS",
      "reason": "CORS preflight of the agent registration endpoint above (agents may call it from a browser context)."
    },
    {
      "path": "/agent/auth/claim",
      "method": "OPTIONS",
      "reason": "CORS preflight of the agent registration endpoint above (agents may call it from a browser context)."
    },
    {
      "path": "/agent/contact",
      "method": "OPTIONS",
      "reason": "CORS preflight of the agent contact endpoint above (agents may call it from a browser context)."
    },
    {
      "path": "/public/ip-echo",
      "method": "OPTIONS",
      "reason": "CORS preflight of the ip-echo endpoint above (it answers browsers too)."
    },
    {
      "path": "/public/unlock/offer",
      "method": "OPTIONS",
      "reason": "CORS preflight of the Web Unlocker public endpoint above (the brand sites read it from a browser)."
    },
    {
      "path": "/public/unlock/status",
      "method": "OPTIONS",
      "reason": "CORS preflight of the Web Unlocker public endpoint above (the brand sites read it from a browser)."
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "`Authorization: Bearer qd_live_YOUR_API_KEY`. Keys are `qd_live_`/`qp_live_` followed by 64 hex characters and are created on the dashboard API keys page. Only this header is read: there is no `x-api-key` fallback and keys are never accepted in the query string. A disabled, expired or unknown key, or a banned account, answers 401. After a 402 `INSUFFICIENT_FUNDS`, the same header may carry `Payment <credential>` instead of the key, to pay a balance top-up with a Stripe Shared Payment Token (see that response and the Agents tag)."
      }
    },
    "headers": {
      "X-RateLimit-Limit": {
        "description": "Requests allowed in the current hourly window for this key.",
        "schema": {
          "type": "integer"
        }
      },
      "X-RateLimit-Remaining": {
        "description": "Requests left in the window.",
        "schema": {
          "type": "integer"
        }
      },
      "X-RateLimit-Reset": {
        "description": "ISO-8601 instant when the window resets.",
        "schema": {
          "type": "string",
          "format": "date-time"
        }
      },
      "Retry-After": {
        "description": "Seconds to wait before retrying (429 only).",
        "schema": {
          "type": "integer"
        }
      },
      "X-RateLimit-Scope": {
        "description": "Which limiter answered: a plan budget scope, `render-concurrency` or `capacity` (plan-level 429s only).",
        "schema": {
          "type": "string"
        }
      },
      "X-RateLimit-Plan": {
        "description": "The plan the limiter applied (plan-level 429s only).",
        "schema": {
          "type": "string"
        }
      }
    },
    "parameters": {
      "jobId": {
        "name": "jobId",
        "in": "path",
        "required": true,
        "description": "Job id returned by the POST that started it.",
        "schema": {
          "type": "string"
        },
        "example": "job_8f2c1a"
      },
      "presetId": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "Preset id returned when it was created.",
        "schema": {
          "type": "string"
        },
        "example": "pst_7Qk3"
      },
      "runId": {
        "name": "runId",
        "in": "path",
        "required": true,
        "description": "Collector run id (10–40 alphanumeric characters).",
        "schema": {
          "type": "string",
          "pattern": "^[a-z0-9]{10,40}$"
        },
        "example": "cmgfq2x1b0001"
      },
      "slug": {
        "name": "slug",
        "in": "path",
        "required": true,
        "description": "Collector slug from the catalog.",
        "schema": {
          "type": "string"
        },
        "example": "google_maps_places"
      },
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "description": "Unique key per purchase or renewal, 16–128 letters, digits or dashes (a UUID works). Sending the same request again with the same key never charges twice: it answers with the order it already created. The same key with a different body answers 409 `IDEMPOTENCY_CONFLICT`.",
        "schema": {
          "type": "string",
          "pattern": "^[a-zA-Z0-9-]{16,128}$"
        }
      },
      "PremiumIspOrderId": {
        "name": "orderId",
        "in": "path",
        "required": true,
        "description": "`id` of the order (from `POST /public/premium-isp/orders` or `GET /public/premium-isp/orders`).",
        "schema": {
          "type": "string"
        }
      },
      "Ipv6OrderId": {
        "name": "orderId",
        "in": "path",
        "required": true,
        "description": "`id` of the order (from `POST /public/ipv6/orders` or `GET /public/ipv6/orders`). The same id goes to `POST /public/proxies/generate`.",
        "schema": {
          "type": "string"
        }
      },
      "orderId": {
        "name": "orderId",
        "in": "path",
        "required": true,
        "description": "Order id of the plan (`orderId` in `GET /public/proxies`).",
        "schema": {
          "type": "string"
        },
        "example": "ord_8c21"
      },
      "unlockBatchId": {
        "name": "batch_id",
        "in": "path",
        "required": true,
        "description": "Batch id returned by `POST /scraper/unlock/batch`.",
        "schema": {
          "type": "string"
        },
        "example": "ub_5e1c9a40d27f"
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Malformed input. `message` names the parameter and the rule it broke.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "example": {
              "type": "error",
              "message": "Invalid format. Must be one of: markdown, html, text (or data_format markdown/screenshot, format raw)"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing, malformed, unknown, disabled or expired API key; or the account is not active.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "example": {
              "type": "error",
              "message": "Missing or invalid Authorization header. Use: Authorization: Bearer qd_live_YOUR_API_KEY"
            }
          }
        }
      },
      "PaymentRequired": {
        "description": "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`.\n\nWhen 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\".",
        "headers": {
          "WWW-Authenticate": {
            "description": "Only when card top-ups for agents are enabled on this host and the error is `INSUFFICIENT_FUNDS`: a Machine Payments Protocol challenge (`Payment id=…, realm=…, method=\"stripe\", intent=\"charge\", request=…, expires=…, description=…, opaque=…`) that adds credit to this key's account. Repeat the same request with `Authorization: Payment <credential>` to pay it.",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "examples": {
              "insufficient_funds": {
                "value": {
                  "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"
                  }
                }
              },
              "budget_reached": {
                "value": {
                  "type": "error",
                  "message": "Monthly Data API budget reached (50.00 of 50.00 USD). Raise the budget in Billing → Spend controls, or wait for the 1st of next month.",
                  "payload": {
                    "code": "BUDGET_REACHED",
                    "budget_usd": 50,
                    "spent_usd": 50
                  },
                  "escalation": {
                    "type": "contact",
                    "reason": "budget_reached",
                    "limit_usd": 1000,
                    "contact_api": "https://app.quanticdata.io/api/v1/agent/contact",
                    "contact_url": "https://quanticdata.io/enterprise/contact/"
                  }
                }
              },
              "insufficient_funds_above_limit": {
                "summary": "Missing credit above the top-up limit: escalation to the team",
                "value": {
                  "type": "error",
                  "message": "Your free tier for this month is used up and your balance can't cover this call (estimated $1,812.50). 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": 12.5,
                    "free_remaining": 0,
                    "estimated_cost": 1812.5,
                    "plans_url": "https://app.quanticdata.io/plans?utm_source=api&utm_medium=402&utm_campaign=free-tier",
                    "billing_mode": "free_first"
                  },
                  "escalation": {
                    "type": "contact",
                    "reason": "amount_above_limit",
                    "limit_usd": 1000,
                    "contact_api": "https://app.quanticdata.io/api/v1/agent/contact",
                    "contact_url": "https://quanticdata.io/enterprise/contact/"
                  }
                }
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "No proxy pool is available to serve the call (no house plan and no residential/datacenter/IPv6 plan on the account).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "example": {
              "type": "error",
              "message": "Scraper API is not available: no proxy credentials found. Contact support or purchase a residential, datacenter or IPv6 plan."
            }
          }
        }
      },
      "NotFound": {
        "description": "Unknown id — or an id that belongs to another account (ownership failures answer 404, never 403, so ids cannot be probed).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "example": {
              "type": "error",
              "message": "Job not found"
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.",
        "headers": {
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/X-RateLimit-Reset"
          },
          "Retry-After": {
            "$ref": "#/components/headers/Retry-After"
          },
          "X-RateLimit-Scope": {
            "$ref": "#/components/headers/X-RateLimit-Scope"
          },
          "X-RateLimit-Plan": {
            "$ref": "#/components/headers/X-RateLimit-Plan"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "examples": {
              "key_window": {
                "value": {
                  "type": "error",
                  "message": "Rate limit exceeded. Resets in 23 minutes.",
                  "payload": {
                    "rateLimit": 1200,
                    "requestCount": 1200,
                    "resetAt": "2026-10-07T15:00:00.000Z"
                  }
                }
              },
              "render_concurrency": {
                "value": {
                  "type": "error",
                  "message": "Render concurrency limit reached: the payg plan runs 1 browser render(s) at a time. Wait for one to finish and retry in 5s, or submit the URLs as a batch job.",
                  "payload": {
                    "code": "render_concurrency_limit",
                    "plan": "payg",
                    "limit": {
                      "class": "render",
                      "concurrent": 1
                    },
                    "retry_after": 5
                  }
                }
              }
            }
          }
        }
      },
      "ServerError": {
        "description": "Our side: the scraper service is unavailable or the call timed out. Never billed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "example": {
              "type": "error",
              "message": "Scraper service unavailable. Please try again later."
            }
          }
        }
      },
      "IpLookupUnavailable": {
        "description": "No answer right now: the daily cap of new lookups is reached (`Retry-After` until 00:00 UTC), or the source did not answer (`Retry-After: 300`). IPs looked up in the last 24 hours keep answering.",
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait before asking for this IP again.",
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "example": {
              "type": "error",
              "message": "Daily IP lookup limit reached. Try again after 00:00 UTC."
            }
          }
        }
      },
      "ServiceDisabled": {
        "description": "The Data API group is switched off for non-admin keys (early-access kill switch).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "example": {
              "type": "error",
              "message": "This API is temporarily unavailable while we finalize pricing. Contact support for early access."
            }
          }
        }
      },
      "PlanUnavailable": {
        "description": "The plan was disabled by support: it is no longer listed by `GET /public/proxies` and its credentials, endpoints and whitelist are not handed out. Contact support.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "example": {
              "type": "error",
              "message": "This plan is not available. Contact support."
            }
          }
        }
      },
      "PremiumIspForbidden": {
        "description": "Your own API key is required (keyless and pay-per-call access cannot buy), keys created by a connected app cannot spend the balance, or the plan was disabled by support.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "examples": {
              "KEY_REQUIRED": {
                "value": {
                  "type": "error",
                  "message": "Premium ISP needs your own API key. Create one in the dashboard under API keys.",
                  "payload": {
                    "code": "KEY_REQUIRED"
                  }
                }
              },
              "KEY_NOT_ALLOWED": {
                "value": {
                  "type": "error",
                  "message": "Keys created by a connected app cannot spend your balance. Use an API key created in the dashboard.",
                  "payload": {
                    "code": "KEY_NOT_ALLOWED"
                  }
                }
              },
              "PLAN_DISABLED": {
                "value": {
                  "type": "error",
                  "message": "This plan is not available. Contact support.",
                  "payload": {
                    "code": "PLAN_DISABLED"
                  }
                }
              }
            }
          }
        }
      },
      "PremiumIspConflict": {
        "description": "The selection cannot be sold right now, or the request conflicts with an earlier one. Nothing was charged unless the code says so.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "examples": {
              "CITY_UNAVAILABLE": {
                "value": {
                  "type": "error",
                  "message": "This city is not available right now.",
                  "payload": {
                    "code": "CITY_UNAVAILABLE"
                  }
                }
              },
              "CARRIER_UNAVAILABLE": {
                "value": {
                  "type": "error",
                  "message": "This carrier is not available in this city.",
                  "payload": {
                    "code": "CARRIER_UNAVAILABLE"
                  }
                }
              },
              "INSUFFICIENT_STOCK": {
                "value": {
                  "type": "error",
                  "message": "Not enough IPs in stock in this city.",
                  "payload": {
                    "code": "INSUFFICIENT_STOCK"
                  }
                }
              },
              "POOL_UNAVAILABLE": {
                "value": {
                  "type": "error",
                  "message": "This Premium ISP product is currently unavailable.",
                  "payload": {
                    "code": "POOL_UNAVAILABLE"
                  }
                }
              },
              "PRICE_CHANGED": {
                "value": {
                  "type": "error",
                  "message": "The price is above your maxTotal. Nothing was charged.",
                  "payload": {
                    "code": "PRICE_CHANGED"
                  }
                }
              },
              "IDEMPOTENCY_CONFLICT": {
                "value": {
                  "type": "error",
                  "message": "This Idempotency-Key was already used for a different selection. Use a new key.",
                  "payload": {
                    "code": "IDEMPOTENCY_CONFLICT"
                  }
                }
              },
              "CHECKOUT_CLOSED": {
                "value": {
                  "type": "error",
                  "message": "This purchase is closed. Send it again with a new Idempotency-Key.",
                  "payload": {
                    "code": "CHECKOUT_CLOSED",
                    "newCheckoutRequired": true
                  }
                }
              },
              "PAYMENT_UNDER_REVIEW": {
                "value": {
                  "type": "error",
                  "message": "Your payment needs verification. Check your orders or contact support before purchasing again.",
                  "payload": {
                    "code": "PAYMENT_UNDER_REVIEW"
                  }
                }
              },
              "AUTO_REPLACE_NOT_AVAILABLE": {
                "value": {
                  "type": "error",
                  "message": "Auto-replace is a setting of city plans.",
                  "payload": {
                    "code": "AUTO_REPLACE_NOT_AVAILABLE"
                  }
                }
              },
              "NO_REPLACEMENTS_LEFT": {
                "value": {
                  "type": "error",
                  "message": "This plan has no prepaid IP swap left. Send {\"ip\": \"...\", \"pay\": true} to buy one for $1.50 from your balance.",
                  "payload": {
                    "code": "NO_REPLACEMENTS_LEFT",
                    "paidSwapPrice": 1.5
                  }
                }
              },
              "NO_STOCK_IN_CITY": {
                "value": {
                  "type": "error",
                  "message": "There is no free IP in this city right now, so this IP was not replaced. The replacement stays free: try again later, or write to support.",
                  "payload": {
                    "code": "NO_STOCK_IN_CITY"
                  }
                }
              }
            }
          }
        }
      },
      "PremiumIspPaymentRequired": {
        "description": "The wallet balance cannot cover the total. Nothing was created or charged: top up in the dashboard and send the request again.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "examples": {
              "INSUFFICIENT_BALANCE": {
                "value": {
                  "type": "error",
                  "message": "Your balance is too low for this purchase. Top up in the dashboard and try again.",
                  "payload": {
                    "code": "INSUFFICIENT_BALANCE"
                  }
                }
              }
            }
          }
        }
      },
      "PremiumIspUnavailable": {
        "description": "Premium ISP is not available through the API on this account yet, a price or the catalog cannot be read right now, or balance payments are switched off. Retry after the `Retry-After` seconds.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "examples": {
              "PRODUCT_DISABLED": {
                "value": {
                  "type": "error",
                  "message": "Premium ISP is not available through the API yet. Use the dashboard to buy Premium ISP plans.",
                  "payload": {
                    "code": "PRODUCT_DISABLED"
                  }
                }
              },
              "SERVICE_UNAVAILABLE": {
                "value": {
                  "type": "error",
                  "message": "Premium ISP is temporarily unavailable. Please try again shortly.",
                  "payload": {
                    "code": "SERVICE_UNAVAILABLE"
                  }
                }
              },
              "PRICING_UNAVAILABLE": {
                "value": {
                  "type": "error",
                  "message": "Premium ISP pricing is being updated. Please try again later.",
                  "payload": {
                    "code": "PRICING_UNAVAILABLE"
                  }
                }
              }
            }
          }
        },
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/Retry-After"
          }
        }
      },
      "PremiumIspNotDelivered": {
        "description": "The IPs could not be delivered and the amount is back on your balance: you have not been charged. Send the purchase again with a new Idempotency-Key.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "examples": {
              "NOT_DELIVERED_REFUNDED": {
                "value": {
                  "type": "error",
                  "message": "The IPs could not be delivered. You have not been charged: the amount is back on your balance.",
                  "payload": {
                    "code": "NOT_DELIVERED_REFUNDED",
                    "refunded": true,
                    "newCheckoutRequired": true,
                    "orderId": "ord_5f2a",
                    "invoiceId": "inv_77c1"
                  }
                }
              }
            }
          }
        }
      },
      "Ipv6Forbidden": {
        "description": "Your own API key is required (keyless and pay-per-call access cannot buy), or the key was created by a connected app and cannot spend the balance.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "examples": {
              "KEY_REQUIRED": {
                "value": {
                  "type": "error",
                  "message": "IPv6 speed plans need your own API key. Create one in the dashboard under API keys.",
                  "payload": {
                    "code": "KEY_REQUIRED"
                  }
                }
              },
              "KEY_NOT_ALLOWED": {
                "value": {
                  "type": "error",
                  "message": "Keys created by a connected app cannot spend your balance. Use an API key created in the dashboard.",
                  "payload": {
                    "code": "KEY_NOT_ALLOWED"
                  }
                }
              }
            }
          }
        }
      },
      "Ipv6Conflict": {
        "description": "The cell is not sold, the price moved above your `maxTotal`, the Idempotency-Key was reused for another body, the checkout is closed, or the payment needs a human look. Nothing was charged unless the message says otherwise.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "examples": {
              "SPEED_UNAVAILABLE": {
                "value": {
                  "type": "error",
                  "message": "This speed is not sold. Available: 30 Mbps, 60 Mbps, 120 Mbps, 200 Mbps; 1000 Mbps on request.",
                  "payload": {
                    "code": "SPEED_UNAVAILABLE",
                    "speeds": [
                      30,
                      60,
                      120,
                      200
                    ]
                  }
                }
              },
              "TERM_UNAVAILABLE": {
                "value": {
                  "type": "error",
                  "message": "30 Mbps is not sold for 7 days.",
                  "payload": {
                    "code": "TERM_UNAVAILABLE",
                    "speedMbps": 30,
                    "days": 7,
                    "availableSpeeds": [
                      60,
                      120,
                      200
                    ]
                  }
                }
              },
              "CONTACT_REQUIRED": {
                "value": {
                  "type": "error",
                  "message": "1000 Mbps is sold on request: ask for it in the dashboard (Plans → IPv6 → 1000 Mbps → Contact us).",
                  "payload": {
                    "code": "CONTACT_REQUIRED",
                    "speedMbps": 1000
                  }
                }
              },
              "PRICE_CHANGED": {
                "value": {
                  "type": "error",
                  "message": "The price is above your maxTotal. Nothing was charged.",
                  "payload": {
                    "code": "PRICE_CHANGED",
                    "quote": {
                      "speedMbps": 200,
                      "days": 7
                    }
                  }
                }
              },
              "IDEMPOTENCY_CONFLICT": {
                "value": {
                  "type": "error",
                  "message": "This Idempotency-Key was already used for a different selection. Use a new key.",
                  "payload": {
                    "code": "IDEMPOTENCY_CONFLICT"
                  }
                }
              },
              "CHECKOUT_CLOSED": {
                "value": {
                  "type": "error",
                  "message": "This purchase is closed. Send it again with a new Idempotency-Key.",
                  "payload": {
                    "code": "CHECKOUT_CLOSED",
                    "newCheckoutRequired": true
                  }
                }
              },
              "PAYMENT_UNDER_REVIEW": {
                "value": {
                  "type": "error",
                  "message": "Your payment needs verification. Check your orders or contact support before purchasing again.",
                  "payload": {
                    "code": "PAYMENT_UNDER_REVIEW",
                    "orderId": "ord_7a1c",
                    "invoiceId": "inv_3b9e"
                  }
                }
              }
            }
          }
        }
      },
      "Ipv6PaymentRequired": {
        "description": "The wallet balance cannot cover the total. Nothing was created or charged: top up in the dashboard and send the request again.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "examples": {
              "INSUFFICIENT_BALANCE": {
                "value": {
                  "type": "error",
                  "message": "Your balance is too low for this purchase. Top up in the dashboard and try again.",
                  "payload": {
                    "code": "INSUFFICIENT_BALANCE"
                  }
                }
              }
            }
          }
        }
      },
      "Ipv6Unavailable": {
        "description": "IPv6 speed plans are not available through the API on this account yet, the grid cannot be read right now, or balance payments are switched off. Retry after the `Retry-After` seconds.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "examples": {
              "PRODUCT_DISABLED": {
                "value": {
                  "type": "error",
                  "message": "IPv6 speed plans are not available through the API yet. Use the dashboard to buy them.",
                  "payload": {
                    "code": "PRODUCT_DISABLED"
                  }
                }
              },
              "PRICING_UNAVAILABLE": {
                "value": {
                  "type": "error",
                  "message": "IPv6 speed plans are being updated. Please try again later.",
                  "payload": {
                    "code": "PRICING_UNAVAILABLE"
                  }
                }
              },
              "PAYMENT_METHOD_UNAVAILABLE": {
                "value": {
                  "type": "error",
                  "message": "Payments from balance are temporarily unavailable. Please try again later.",
                  "payload": {
                    "code": "PAYMENT_METHOD_UNAVAILABLE"
                  }
                }
              },
              "SERVICE_UNAVAILABLE": {
                "value": {
                  "type": "error",
                  "message": "IPv6 speed plans are temporarily unavailable. Please try again shortly.",
                  "payload": {
                    "code": "SERVICE_UNAVAILABLE"
                  }
                }
              }
            }
          }
        }
      },
      "Ipv6NotDelivered": {
        "description": "The plan could not be delivered and the amount is back on your balance: you have not been charged. Send the purchase again with a new Idempotency-Key.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "examples": {
              "NOT_DELIVERED_REFUNDED": {
                "value": {
                  "type": "error",
                  "message": "The plan could not be delivered. You have not been charged: the amount is back on your balance.",
                  "payload": {
                    "code": "NOT_DELIVERED_REFUNDED",
                    "refunded": true,
                    "newCheckoutRequired": true,
                    "orderId": "ord_7a1c",
                    "invoiceId": "inv_3b9e"
                  }
                }
              }
            }
          }
        }
      },
      "RotationNotSupported": {
        "description": "This plan type has no rotation in place (`ROTATION_NOT_SUPPORTED`). `reason`: `new_string_only` — request a new sticky string with `generate`; `static_ips` — ISP plans have dedicated static IPs; `gateway_managed` — the gateway assigns the IP. Also `LINK_LIMIT_REACHED` on link creation (1,000 active links per plan).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "examples": {
              "new_string_only": {
                "value": {
                  "type": "error",
                  "message": "Rotation links are not available for this plan. For a new IP, request a new sticky proxy string with POST /v1/public/proxies/generate: each string has its own session.",
                  "payload": {
                    "code": "ROTATION_NOT_SUPPORTED",
                    "planType": "residentialpremium",
                    "reason": "new_string_only"
                  }
                }
              },
              "static_ips": {
                "value": {
                  "type": "error",
                  "message": "ISP plans have static IPs: there is nothing to rotate.",
                  "payload": {
                    "code": "ROTATION_NOT_SUPPORTED",
                    "planType": "isp",
                    "reason": "static_ips"
                  }
                }
              }
            }
          }
        }
      },
      "RotationRateLimited": {
        "description": "`RATE_LIMITED`: one rotation every 10 seconds per session (`scope: session`), 1,200 rotations an hour per account (`scope: account`), or too many unknown links from one address (`scope: ip`, link only). API-key calls also count against the key's hourly window. Back off on Retry-After.",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/Retry-After"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "examples": {
              "session": {
                "value": {
                  "type": "error",
                  "message": "This session was rotated less than 10 seconds ago. Try again in 7 s.",
                  "payload": {
                    "code": "RATE_LIMITED",
                    "scope": "session",
                    "retryAfter": 7
                  }
                }
              },
              "account": {
                "value": {
                  "type": "error",
                  "message": "This account reached 1200 rotations in an hour. Try again in 12 minutes.",
                  "payload": {
                    "code": "RATE_LIMITED",
                    "scope": "account",
                    "retryAfter": 700
                  }
                }
              }
            }
          }
        }
      },
      "RotationFailed": {
        "description": "`ROTATION_FAILED`: the session could not be restarted this time. The proxy string keeps working with its current IP. Retry after Retry-After.",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/Retry-After"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "example": {
              "type": "error",
              "message": "The IP could not be rotated right now. Your proxy string still works. Try again in a few seconds.",
              "payload": {
                "code": "ROTATION_FAILED"
              }
            }
          }
        }
      },
      "RotationUnavailable": {
        "description": "`SERVICE_UNAVAILABLE`: rotation is temporarily unavailable. Retry after Retry-After.",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/Retry-After"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "example": {
              "type": "error",
              "message": "Rotation links are temporarily unavailable. Please try again later.",
              "payload": {
                "code": "SERVICE_UNAVAILABLE"
              }
            }
          }
        }
      }
    },
    "schemas": {
      "Envelope": {
        "type": "object",
        "description": "Success envelope shared by every endpoint.",
        "required": [
          "type",
          "message",
          "payload"
        ],
        "properties": {
          "type": {
            "type": "string",
            "const": "response"
          },
          "message": {
            "type": "string"
          },
          "payload": {
            "type": "object"
          },
          "pagination": {
            "type": "object",
            "description": "Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here)."
          }
        }
      },
      "ErrorEnvelope": {
        "type": "object",
        "description": "Error envelope. `payload` is present only when the error carries structured detail (codes, balances, limits). `escalation` is present only on a 402 that asks to talk to the team instead of paying (see `ContactEscalation`).",
        "required": [
          "type",
          "message"
        ],
        "properties": {
          "type": {
            "type": "string",
            "const": "error"
          },
          "message": {
            "type": "string"
          },
          "payload": {
            "type": "object"
          },
          "escalation": {
            "$ref": "#/components/schemas/ContactEscalation"
          }
        }
      },
      "Usage": {
        "type": "object",
        "description": "What the call cost. Present only on billed calls (absent when billing is off for the account or the key is an admin key).",
        "required": [
          "cost_usd",
          "free_usd",
          "paid_usd"
        ],
        "properties": {
          "cost_usd": {
            "type": "number",
            "description": "Total cost of the call, USD, after the tier discount."
          },
          "free_usd": {
            "type": "number",
            "description": "Portion covered by the monthly free allowance."
          },
          "paid_usd": {
            "type": "number",
            "description": "Portion debited from the wallet."
          },
          "balance": {
            "type": "number",
            "description": "Wallet balance after the debit, present only when the wallet was touched."
          }
        }
      },
      "Geo": {
        "type": "object",
        "description": "Echo of the geo-targeting the call used.",
        "properties": {
          "country": {
            "type": [
              "string",
              "null"
            ]
          },
          "state": {
            "type": [
              "string",
              "null"
            ]
          },
          "city": {
            "type": [
              "string",
              "null"
            ]
          },
          "rotation": {
            "type": "string",
            "enum": [
              "rotating",
              "sticky"
            ]
          }
        }
      },
      "GeoValue": {
        "type": "string",
        "description": "Country code or place name: letters, digits, spaces, dots, hyphens, underscores; max 56 characters. `all` means no targeting.",
        "pattern": "^([a-zA-Z0-9 ._-]{1,56}|all)$",
        "examples": [
          "us",
          "it",
          "all"
        ]
      },
      "ExtractSchema": {
        "type": "object",
        "description": "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).",
        "additionalProperties": {
          "oneOf": [
            {
              "type": "string",
              "description": "CSS selector; the element's text is returned."
            },
            {
              "type": "object",
              "properties": {
                "selector": {
                  "type": "string"
                },
                "attr": {
                  "type": "string"
                },
                "all": {
                  "type": "boolean"
                }
              },
              "required": [
                "selector"
              ]
            }
          ]
        },
        "examples": [
          {
            "title": "h1",
            "price": ".price",
            "image": {
              "selector": "img.hero",
              "attr": "src"
            },
            "features": {
              "selector": "li.feature",
              "all": true
            }
          }
        ]
      },
      "PageAction": {
        "type": "object",
        "description": "One interaction before capture (render tier). Shapes are enforced by the scraper service; at most 20 actions, each a plain object. A `fetchResource` action must be last: the matching network response becomes the result body.",
        "examples": [
          {
            "click": "#accept"
          },
          {
            "scroll": "bottom"
          },
          {
            "wait": 1500
          },
          {
            "fetchResource": {
              "pattern": "/api/items"
            }
          }
        ]
      },
      "ForwardHeaders": {
        "description": "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.",
        "oneOf": [
          {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          {
            "type": "string"
          }
        ]
      },
      "PageMetadata": {
        "type": "object",
        "description": "Meta/OpenGraph data of an HTML page (keys depend on what the page declares).",
        "properties": {
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "canonical": {
            "type": [
              "string",
              "null"
            ]
          },
          "language": {
            "type": [
              "string",
              "null"
            ]
          },
          "appState": {
            "description": "The page's own hydration state (Next/Nuxt/JSON islands), present only when `app_state` was requested."
          }
        },
        "additionalProperties": true
      },
      "ExtractResult": {
        "type": "object",
        "description": "Payload of a scrape. Optional fields appear only when requested (`data`, `links`, `screenshot`, `xhr`, `formats`, `contents`, `chunks`, `highlights`, `ai`).",
        "required": [
          "url",
          "finalUrl",
          "status",
          "format",
          "content",
          "bytes",
          "durationMs"
        ],
        "properties": {
          "url": {
            "type": "string"
          },
          "finalUrl": {
            "type": "string",
            "description": "URL after redirects."
          },
          "status": {
            "type": "integer",
            "description": "HTTP status the target answered."
          },
          "contentType": {
            "type": [
              "string",
              "null"
            ]
          },
          "format": {
            "type": "string",
            "enum": [
              "markdown",
              "html",
              "text"
            ]
          },
          "title": {
            "type": [
              "string",
              "null"
            ]
          },
          "metadata": {
            "$ref": "#/components/schemas/PageMetadata"
          },
          "content": {
            "type": "string",
            "description": "The page in the requested format (empty in `mode: summary`)."
          },
          "contents": {
            "type": "object",
            "description": "One entry per requested `content_modes` value.",
            "additionalProperties": {
              "type": "string"
            }
          },
          "chunks": {
            "type": "array",
            "description": "Segmented output when `chunk` was requested.",
            "items": {
              "type": "object"
            }
          },
          "highlights": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "bytes": {
            "type": "integer",
            "description": "Proxy bandwidth the fetch used — the metered part of the price."
          },
          "durationMs": {
            "type": "integer"
          },
          "engine": {
            "type": "string",
            "enum": [
              "tls",
              "fetch",
              "render"
            ],
            "description": "Engine that actually served the page; decides between the `extract` and `extract_render` price."
          },
          "attempts": {
            "type": "integer"
          },
          "escalated": {
            "type": "boolean",
            "description": "True when `engine: auto` escalated from the TLS tier to the browser."
          },
          "blockReason": {
            "type": "string",
            "description": "Present when the final page was an anti-bot block (the call is then not charged)."
          },
          "tlsProfile": {
            "type": "string"
          },
          "jsLikely": {
            "type": "boolean",
            "description": "Content came out near-empty but the HTML is a JS app shell: retry with `render: true`."
          },
          "screenshot": {
            "type": "string",
            "description": "Base64 PNG, render tier only."
          },
          "xhr": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "resource": {
            "type": "object",
            "description": "The network response captured by a `fetchResource` action; its body is `content`."
          },
          "data": {
            "type": "object",
            "description": "Values of the `extract` schema (or of the `presetId` parser)."
          },
          "formats": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "links": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "notes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "documentKind": {
            "type": "string",
            "description": "Set when the URL was a binary document converted to text (pdf, docx, xlsx, csv)."
          },
          "ai": {
            "type": "object",
            "description": "AI extraction result (`ai_prompt`/`ai_schema`): `data`, `truncated`, `model`, `usage`; or `error` when the model step failed (the scrape itself still succeeded).",
            "properties": {
              "data": {},
              "truncated": {
                "type": "boolean"
              },
              "model": {
                "type": "string"
              },
              "usage": {
                "type": "object"
              },
              "error": {
                "type": "string"
              }
            }
          },
          "geo": {
            "$ref": "#/components/schemas/Geo"
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          }
        },
        "additionalProperties": true
      },
      "OrganicResult": {
        "type": "object",
        "required": [
          "rank",
          "title",
          "link"
        ],
        "properties": {
          "rank": {
            "type": "integer"
          },
          "title": {
            "type": "string"
          },
          "link": {
            "type": "string",
            "description": "The result URL. On Google results it can be Google's click address (`https://www.google.com/url?…`) instead of the site's own URL: it opens the result in a browser, and `redirect_link` carries the same address."
          },
          "redirect_link": {
            "type": [
              "string",
              "null"
            ],
            "description": "Google's click address for the result (`https://www.google.com/url?…`) when Google links the result through one, otherwise `null`."
          },
          "display_link": {
            "type": [
              "string",
              "null"
            ]
          },
          "source": {
            "type": [
              "string",
              "null"
            ],
            "description": "Registrable host, e.g. wikipedia.org."
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "date": {
            "type": [
              "string",
              "null"
            ]
          },
          "snippet_highlighted_words": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "sitelinks": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "rich_snippet": {
            "type": "object"
          }
        }
      },
      "SerpResult": {
        "type": "object",
        "description": "Search result in the common SERP-API JSON shape (drop-in for most existing SERP clients). Vertical arrays are always present (empty when the vertical did not apply); the single-object verticals (`place_results`, `product_results`, `trends`, `trending`, `knowledge_graph`, …) are null when absent.",
        "required": [
          "search_metadata",
          "search_parameters",
          "organic",
          "pagination"
        ],
        "properties": {
          "search_metadata": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string"
              },
              "engine": {
                "type": "string"
              },
              "search_url": {
                "type": "string",
                "description": "The engine URL that was searched, with the engine's own parameters only."
              },
              "created_at": {
                "type": "string"
              },
              "total_time_taken": {
                "type": "number"
              },
              "attempts": {
                "type": "integer"
              },
              "bytes": {
                "type": "integer"
              },
              "from_cache": {
                "type": "boolean",
                "description": "Served from the 24h result cache — identical requests are free."
              },
              "path": {
                "type": "string",
                "enum": [
                  "http",
                  "farm",
                  "sei",
                  "render"
                ],
                "description": "Winning fetch tier. `http` bills the `serp` price; anything else bills `serp_render` (Google only)."
              },
              "served_device": {
                "type": "string",
                "enum": [
                  "mobile",
                  "desktop"
                ],
                "description": "Google: the device the returned page was served for, read from the page itself (`search_parameters.device` is the device you asked for). Web, news and videos never return the other device's page: if Google keeps serving it, the call ends with 429 `device-mismatch`, unbilled, and can be retried. Absent where the source is not a results page (autocomplete, Maps, place details, trends, reviews)."
              },
              "served_platform": {
                "type": "string",
                "enum": [
                  "ios",
                  "android",
                  "desktop"
                ],
                "description": "Google web, news and videos: the device the page was fetched as (`android` for `mobile`, `ios` and `android`; `desktop`)."
              },
              "served_browser": {
                "type": "string",
                "enum": [
                  "safari",
                  "chrome",
                  "edge",
                  "firefox"
                ],
                "description": "Google web, news and videos: the browser the page was fetched as (`edge`)."
              },
              "empty_reason": {
                "type": "string",
                "enum": [
                  "no_results"
                ],
                "description": "Present when a Success carries no results, and says why: `no_results` = the engine's own \"no results\" page (Google's \"did not match any documents\"; Bing's \"There are no results\", taken only from a browser attempt, never from the HTTP tier alone). A zero-result page without a reason never leaves as a Success for Google search or Bing web search: it is a 429 (`empty-soft-throttle`, `bing-decoy`, `bing-no-results`), unbilled, that you can retry."
              },
              "paging": {
                "type": "object"
              }
            }
          },
          "search_parameters": {
            "type": "object",
            "properties": {
              "engine": {
                "type": "string"
              },
              "q": {
                "type": "string"
              },
              "search_type": {
                "type": "string"
              },
              "device": {
                "type": "string",
                "enum": [
                  "desktop",
                  "mobile",
                  "ios",
                  "android"
                ],
                "description": "The device asked for."
              },
              "country": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "language": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "page": {
                "type": "integer"
              }
            }
          },
          "general": {
            "type": "object"
          },
          "retries": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "organic": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrganicResult"
            }
          },
          "ads": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "shopping": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "images": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "news": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "places": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "scholar": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "jobs_results": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "suggestions": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "trends": {
            "type": [
              "object",
              "null"
            ]
          },
          "trending": {
            "type": [
              "object",
              "null"
            ]
          },
          "place_results": {
            "type": [
              "object",
              "null"
            ]
          },
          "properties": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Google Hotels property cards."
          },
          "flights_results": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "events_results": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "product_results": {
            "type": [
              "object",
              "null"
            ]
          },
          "visual_matches": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "reviews_results": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "serpapi_pagination": {
            "type": "object",
            "properties": {
              "next_page_token": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "inline_videos": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "immersive_products": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "perspectives": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "related": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "related_searches": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "refine_this_search": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "refine_search_filters": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "things_to_know": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "people_also_ask": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "related_questions": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "knowledge": {
            "type": [
              "object",
              "null"
            ]
          },
          "knowledge_graph": {
            "type": [
              "object",
              "null"
            ]
          },
          "featured_snippet": {
            "type": [
              "object",
              "null"
            ]
          },
          "ai_overview": {
            "type": [
              "string",
              "null"
            ]
          },
          "ai_overview_references": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "answer_box": {
            "type": [
              "object",
              "null"
            ]
          },
          "weather": {
            "type": [
              "object",
              "null"
            ]
          },
          "flights": {
            "type": [
              "object",
              "null"
            ]
          },
          "currency": {
            "type": [
              "object",
              "null"
            ]
          },
          "pagination": {
            "type": "object",
            "properties": {
              "current": {
                "type": "integer"
              },
              "next": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "total_pages": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "other_pages": {
                "type": "object"
              },
              "available_pages": {
                "type": "array",
                "items": {
                  "type": "integer"
                }
              },
              "has_next": {
                "type": "boolean"
              }
            }
          },
          "html": {
            "type": "string",
            "description": "Full page HTML, only with `include_html: true`."
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          }
        },
        "additionalProperties": true
      },
      "MapResult": {
        "type": "object",
        "required": [
          "url",
          "count",
          "total",
          "summary",
          "sources",
          "durationMs"
        ],
        "properties": {
          "url": {
            "type": "string"
          },
          "links": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Up to `limit` URLs (omitted with `group_by`)."
          },
          "count": {
            "type": "integer",
            "description": "How many URLs `links` holds."
          },
          "total": {
            "type": "integer",
            "description": "URLs discovered site-wide (can exceed `count`)."
          },
          "summary": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            },
            "description": "URLs per first path segment."
          },
          "groups": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            },
            "description": "Path tree with counts (depth 2), only with `group_by: path`."
          },
          "sources": {
            "type": "object",
            "properties": {
              "sitemap": {
                "type": "integer"
              },
              "homepage": {
                "type": "integer"
              }
            }
          },
          "durationMs": {
            "type": "integer"
          },
          "geo": {
            "type": "object",
            "properties": {
              "country": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          }
        }
      },
      "JobStarted": {
        "type": "object",
        "description": "Answer of a POST that started an async job.",
        "required": [
          "id",
          "status",
          "statusUrl"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "statusUrl": {
            "type": "string",
            "description": "Dashboard-host path to poll (prefix it with the app host, or call the same path on the API host without `/api`)."
          },
          "usage": {
            "$ref": "#/components/schemas/Usage",
            "description": "The up-front charge on the requested volume; the unfetched share is refunded when the job settles."
          }
        },
        "additionalProperties": true
      },
      "CrawlPage": {
        "type": "object",
        "required": [
          "url",
          "status",
          "depth"
        ],
        "properties": {
          "url": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "title": {
            "type": [
              "string",
              "null"
            ]
          },
          "depth": {
            "type": "integer"
          },
          "content": {
            "type": "string",
            "description": "Omitted when polled with `include_content=false`."
          },
          "error": {
            "type": "string"
          }
        }
      },
      "CrawlJob": {
        "type": "object",
        "required": [
          "id",
          "status",
          "seed",
          "limit",
          "depth",
          "format",
          "pagesCrawled",
          "pagesQueued",
          "pages",
          "nextCursor",
          "hasMore"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "running",
              "completed",
              "failed",
              "cancelled"
            ]
          },
          "seed": {
            "type": "string"
          },
          "limit": {
            "type": "integer"
          },
          "depth": {
            "type": "integer"
          },
          "format": {
            "type": "string"
          },
          "pagesCrawled": {
            "type": "integer"
          },
          "pagesQueued": {
            "type": "integer"
          },
          "error": {
            "type": "string"
          },
          "pages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CrawlPage"
            }
          },
          "nextCursor": {
            "type": "integer",
            "description": "Pass as `since` on the next poll to receive only newer pages."
          },
          "hasMore": {
            "type": "boolean",
            "description": "Finished pages beyond `nextCursor` were withheld (byte budget or cursor)."
          },
          "createdAt": {
            "type": "integer",
            "description": "Unix ms."
          },
          "finishedAt": {
            "type": [
              "integer",
              "null"
            ]
          }
        }
      },
      "BatchItem": {
        "type": "object",
        "required": [
          "url",
          "status"
        ],
        "properties": {
          "url": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "title": {
            "type": [
              "string",
              "null"
            ]
          },
          "content": {
            "type": "string",
            "description": "Only with `include_content=true` and not in `mode: summary`."
          },
          "data": {
            "type": "object",
            "description": "Values of the `extract` schema."
          },
          "engine": {
            "type": "string"
          },
          "error": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "Summary mode."
          },
          "canonical": {
            "type": [
              "string",
              "null"
            ],
            "description": "Summary mode."
          },
          "contentLength": {
            "type": "integer",
            "description": "Summary mode: characters of the converted content."
          },
          "bytes": {
            "type": "integer"
          },
          "blockReason": {
            "type": "string",
            "description": "Anti-bot block: the URL counts as failed and is refunded."
          }
        }
      },
      "BatchJob": {
        "type": "object",
        "required": [
          "id",
          "status",
          "total",
          "completed",
          "failed",
          "items",
          "nextCursor",
          "hasMore"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "running",
              "completed",
              "cancelled",
              "failed"
            ]
          },
          "total": {
            "type": "integer"
          },
          "completed": {
            "type": "integer"
          },
          "failed": {
            "type": "integer"
          },
          "error": {
            "type": "string"
          },
          "contentTruncated": {
            "type": "boolean",
            "description": "The job hit its memory budget; later items carry metadata only."
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BatchItem"
            }
          },
          "nextCursor": {
            "type": "integer"
          },
          "hasMore": {
            "type": "boolean"
          },
          "createdAt": {
            "type": "integer"
          },
          "finishedAt": {
            "type": [
              "integer",
              "null"
            ]
          }
        }
      },
      "SerpBulkJob": {
        "type": "object",
        "required": [
          "id",
          "status",
          "query",
          "total",
          "completed",
          "failed",
          "pages",
          "organic",
          "nextCursor"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "running",
              "completed",
              "cancelled",
              "failed"
            ]
          },
          "query": {
            "type": "string"
          },
          "total": {
            "type": "integer",
            "description": "Pages requested (`max_pages`)."
          },
          "completed": {
            "type": "integer"
          },
          "failed": {
            "type": "integer"
          },
          "error": {
            "type": "string"
          },
          "pages": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "page": {
                  "type": "integer"
                },
                "organic_count": {
                  "type": "integer"
                },
                "bytes": {
                  "type": "integer"
                },
                "path": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "error": {
                  "type": "string"
                }
              }
            }
          },
          "organic": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrganicResult"
            },
            "description": "Merged, de-duplicated, re-ranked across pages (from `since` onwards)."
          },
          "related_searches": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "ai_overview": {
            "type": [
              "string",
              "null"
            ]
          },
          "search_metadata": {
            "type": "object"
          },
          "search_parameters": {
            "type": "object"
          },
          "pagination": {
            "type": "object"
          },
          "available_pages": {
            "type": "array",
            "items": {
              "type": "integer"
            }
          },
          "nextCursor": {
            "type": "integer"
          },
          "createdAt": {
            "type": "integer"
          },
          "finishedAt": {
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "additionalProperties": true
      },
      "UnlockResult": {
        "type": "object",
        "description": "The target's response, replayed. `bodyBase64` is always present and is the raw page; `body` only when the content type is text-like (html, xml, text, json, javascript), in the `format` asked for HTML pages. `blocked: true` means every tier came back with a challenge or refusal and the payload is that page, for inspection.",
        "required": [
          "request_id",
          "status",
          "bodyBase64",
          "attempts",
          "cache",
          "blocked",
          "rendered",
          "escalated",
          "mode",
          "tier_served",
          "tier",
          "latency_ms",
          "attempt_log",
          "usage",
          "cost"
        ],
        "properties": {
          "request_id": {
            "type": "string",
            "description": "Id of this exchange, the same value as the `x-qp-request-id` header; quote it to support."
          },
          "status": {
            "type": "integer",
            "description": "HTTP status the origin answered."
          },
          "headers": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "body": {
            "type": "string",
            "description": "The response as text, in the `format` asked (`html`, `markdown`, `text`) when the page is HTML; absent for binary content."
          },
          "bodyBase64": {
            "type": "string",
            "description": "The raw response body, base64, always present."
          },
          "finalUrl": {
            "type": "string",
            "description": "URL after redirects."
          },
          "contentType": {
            "type": [
              "string",
              "null"
            ]
          },
          "profile": {
            "type": "string",
            "description": "TLS fingerprint profile that won."
          },
          "attempts": {
            "type": "integer",
            "description": "Number of attempts across every tier (the detail is in `attempt_log`); 0 when the answer came from the cache."
          },
          "blocked": {
            "type": "boolean",
            "description": "Every tier came back with a challenge or refusal; the payload is that page, for inspection."
          },
          "blockReason": {
            "type": "string"
          },
          "blockClass": {
            "type": "string",
            "enum": [
              "js_challenge",
              "captcha",
              "access_denied",
              "rate_limited",
              "fingerprint",
              "geo",
              "timeout",
              "unknown"
            ]
          },
          "vendor": {
            "type": "string",
            "description": "Anti-bot system, when recognised: `cloudflare`, `datadome`, `akamai`, `perimeterx`, `kasada`, `imperva`, `shape` (F5), `awswaf`, `amazon`, `google`, `reddit`, `yandex`, `hcaptcha`, `recaptcha` or `unknown`. See \"Reading a block\" in the Web Unlocker guide."
          },
          "hint": {
            "type": "string",
            "description": "Suggestion when blocked, e.g. try the `mobile` tier."
          },
          "clearance": {
            "type": "string",
            "enum": [
              "hit",
              "miss",
              "minted",
              "stale",
              "off"
            ],
            "description": "What the engine did with its per-tenant clearance cache."
          },
          "setCookie": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "cookies": {
            "type": "object",
            "description": "Full cookie jar, only with `returnCookies: true`."
          },
          "exitSessionId": {
            "type": "string"
          },
          "strategy": {
            "type": "object",
            "properties": {
              "startTier": {
                "type": "string",
                "enum": [
                  "tls",
                  "browser"
                ]
              },
              "hedged": {
                "type": "boolean"
              }
            }
          },
          "rendered": {
            "type": "boolean",
            "description": "The headless browser produced the answer."
          },
          "escalated": {
            "type": "boolean",
            "description": "The browser was reached by escalation after blocked TLS attempts."
          },
          "mode": {
            "type": "string",
            "enum": [
              "auto",
              "tls",
              "browser"
            ],
            "description": "The `mode` the call ran with."
          },
          "tier_served": {
            "type": "string",
            "enum": [
              "tls",
              "browser"
            ],
            "description": "The tier that produced the answer (same as the `x-qp-tier-served` header). On a cache hit: the tier that produced the stored page."
          },
          "format": {
            "type": "string",
            "enum": [
              "html",
              "markdown",
              "text"
            ],
            "description": "Format `body` was served in."
          },
          "tier": {
            "type": "string",
            "enum": [
              "premium",
              "mobile"
            ]
          },
          "geo": {
            "$ref": "#/components/schemas/Geo"
          },
          "latency_ms": {
            "type": "integer",
            "description": "Milliseconds from the request to the answer, every attempt included (same as `x-qp-latency-ms`)."
          },
          "cache": {
            "type": "string",
            "enum": [
              "hit",
              "miss",
              "off"
            ],
            "description": "`hit`: answered from the cache, no bytes moved; `miss`: `cache_ttl` was set and the page was fetched; `off`: no `cache_ttl`. Same as the `x-qp-cache` header."
          },
          "cached_at": {
            "type": "string",
            "format": "date-time",
            "description": "On a hit: when the copy was stored. Same as the `x-qp-cached-at` header."
          },
          "attempt_log": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/UnlockAttempt"
            },
            "description": "One entry per attempt, in order (same data as the `x-qp-attempt-log` header)."
          },
          "usage": {
            "type": "object",
            "description": "Unlocker usage is metered in bytes against the tier's prepaid GB, not the wallet.",
            "properties": {
              "bytes": {
                "type": "integer",
                "description": "Bytes the exit network moved for this call: every attempt and tier, not only the body returned."
              },
              "unlock_gb_remaining": {
                "type": "number",
                "description": "GB left on the tier after this call."
              },
              "unlock_gb_purchased": {
                "type": "number",
                "description": "GB bought on the tier, lifetime of the current package."
              }
            }
          },
          "cost": {
            "$ref": "#/components/schemas/UnlockCost"
          }
        }
      },
      "AiAgentResult": {
        "type": "object",
        "required": [
          "data",
          "steps",
          "model"
        ],
        "properties": {
          "data": {
            "description": "The extracted JSON (shape follows the task)."
          },
          "steps": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "One entry per page the agent fetched."
          },
          "searches": {
            "type": "integer"
          },
          "mapped": {
            "type": "integer"
          },
          "model": {
            "type": "string"
          },
          "bytes": {
            "type": "integer"
          },
          "usage": {
            "description": "LLM token usage (`input_tokens`, `output_tokens`) merged with the billing block (`cost_usd`, `free_usd`, `paid_usd`)."
          }
        },
        "additionalProperties": true
      },
      "AiFinderResult": {
        "type": "object",
        "description": "Shared shape of the AI Places and AI Shopping finders.",
        "properties": {
          "places": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Places finder only."
          },
          "products": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Shopping finder only."
          },
          "total": {
            "type": "integer"
          },
          "enriched": {
            "type": "integer",
            "description": "Places finder only: knowledge-panel lookups performed."
          },
          "queries": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The searches the model crafted."
          },
          "searches": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "summary": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "usage": {
            "description": "LLM token usage merged with the billing block."
          }
        },
        "additionalProperties": true
      },
      "AiVisibilityResult": {
        "type": "object",
        "required": [
          "url",
          "finalUrl",
          "domain",
          "score",
          "checks",
          "topFixes",
          "access",
          "content",
          "structure"
        ],
        "properties": {
          "url": {
            "type": "string"
          },
          "finalUrl": {
            "type": "string"
          },
          "domain": {
            "type": "string"
          },
          "score": {
            "type": "object",
            "properties": {
              "overall": {
                "type": "number"
              },
              "pillars": {
                "type": "object",
                "additionalProperties": {
                  "type": "number"
                }
              },
              "scoredPillars": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "blockers": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Checks whose failure caps the overall (blocked crawler, noindex, no text)."
              },
              "uncapped": {
                "type": "number"
              }
            }
          },
          "checks": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "pillar": {
                  "type": "string"
                },
                "status": {
                  "type": "string"
                },
                "weight": {
                  "type": "number"
                },
                "title": {
                  "type": "string"
                },
                "detail": {
                  "type": "string"
                },
                "fix": {
                  "type": "string"
                },
                "evidence": {}
              }
            }
          },
          "topFixes": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "access": {
            "type": "object",
            "description": "robots.txt verdict per AI crawler, Content-Signal, sitemaps, llms.txt, the fetch that identified itself as an AI crawler."
          },
          "content": {
            "type": "object",
            "description": "No-JS vs rendered view, readability metrics."
          },
          "structure": {
            "type": "object",
            "description": "JSON-LD types, entities, author, dates, heading outline."
          },
          "retrievability": {
            "type": "object",
            "description": "Google rank for the page's own H1 question and index status (2 SERPs), unless `no_retrieval`."
          },
          "citations": {
            "type": "object",
            "description": "Only with `queries`: `rows` (one per query × engine: cited / mentioned / rank / error), `usage`, share of voice."
          },
          "offsite": {
            "type": "object",
            "description": "Only with `offsite: true`: brand presence per platform."
          },
          "geo": {
            "type": "object"
          },
          "billing": {
            "type": "object",
            "properties": {
              "citation_calls_billed": {
                "type": "integer"
              },
              "offsite_serps_billed": {
                "type": "integer"
              }
            }
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          }
        },
        "additionalProperties": true
      },
      "SeoView": {
        "type": "object",
        "properties": {
          "status": {
            "type": "integer"
          },
          "title": {
            "type": [
              "string",
              "null"
            ]
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "canonical": {
            "type": [
              "string",
              "null"
            ]
          },
          "h1": {
            "type": [
              "string",
              "null"
            ]
          },
          "wordCount": {
            "type": "integer"
          },
          "hasContent": {
            "type": "boolean"
          }
        }
      },
      "SeoAuditResult": {
        "type": "object",
        "required": [
          "url",
          "finalUrl",
          "noJs",
          "render",
          "diff",
          "meta",
          "durationMs"
        ],
        "properties": {
          "url": {
            "type": "string"
          },
          "finalUrl": {
            "type": "string"
          },
          "noJs": {
            "$ref": "#/components/schemas/SeoView"
          },
          "render": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/SeoView"
              },
              {
                "type": "object",
                "properties": {
                  "error": {
                    "type": "string"
                  }
                },
                "required": [
                  "error"
                ]
              }
            ],
            "description": "Rendered view, or `{error}` when the render pass was skipped or failed (then the call bills the plain scrape price)."
          },
          "diff": {
            "type": "object",
            "properties": {
              "titleChanged": {
                "type": [
                  "boolean",
                  "null"
                ]
              },
              "descriptionChanged": {
                "type": [
                  "boolean",
                  "null"
                ]
              },
              "h1OnlyInRender": {
                "type": [
                  "boolean",
                  "null"
                ]
              },
              "canonicalMissingNoJs": {
                "type": [
                  "boolean",
                  "null"
                ]
              },
              "contentOnlyInJs": {
                "type": [
                  "boolean",
                  "null"
                ]
              }
            }
          },
          "meta": {
            "type": "object",
            "properties": {
              "robots": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "ogTitle": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "ogUrl": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "twitterCard": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "jsonldTypes": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "durationMs": {
            "type": "integer"
          },
          "geo": {
            "type": "object"
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          }
        }
      },
      "CollectorHealth": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "healthy",
              "degraded",
              "unknown"
            ]
          },
          "checked_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "latency_ms": {
            "type": [
              "integer",
              "null"
            ]
          },
          "result_count": {
            "type": [
              "integer",
              "null"
            ]
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          },
          "success_rate_24h": {
            "type": [
              "number",
              "null"
            ]
          },
          "last_ok_at": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "CollectorCatalogEntry": {
        "type": "object",
        "description": "One collector. `input_schema` is a JSON Schema object (what to POST to `run_url`); `output_schema.fields` lists the columns of every delivered row.",
        "required": [
          "slug",
          "name",
          "version",
          "category",
          "unit",
          "price",
          "max_results",
          "input_schema",
          "output_schema",
          "examples",
          "health",
          "run_url"
        ],
        "properties": {
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "category": {
            "type": "string",
            "enum": [
              "search",
              "seo",
              "social",
              "apps",
              "real_estate",
              "local",
              "jobs",
              "news",
              "ecommerce",
              "travel",
              "leads",
              "company",
              "classifieds",
              "finance",
              "dev",
              "knowledge",
              "gaming",
              "osint",
              "research"
            ]
          },
          "category_label": {
            "type": "string"
          },
          "tagline": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "unit": {
            "type": "string",
            "description": "What one billed result is (place, review, job, …)."
          },
          "engines": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "serp",
                "extract",
                "map",
                "ai"
              ]
            }
          },
          "price": {
            "type": "object",
            "properties": {
              "list_usd": {
                "type": "number"
              },
              "your_usd": {
                "type": "number",
                "description": "List price × your tier discount — what you pay per delivered result."
              },
              "price_key": {
                "type": "string",
                "description": "The pricing.json key (`collector_<slug>`, or `collector_result` as fallback)."
              },
              "per_1k_usd": {
                "type": "number"
              },
              "min_billable_results": {
                "type": "integer",
                "description": "Floor in units for a run that delivers anything; 0 = pure per-row."
              },
              "min_run_usd": {
                "type": "number"
              }
            }
          },
          "max_results": {
            "type": "integer",
            "description": "Hard cap on rows per run."
          },
          "input_schema": {
            "type": "object",
            "description": "JSON Schema (type object, properties, required, additionalProperties: false)."
          },
          "output_schema": {
            "type": "object",
            "properties": {
              "fields": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string"
                    },
                    "nullable": {
                      "type": "boolean"
                    },
                    "description": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "examples": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "title": {
                  "type": "string"
                },
                "input": {
                  "type": "object"
                }
              }
            }
          },
          "health_input": {
            "type": "object"
          },
          "health": {
            "$ref": "#/components/schemas/CollectorHealth"
          },
          "run_url": {
            "type": "string"
          },
          "changelog": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "version": {
                  "type": "string"
                },
                "date": {
                  "type": "string"
                },
                "tldr": {
                  "type": "string",
                  "description": "One line on what the release changes for you. Optional: present on recent releases only."
                },
                "notes": {
                  "type": "string"
                }
              }
            },
            "description": "Single-collector view only."
          },
          "health_history": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Single-collector view only: last 24 probes."
          }
        }
      },
      "CollectorRun": {
        "type": "object",
        "required": [
          "run_id",
          "slug",
          "version",
          "status",
          "input",
          "count",
          "partial",
          "cost",
          "error",
          "created_at",
          "started_at",
          "finished_at"
        ],
        "properties": {
          "run_id": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "done",
              "failed"
            ]
          },
          "input": {
            "type": "object"
          },
          "count": {
            "type": "integer",
            "description": "Delivered rows."
          },
          "partial": {
            "type": "boolean",
            "description": "The run stopped before `max_results` (deadline, a page failed, …)."
          },
          "partial_reason": {
            "type": "string"
          },
          "cost": {
            "type": "object",
            "properties": {
              "usd": {
                "type": "number"
              },
              "unit_usd": {
                "type": "number"
              },
              "unit": {
                "type": "string"
              },
              "billed": {
                "type": "boolean"
              }
            }
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          },
          "error_kind": {
            "type": "string",
            "enum": [
              "input"
            ],
            "description": "`input` = retrying the same input cannot help (HTTP 422)."
          },
          "dropped": {
            "type": "object",
            "description": "Lead collectors only: rows withheld by the removal list, your exclusion list or because already delivered to you."
          },
          "results": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Delivered rows (columns per `output_schema`). Absent in list views."
          },
          "failed": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "notes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "deduplicated": {
            "type": "boolean",
            "description": "An identical run inside the dedup window was served instead of starting a new one — nothing new was charged."
          },
          "created_at": {
            "type": "string"
          },
          "started_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "finished_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          }
        }
      },
      "DatasetSummary": {
        "type": "object",
        "description": "One row of the dataset list.",
        "properties": {
          "id": {
            "type": "string"
          },
          "jobId": {
            "type": "string"
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "prompt": {
            "type": "string"
          },
          "columns": {
            "type": "string",
            "description": "JSON-encoded column list."
          },
          "country": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "running",
              "completed",
              "failed",
              "cancelled",
              "budget_reached",
              "expired"
            ]
          },
          "rowCount": {
            "type": "integer"
          },
          "billableRows": {
            "type": "integer"
          },
          "refresh": {
            "type": "boolean"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "completedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "purgedAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "costUsd": {
            "type": [
              "number",
              "null"
            ],
            "description": "Real cost once settled (budget charge minus refund); null while running."
          },
          "stored": {
            "type": "boolean",
            "description": "Rows are stored and the run can be reopened/exported."
          },
          "storedRows": {
            "type": [
              "integer",
              "null"
            ]
          },
          "storedBytes": {
            "type": [
              "integer",
              "null"
            ]
          },
          "purged": {
            "type": "boolean"
          },
          "dropped": {
            "type": [
              "object",
              "null"
            ]
          }
        }
      },
      "DatasetJob": {
        "type": "object",
        "description": "Live job view (from the service) or the stored view of a finished run (`source: storage`, no progress/steps).",
        "required": [
          "id",
          "status",
          "prompt",
          "columns",
          "row_count",
          "billable_rows"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "running",
              "completed",
              "failed",
              "cancelled",
              "budget_reached"
            ]
          },
          "prompt": {
            "type": "string"
          },
          "columns": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "files": {
            "type": [
              "object",
              "null"
            ]
          },
          "progress": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "queries_run": {
                "type": "integer"
              },
              "sites_mapped": {
                "type": "integer"
              },
              "pages_scraped": {
                "type": "integer"
              },
              "pages_failed": {
                "type": "integer"
              },
              "rows": {
                "type": "integer"
              },
              "dropped_offtarget": {
                "type": "integer"
              },
              "cost_so_far_usd": {
                "type": "number"
              }
            }
          },
          "limits": {
            "type": "object",
            "properties": {
              "max_rows": {
                "type": "integer"
              },
              "max_pages": {
                "type": "integer"
              },
              "max_cost_usd": {
                "type": "number"
              }
            }
          },
          "entity": {
            "type": [
              "string",
              "null"
            ]
          },
          "billable": {
            "type": "object",
            "properties": {
              "row_fees_usd": {
                "type": "number"
              },
              "unit_usd": {
                "type": "number"
              }
            }
          },
          "steps": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "phase": {
                  "type": "string",
                  "enum": [
                    "plan",
                    "search",
                    "map",
                    "scrape",
                    "extract",
                    "consolidate"
                  ]
                },
                "detail": {
                  "type": "string"
                },
                "ts": {
                  "type": "integer"
                }
              }
            }
          },
          "rows": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "fields": {
                  "type": "object"
                },
                "_source_url": {
                  "type": "string"
                },
                "_fetched_at": {
                  "type": "string"
                },
                "confidence": {
                  "type": "number"
                },
                "billed_fields": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "fee_usd": {
                  "type": "number"
                },
                "low_confidence": {
                  "type": "boolean"
                }
              }
            },
            "description": "Omitted with `mode=summary`; from `since` onwards otherwise."
          },
          "dropped": {
            "type": [
              "object",
              "null"
            ]
          },
          "row_count": {
            "type": "integer"
          },
          "billable_rows": {
            "type": "integer"
          },
          "nextCursor": {
            "type": "integer"
          },
          "createdAt": {},
          "finishedAt": {},
          "error": {
            "type": "string"
          },
          "source": {
            "type": "string",
            "enum": [
              "storage"
            ]
          },
          "purged": {
            "type": "boolean"
          },
          "rowsUnavailable": {
            "type": "boolean"
          }
        },
        "additionalProperties": true
      },
      "ParserPreset": {
        "type": "object",
        "required": [
          "id",
          "name",
          "parser",
          "version",
          "autoHeal",
          "createdAt",
          "updatedAt",
          "stats",
          "history"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "sourceUrl": {
            "type": "string"
          },
          "fields": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "render": {
            "type": "boolean"
          },
          "parser": {
            "$ref": "#/components/schemas/ExtractSchema"
          },
          "version": {
            "type": "integer"
          },
          "autoHeal": {
            "type": "boolean"
          },
          "createdAt": {
            "type": "integer"
          },
          "updatedAt": {
            "type": "integer"
          },
          "lastHealAt": {
            "type": [
              "integer",
              "null"
            ]
          },
          "stats": {
            "type": "object",
            "properties": {
              "runs": {
                "type": "integer"
              },
              "lastRunAt": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "fields": {
                "type": "object"
              },
              "recent": {
                "type": "array",
                "items": {
                  "type": "number"
                }
              }
            }
          },
          "history": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "version": {
                  "type": "integer"
                },
                "parser": {
                  "type": "object"
                },
                "at": {
                  "type": "integer"
                },
                "reason": {
                  "type": "string"
                },
                "coverage": {
                  "type": "number"
                }
              }
            }
          }
        }
      },
      "PresetStatsView": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "version": {
            "type": "integer"
          },
          "runs": {
            "type": "integer"
          },
          "lastRunAt": {
            "type": [
              "integer",
              "null"
            ]
          },
          "successRateByField": {
            "type": "object",
            "additionalProperties": {
              "type": "number"
            }
          },
          "recentCoverage": {
            "type": [
              "number",
              "null"
            ]
          },
          "decayed": {
            "type": "boolean"
          },
          "autoHeal": {
            "type": "boolean"
          },
          "lastHealAt": {
            "type": [
              "integer",
              "null"
            ]
          }
        }
      },
      "HealResult": {
        "type": "object",
        "required": [
          "healed",
          "reason",
          "version"
        ],
        "properties": {
          "healed": {
            "type": "boolean"
          },
          "reason": {
            "type": "string"
          },
          "version": {
            "type": "integer"
          },
          "coverageBefore": {
            "type": [
              "number",
              "null"
            ]
          },
          "coverageAfter": {
            "type": "number"
          },
          "parser": {
            "$ref": "#/components/schemas/ExtractSchema"
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          }
        }
      },
      "GenerateParserResult": {
        "type": "object",
        "required": [
          "parser",
          "report",
          "missed",
          "coverage"
        ],
        "properties": {
          "parser": {
            "$ref": "#/components/schemas/ExtractSchema",
            "description": "Ready to pass as `extract` on any later scrape of this layout."
          },
          "report": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "field": {
                  "type": "string"
                },
                "selector": {
                  "type": "string"
                },
                "sample": {},
                "missed": {
                  "type": "boolean"
                }
              }
            }
          },
          "missed": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "coverage": {
            "type": "number",
            "description": "Fraction of requested fields that produced a value (0–1). 0 = not charged."
          },
          "repaired": {
            "type": "boolean"
          },
          "usage": {}
        },
        "additionalProperties": true
      },
      "ProxyPlan": {
        "type": "object",
        "description": "One proxy service on the account. `orderId` is what the generate and whitelist endpoints take.",
        "properties": {
          "id": {
            "type": "string"
          },
          "orderId": {
            "type": "string"
          },
          "planName": {
            "type": "string"
          },
          "planType": {
            "type": "string",
            "enum": [
              "residentialbasic",
              "residentialpremium",
              "resiprivate",
              "isp",
              "isppremium",
              "datacenter",
              "datacentertraffic",
              "ipv6",
              "mobile",
              "mobile_v2"
            ]
          },
          "planTypeName": {
            "type": "string"
          },
          "username": {
            "type": "string"
          },
          "password": {
            "type": "string"
          },
          "tier": {
            "type": "string"
          },
          "bandwidth": {
            "type": "number",
            "description": "GB purchased; 0 = unlimited."
          },
          "bandwidthGB": {
            "type": "number"
          },
          "bandwidthLeft": {
            "type": "number"
          },
          "bandwidthLeftGB": {
            "type": "number"
          },
          "bandwidthUsed": {
            "type": "number"
          },
          "bandwidthUsedGB": {
            "type": "number"
          },
          "bandwidthUsagePercent": {
            "type": "integer"
          },
          "isUnlimited": {
            "type": "boolean"
          },
          "expiry": {
            "type": "string",
            "format": "date-time"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "isActive": {
            "type": "boolean"
          },
          "isExpired": {
            "type": "boolean"
          },
          "daysRemaining": {
            "type": "integer"
          },
          "hoursRemaining": {
            "type": "integer"
          },
          "ips": {
            "type": "integer"
          },
          "whitelistSlots": {
            "type": "integer"
          },
          "whitelistedIPs": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "region": {
            "type": "string"
          },
          "speed": {},
          "highConcurrency": {
            "type": "boolean"
          },
          "highPriority": {
            "type": "boolean"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "GeneratedProxies": {
        "type": "object",
        "required": [
          "orderId",
          "quantity",
          "protocol",
          "format",
          "rotation",
          "sessionTime",
          "geoTargeting",
          "proxies"
        ],
        "properties": {
          "orderId": {
            "type": "string"
          },
          "quantity": {
            "type": "integer"
          },
          "protocol": {
            "type": "string"
          },
          "format": {
            "type": "string"
          },
          "rotation": {
            "type": "string"
          },
          "sessionTime": {
            "type": "integer"
          },
          "superSticky": {
            "type": "boolean",
            "description": "`true` when the strings were built as super sticky sessions (24 h)."
          },
          "udp": {
            "type": "boolean",
            "description": "`true` when the strings carry the UDP option (Residential Basic, SOCKS5)."
          },
          "geoTargeting": {
            "type": "object",
            "properties": {
              "country": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "state": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "city": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "proxies": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Ready-to-use proxy strings in the requested `format` (credentials included)."
          },
          "rotatingProxy": {
            "type": "string",
            "description": "Plans that expose a single rotating endpoint."
          },
          "bandwidth": {
            "type": "number"
          },
          "bandwidthLeft": {
            "type": "number"
          },
          "trafficUsed": {
            "type": "number"
          },
          "whitelist": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "ips": {
            "type": "integer"
          },
          "daysRemaining": {
            "type": "integer"
          },
          "hoursRemaining": {
            "type": "integer"
          },
          "port": {},
          "gateway": {
            "type": "string",
            "enum": [
              "ww",
              "us",
              "eu",
              "as"
            ]
          },
          "region": {
            "type": "string"
          },
          "ip": {
            "type": "string"
          },
          "ipAddresses": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "currentIpInfo": {
            "type": [
              "object",
              "null"
            ]
          },
          "expiry": {}
        },
        "additionalProperties": true
      },
      "IpInfo": {
        "type": "object",
        "description": "Location and network of an IP, from ipinfo.io. Text the source does not give is an empty string.",
        "properties": {
          "ip": {
            "type": "string",
            "description": "The address looked up, in canonical form."
          },
          "country": {
            "type": "string",
            "description": "Country name in English."
          },
          "countryCode": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2 code, upper case."
          },
          "flag": {
            "type": "string",
            "description": "Flag emoji of `countryCode`."
          },
          "region": {
            "type": "string",
            "description": "Region or state."
          },
          "regionCode": {
            "type": "string",
            "deprecated": true,
            "description": "Always an empty string: the source gives no region code. Kept so existing clients keep working; use `region`."
          },
          "city": {
            "type": "string"
          },
          "zip": {
            "type": "string",
            "description": "Postal code."
          },
          "lat": {
            "type": [
              "number",
              "null"
            ],
            "description": "Latitude of the city area, never of a street."
          },
          "lon": {
            "type": [
              "number",
              "null"
            ],
            "description": "Longitude of the city area, never of a street."
          },
          "timezone": {
            "type": "string",
            "description": "IANA time zone, e.g. `Europe/Istanbul`."
          },
          "isp": {
            "type": "string",
            "description": "Network operator registered for the ASN."
          },
          "org": {
            "type": "string",
            "description": "Same value as `isp`."
          },
          "as": {
            "type": "string",
            "description": "ASN and operator, e.g. `AS15169 Google LLC`."
          }
        }
      },
      "UsageDay": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "format": "date"
          },
          "requests": {
            "type": "integer"
          },
          "by_type": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            },
            "description": "Requests per query type (extract, google, bing, map, crawl, batch, unlock, ai, …)."
          },
          "proxy_kb": {
            "type": "number"
          },
          "ai_cost_usd": {
            "type": "number"
          },
          "billed_usd": {
            "type": "number",
            "description": "Wallet part of the spend (total − free)."
          },
          "free_usd": {
            "type": "number"
          }
        }
      },
      "BillingStatus": {
        "type": "object",
        "properties": {
          "billing_enabled": {
            "type": "boolean"
          },
          "billed": {
            "type": "boolean",
            "description": "Whether this key's calls are charged (false for admin keys or when billing is off)."
          },
          "balance": {
            "type": "number"
          },
          "tier": {
            "type": "object",
            "properties": {
              "key": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "discount_pct": {
                "type": "number"
              },
              "rate_limit_per_min": {
                "type": "integer"
              }
            }
          },
          "billing_mode": {
            "type": "object",
            "properties": {
              "preference": {
                "type": "string"
              },
              "effective": {
                "type": "string",
                "enum": [
                  "free_first",
                  "balance"
                ]
              },
              "reason": {
                "type": "string"
              },
              "available": {
                "type": "boolean"
              },
              "free_first_rate_limit_per_min": {
                "type": "integer"
              },
              "balance_rate_limit_per_min": {
                "type": "integer"
              },
              "effective_rate_limit_per_min": {
                "type": "integer"
              }
            }
          },
          "free_monthly_usd": {
            "type": "number"
          },
          "free_remaining_usd": {
            "type": "number"
          },
          "free_tier_blocked_reason": {
            "type": "string",
            "description": "Why the allowance is 0; absent when conceded. `disposable_email`: the account's email address is disposable. `first_order_required`: on this account the free allowance starts with the first paid order."
          },
          "ai_token_markup": {
            "type": "number"
          },
          "prices_usd": {
            "type": "object",
            "additionalProperties": {
              "type": "number"
            },
            "description": "The live price list with your tier discount applied — keyed like pricing.json."
          }
        }
      },
      "TrialConfig": {
        "type": "object",
        "required": [
          "brand",
          "enabled",
          "perIpPerDay",
          "perDay",
          "tools"
        ],
        "properties": {
          "brand": {
            "type": "string",
            "enum": [
              "QP",
              "QD"
            ]
          },
          "enabled": {
            "type": "boolean"
          },
          "perIpPerDay": {
            "type": "integer"
          },
          "perDay": {
            "type": "integer"
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "PremiumIspPool": {
        "type": "object",
        "description": "A ready Premium ISP pool: dedicated static IPs of one country, built for one category of sites. 30-day plans. `available` says whether the pool can be bought now; `maxQuantity` is the most IPs one order can take now (at most 200, lower when the pool is short of IPs). A pool with `subnet: true` sells a whole /24 instead: 256 dedicated IPs in one block, one subnet per order (`quantity` must be 256).",
        "properties": {
          "id": {
            "type": "string",
            "description": "Pool id, `premium-<country>-<category>`, ending in `-subnet` for a whole /24. Use it as `poolId`."
          },
          "country": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2."
          },
          "countryName": {
            "type": "string"
          },
          "category": {
            "type": "string",
            "enum": [
              "aio",
              "retail",
              "ipqs",
              "social",
              "pokemon-center",
              "sneaker",
              "ticket"
            ]
          },
          "categoryName": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "days": {
            "type": "integer",
            "const": 30
          },
          "minQuantity": {
            "type": "integer"
          },
          "maxQuantity": {
            "type": "integer",
            "description": "Most IPs one order can take now: at most 200, lower when the pool is short of IPs."
          },
          "available": {
            "type": "boolean"
          },
          "subnet": {
            "type": "boolean",
            "description": "True for a whole /24 subnet: 256 IPs per order, `minQuantity` = `maxQuantity` = 256."
          },
          "stock": {
            "type": [
              "integer",
              "null"
            ],
            "description": "IPs in stock now (a subnet takes 256); null when not reported."
          },
          "features": {
            "type": "object",
            "properties": {
              "dedicated": {
                "type": "boolean"
              },
              "unlimitedBandwidth": {
                "type": "boolean"
              },
              "udp": {
                "type": "boolean"
              },
              "maxSpeedGbps": {
                "type": "integer"
              },
              "cityChoice": {
                "type": "boolean"
              },
              "carrierChoice": {
                "type": "boolean"
              },
              "replacementWithin24hOnRequest": {
                "type": "boolean",
                "description": "IPs blocked by a site of the pool's category can be replaced within 24 hours of purchase, on request to support (not through the API). False for subnets."
              },
              "subnetsOnRequest": {
                "type": "boolean",
                "description": "Whole /24 subnets of this pool can be arranged with support. False on a subnet pool, which is bought through the API."
              }
            }
          }
        }
      },
      "PremiumIspCityCatalog": {
        "type": "object",
        "description": "City plans of one type: plan lengths with their price per IP, and the countries and cities with the IPs in stock. Served from a cache up to `maxAgeSeconds` old; the purchase reads stock again.",
        "properties": {
          "enabled": {
            "type": "boolean"
          },
          "type": {
            "type": "string",
            "enum": [
              "city",
              "fraud-score-0"
            ]
          },
          "udp": {
            "type": "boolean"
          },
          "maxAgeSeconds": {
            "type": "integer"
          },
          "types": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "enum": [
                    "city",
                    "fraud-score-0"
                  ]
                },
                "name": {
                  "type": "string"
                },
                "available": {
                  "type": "boolean"
                }
              }
            }
          },
          "lengths": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "enum": [
                    "1_day",
                    "7_days",
                    "1_month",
                    "2_months",
                    "3_months"
                  ]
                },
                "label": {
                  "type": "string"
                },
                "days": {
                  "type": "integer"
                },
                "perIpPrice": {
                  "type": "number",
                  "description": "Price per IP for the length, before quantity ranges, USD."
                },
                "ranges": {
                  "type": "array",
                  "description": "Price per IP by quantity range.",
                  "items": {
                    "type": "object",
                    "properties": {
                      "from": {
                        "type": "integer"
                      },
                      "to": {
                        "type": "integer"
                      },
                      "price": {
                        "type": "number",
                        "description": "Price per IP in the range, USD."
                      }
                    }
                  }
                },
                "replacementPrice": {
                  "type": "number",
                  "description": "Price of one paid IP swap bought with the plan, USD."
                },
                "minQuantity": {
                  "type": "integer"
                },
                "maxQuantity": {
                  "type": "integer"
                }
              }
            }
          },
          "carrierFeePerIp": {
            "type": "number",
            "description": "Extra per IP when you pick a carrier (`asn`), USD."
          },
          "maxReplacements": {
            "type": "integer",
            "description": "Paid IP swaps you can buy with one plan."
          },
          "paidSwapPrice": {
            "type": "number",
            "description": "USD for one IP swap bought after the purchase, from the plan page or `POST .../replacements` with `pay: true`; flat for this type."
          },
          "siteCheck": {
            "type": "boolean",
            "description": "The optional site test (`siteCheck` on the selection) is offered for this type."
          },
          "guarantees": {
            "type": "object",
            "description": "What every IP of a new plan comes with right now. `autoReplace`: free auto-replace, an IP that stays offline for more than 30 minutes is replaced by itself, same city, same login and password, without using an IP swap; the customer can switch it off for a plan on its dashboard page. `freshIps`: IPs never assigned to your account before, where available. Both `false` when the current inventory does not offer them.",
            "properties": {
              "autoReplace": {
                "type": "boolean"
              },
              "freshIps": {
                "type": "boolean"
              }
            },
            "required": [
              "autoReplace",
              "freshIps"
            ]
          },
          "countries": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "code": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "ISO 3166-1 alpha-2."
                },
                "name": {
                  "type": "string"
                },
                "stock": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "description": "IPs in stock in the country; null when not reported."
                },
                "cities": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "location": {
                        "type": "string",
                        "description": "Pass it as `location`."
                      },
                      "name": {
                        "type": "string"
                      },
                      "stock": {
                        "type": [
                          "integer",
                          "null"
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "PremiumIspCarrier": {
        "type": "object",
        "properties": {
          "asn": {
            "type": "integer",
            "description": "Carrier ASN. Pass it as `asn` to pin the carrier."
          },
          "name": {
            "type": "string"
          },
          "stock": {
            "type": [
              "integer",
              "null"
            ],
            "description": "IPs in stock on this carrier in the city."
          }
        }
      },
      "PremiumIspSelection": {
        "type": "object",
        "description": "What to buy. A pool (`product: pool`) or a city plan (`product: city`).",
        "required": [
          "product",
          "quantity"
        ],
        "properties": {
          "product": {
            "type": "string",
            "enum": [
              "pool",
              "city"
            ]
          },
          "poolId": {
            "type": "string",
            "description": "Pool id from `GET /public/premium-isp/pools` (pool only). A `-subnet` pool buys a whole /24."
          },
          "type": {
            "type": "string",
            "enum": [
              "city",
              "fraud-score-0"
            ],
            "default": "city",
            "description": "City plans only. `fraud-score-0`: every IP is checked for a fraud score of 0 before delivery."
          },
          "length": {
            "type": "string",
            "enum": [
              "1_day",
              "7_days",
              "1_month",
              "2_months",
              "3_months"
            ],
            "description": "City plans only; the lengths on sale are listed by the catalog."
          },
          "location": {
            "type": "string",
            "description": "City plans only: a `location` from the catalog, e.g. `United States - New York City`. Or just the country name from the catalog (e.g. `United States`) for IPs from any city in that country — full-country stock, and it always uses any carrier (no `asn`)."
          },
          "asn": {
            "type": [
              "integer",
              "null"
            ],
            "default": null,
            "description": "City plans only: carrier ASN from `GET /public/premium-isp/cities/carriers`; null = any carrier. Not allowed when `location` is a country name (any city)."
          },
          "udp": {
            "type": "boolean",
            "default": false,
            "description": "City plans only: UDP-capable IPs."
          },
          "ispNameCheck": {
            "type": "boolean",
            "default": false,
            "deprecated": true,
            "description": "City plans only. Deprecated and currently ignored: this free beta is turned off, so the flag has no effect and no IPs are filtered — leave it out. (When on, it delivered only IPs an IP-lookup database lists under an internet provider.)"
          },
          "siteCheck": {
            "type": [
              "object",
              "null"
            ],
            "description": "City plans only, optional. A site test before delivery: every IP must open `url` and answer `expectedStatus` (default 200); IPs that fail are not assigned. Fewer IPs qualify, so delivery can take longer, and when none passes the order fails and is refunded to the balance by itself. A swapped IP is not tested again. Payment-processor domains are blocked on these IPs and always fail.",
            "properties": {
              "url": {
                "type": "string",
                "maxLength": 200,
                "description": "A full http or https address with a public host name, no credentials."
              },
              "expectedStatus": {
                "type": "integer",
                "minimum": 100,
                "maximum": 599,
                "default": 200
              }
            },
            "required": [
              "url"
            ]
          },
          "replacements": {
            "type": "integer",
            "minimum": 0,
            "maximum": 5,
            "default": 0,
            "description": "City plans only: paid IP swaps bought with the plan (they cannot be added later). A swap changes a working IP, for example one a site blocks; an IP that goes offline is replaced free by auto-replace."
          },
          "quantity": {
            "type": "integer",
            "minimum": 1,
            "description": "Number of IPs, within the length's or pool's minQuantity/maxQuantity: exactly 256 for a subnet pool."
          },
          "paymentMethod": {
            "type": "string",
            "enum": [
              "BALANCE"
            ],
            "default": "BALANCE"
          }
        }
      },
      "PremiumIspQuote": {
        "type": "object",
        "description": "Server-side price of a selection. Nothing is reserved (`reserved: false`).",
        "properties": {
          "product": {
            "type": "string",
            "enum": [
              "pool",
              "city"
            ]
          },
          "poolId": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "subnet": {
            "type": "boolean",
            "description": "Pools only: true for a whole /24 subnet (256 IPs)."
          },
          "type": {
            "type": "string"
          },
          "length": {
            "type": "string"
          },
          "days": {
            "type": "integer"
          },
          "location": {
            "type": "string"
          },
          "city": {
            "type": "string",
            "description": "`Any city` when the whole country was chosen."
          },
          "country": {
            "type": "string"
          },
          "anyCity": {
            "type": "boolean",
            "description": "True when the plan is for any city in the country (full-country stock, no carrier)."
          },
          "asn": {
            "type": [
              "integer",
              "null"
            ]
          },
          "carrierName": {
            "type": [
              "string",
              "null"
            ]
          },
          "udp": {
            "type": "boolean"
          },
          "ispNameCheck": {
            "type": "boolean",
            "deprecated": true,
            "description": "Deprecated: the ISP name check beta is off, so this is always false."
          },
          "quantity": {
            "type": "integer"
          },
          "replacements": {
            "type": "integer"
          },
          "perIpPrice": {
            "type": "number",
            "description": "Price per IP, USD."
          },
          "carrierFeePerIp": {
            "type": "number",
            "description": "Carrier fee per IP, USD; charged at purchase and at every renewal of the plan."
          },
          "replacementPrice": {
            "type": "number",
            "description": "Price per IP swap, USD."
          },
          "ipsTotal": {
            "type": "number",
            "description": "IPs subtotal, USD."
          },
          "carrierTotal": {
            "type": "number",
            "description": "Carrier fee subtotal, USD."
          },
          "replacementsTotal": {
            "type": "number",
            "description": "IP swaps subtotal, USD."
          },
          "subtotal": {
            "type": "number",
            "description": "Subtotal, USD."
          },
          "vatRate": {
            "type": "number",
            "description": "VAT percentage: 0 on balance payments."
          },
          "vat": {
            "type": "number",
            "description": "VAT, USD."
          },
          "total": {
            "type": "number",
            "description": "Amount charged to the balance, USD."
          },
          "currency": {
            "type": "string",
            "const": "USD"
          },
          "paymentMethod": {
            "type": "string",
            "const": "BALANCE"
          },
          "balance": {
            "type": "number",
            "description": "Your current balance, USD."
          },
          "sufficientBalance": {
            "type": "boolean"
          },
          "reserved": {
            "type": "boolean",
            "const": false
          },
          "quotedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "PremiumIspOrder": {
        "type": "object",
        "description": "A Premium ISP order, from our records.",
        "properties": {
          "id": {
            "type": "string"
          },
          "product": {
            "type": "string",
            "enum": [
              "pool",
              "city"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "awaiting_payment",
              "provisioning",
              "active",
              "expired",
              "refunded",
              "failed",
              "disabled"
            ],
            "description": "`provisioning`: paid, the IPs are being prepared (poll this order). `refunded`: not delivered, the amount is back on the balance."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "selection": {
            "type": "object",
            "description": "What was bought: the pool (`poolId`, `name`) or the city pick (`type`, `length`, `location`, `city`, `country`, `asn`, `carrierName`, `udp`, `replacements`)."
          },
          "quantity": {
            "type": [
              "integer",
              "null"
            ]
          },
          "days": {
            "type": "integer"
          },
          "region": {
            "type": [
              "string",
              "null"
            ],
            "description": "Same value as `region` in `GET /public/proxies`: the pool id, `premium-isp-city` or `premium-isp-city-fraud-score-0`."
          },
          "expiresAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "daysRemaining": {
            "type": [
              "integer",
              "null"
            ]
          },
          "invoice": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "total": {
                "type": "number",
                "description": "Total, USD."
              },
              "vat": {
                "type": "number"
              },
              "vatRate": {
                "type": "number"
              },
              "paid": {
                "type": "boolean"
              },
              "status": {
                "type": "string"
              },
              "refunded": {
                "type": "boolean"
              }
            }
          },
          "replacements": {
            "type": "object",
            "description": "City plans: paid IP swaps bought, used, being confirmed and left; `offline` lists the IPs that the network marks offline right now.",
            "properties": {
              "bought": {
                "type": "integer"
              },
              "used": {
                "type": "integer"
              },
              "checking": {
                "type": "integer"
              },
              "left": {
                "type": "integer"
              },
              "offline": {
                "type": "array",
                "description": "The plan's IPs that the network marks offline right now, as in `GET .../replacements`. Empty when none.",
                "items": {
                  "$ref": "#/components/schemas/PremiumIspOfflineIp"
                }
              }
            }
          }
        }
      },
      "PremiumIspOfflineIp": {
        "type": "object",
        "description": "One IP of a city plan that the network marks offline.",
        "properties": {
          "ip": {
            "type": "string",
            "description": "The IP address that the network marks offline."
          },
          "pending": {
            "type": "boolean",
            "description": "`true` when the free replacement of this IP is already being confirmed: do not send it again."
          }
        }
      },
      "PremiumIspLines": {
        "type": "object",
        "description": "Proxy lines of an active order, read live.",
        "properties": {
          "protocol": {
            "type": "string",
            "enum": [
              "http",
              "socks5"
            ]
          },
          "format": {
            "type": "string"
          },
          "proxies": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "One line per dedicated IP, in `format`. Every IP has its own login."
          },
          "ipAddresses": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Exit IP of each line."
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "servers": {
            "type": "array",
            "description": "City plans: the connection servers you can pass as `server`, `auto` (the closest server) first. The exit IPs are the same on every server; only the host of the lines changes. Pick the server nearest to where your tools run.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Server id to pass as `server`, e.g. `auto`, `us-east`, `de`, `sg`."
                },
                "label": {
                  "type": "string",
                  "description": "Display name, e.g. `Auto (closest server)`, `US East (Virginia)`, `Frankfurt`, `Singapore`."
                }
              }
            }
          },
          "server": {
            "type": "string",
            "description": "City plans: the connection server these lines use."
          }
        }
      },
      "Ipv6SpeedPlanCatalog": {
        "type": "object",
        "description": "The IPv6 speed plans on sale right now: one entry per speed with the terms sold for it and the price of each cell. A speed missing a term is simply not sold for that term.",
        "properties": {
          "currency": {
            "type": "string",
            "const": "USD"
          },
          "paymentMethod": {
            "type": "string",
            "const": "BALANCE"
          },
          "vatRate": {
            "type": "number",
            "description": "0 on balance payments."
          },
          "terms": {
            "type": "array",
            "items": {
              "type": "integer",
              "enum": [
                1,
                7,
                30
              ]
            },
            "description": "Terms in days that exist in the grid."
          },
          "speeds": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "speedMbps": {
                  "type": "integer"
                },
                "terms": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "days": {
                        "type": "integer",
                        "enum": [
                          1,
                          7,
                          30
                        ]
                      },
                      "price": {
                        "type": "number",
                        "description": "Total for the term, USD."
                      },
                      "planName": {
                        "type": "string",
                        "description": "The name the order and the invoice carry, e.g. `IPv6 Unlimited · 200 Mbps · 7 days`."
                      }
                    }
                  }
                }
              }
            }
          },
          "from": {
            "type": [
              "object",
              "null"
            ],
            "description": "The cheapest cell.",
            "properties": {
              "speedMbps": {
                "type": "integer"
              },
              "days": {
                "type": "integer"
              },
              "price": {
                "type": "number"
              }
            }
          },
          "onRequest": {
            "type": "object",
            "description": "The special plan with no price in the grid.",
            "properties": {
              "speedMbps": {
                "type": "integer",
                "const": 1000
              },
              "price": {
                "type": "null"
              },
              "availability": {
                "type": "string",
                "const": "contact"
              },
              "how": {
                "type": "string"
              }
            }
          }
        }
      },
      "Ipv6Selection": {
        "type": "object",
        "required": [
          "speedMbps",
          "days"
        ],
        "properties": {
          "speedMbps": {
            "type": "integer",
            "description": "A speed of the grid (`GET /public/ipv6/plans`). 1000 answers `CONTACT_REQUIRED`."
          },
          "days": {
            "type": "integer",
            "enum": [
              1,
              7,
              30
            ],
            "description": "The term. Traffic is not metered for the whole term."
          },
          "paymentMethod": {
            "type": "string",
            "enum": [
              "BALANCE"
            ],
            "default": "BALANCE"
          }
        }
      },
      "Ipv6Quote": {
        "type": "object",
        "description": "Server-side price of one cell. Nothing is reserved.",
        "properties": {
          "speedMbps": {
            "type": "integer"
          },
          "days": {
            "type": "integer"
          },
          "planName": {
            "type": "string"
          },
          "trafficMetered": {
            "type": "boolean",
            "const": false
          },
          "subtotal": {
            "type": "number"
          },
          "vatRate": {
            "type": "number"
          },
          "vat": {
            "type": "number"
          },
          "total": {
            "type": "number",
            "description": "What the balance is charged, USD."
          },
          "currency": {
            "type": "string",
            "const": "USD"
          },
          "paymentMethod": {
            "type": "string",
            "const": "BALANCE"
          },
          "sufficientBalance": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Whether the caller's balance covers `total`; null when the balance is not known."
          },
          "reserved": {
            "type": "boolean",
            "const": false
          },
          "quotedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Ipv6Order": {
        "type": "object",
        "description": "An IPv6 speed order, from our records (dashboard and API purchases alike).",
        "properties": {
          "id": {
            "type": "string"
          },
          "product": {
            "type": "string",
            "const": "ipv6-speed"
          },
          "status": {
            "type": "string",
            "enum": [
              "awaiting_payment",
              "provisioning",
              "active",
              "expired",
              "refunded",
              "failed",
              "disabled"
            ],
            "description": "`refunded`: not delivered, the amount is back on the balance. `disabled`: switched off by support."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "speedMbps": {
            "type": [
              "integer",
              "null"
            ]
          },
          "days": {
            "type": [
              "integer",
              "null"
            ]
          },
          "planName": {
            "type": [
              "string",
              "null"
            ]
          },
          "trafficMetered": {
            "type": "boolean",
            "const": false
          },
          "expiresAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "daysRemaining": {
            "type": [
              "integer",
              "null"
            ]
          },
          "channel": {
            "type": "string",
            "enum": [
              "api",
              "dashboard"
            ],
            "description": "Where the order was placed."
          },
          "invoice": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "total": {
                "type": "number",
                "description": "Total, USD."
              },
              "vat": {
                "type": "number"
              },
              "vatRate": {
                "type": "number"
              },
              "paid": {
                "type": "boolean"
              },
              "status": {
                "type": "string"
              },
              "refunded": {
                "type": "boolean"
              }
            }
          }
        }
      },
      "PlanTypeInfo": {
        "type": "object",
        "description": "A plan type the API knows, with its display name and default features. Not every type has plans on sale: `plans` says what can be bought now.",
        "properties": {
          "key": {
            "type": "string",
            "enum": [
              "residentialbasic",
              "residentialpremium",
              "resiprivate",
              "isp",
              "isppremium",
              "datacenter",
              "datacentertraffic",
              "ipv6",
              "mobile",
              "mobile_v2"
            ]
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "features": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "Plan": {
        "type": "object",
        "description": "A plan you can buy with `POST /public/purchase`. Fixed size: `bandwidthGB` of traffic valid for `durationDays`.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Send it as `planId` to `POST /public/purchase`."
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "amount": {
            "type": "number",
            "description": "List price in USD, before any coupon. Purchases from the balance add 0% VAT."
          },
          "planType": {
            "type": "string",
            "enum": [
              "residentialbasic",
              "residentialpremium",
              "resiprivate",
              "isp",
              "isppremium",
              "datacenter",
              "datacentertraffic",
              "ipv6",
              "mobile",
              "mobile_v2"
            ]
          },
          "planTypeName": {
            "type": "string"
          },
          "bandwidth": {
            "type": "number",
            "description": "GB included; 0 = unlimited."
          },
          "bandwidthGB": {
            "type": "number"
          },
          "isUnlimited": {
            "type": "boolean"
          },
          "duration": {
            "type": "integer",
            "description": "Days the plan stays active after purchase."
          },
          "durationDays": {
            "type": "integer"
          },
          "ips": {
            "type": "integer",
            "description": "IPs included (0 on traffic-based plans)."
          },
          "whitelistSlots": {
            "type": "integer",
            "description": "IPs you can whitelist for IP authentication."
          },
          "features": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "region": {
            "type": "string",
            "description": "`Global` unless the plan is tied to a region."
          },
          "speed": {
            "type": "integer",
            "description": "Speed tier in Mbps where the plan has one, else 0."
          },
          "highConcurrency": {
            "type": "boolean"
          },
          "highPriority": {
            "type": "boolean"
          }
        }
      },
      "PurchasedProxy": {
        "type": "object",
        "description": "The plan created by a purchase, with its credentials. `orderId` is what `POST /public/proxies/generate` and the whitelist endpoints take. Fields with no value on a plan type are left out.",
        "properties": {
          "id": {
            "type": "string"
          },
          "orderId": {
            "type": "string"
          },
          "username": {
            "type": "string"
          },
          "password": {
            "type": "string"
          },
          "proxyType": {
            "type": "string",
            "enum": [
              "RESIDENTIAL",
              "DATACENTER",
              "IPV6",
              "MOBILE",
              "MOBILE_V2",
              "ISP"
            ],
            "description": "Product family. For the exact plan type use `planType` from `GET /public/proxies`."
          },
          "region": {
            "type": "string"
          },
          "bandwidth": {
            "type": "number",
            "description": "GB bought; 0 = unlimited."
          },
          "bandwidthLeft": {
            "type": "number"
          },
          "noOfIps": {
            "type": "integer"
          },
          "noOfWhitelistedIps": {
            "type": "integer",
            "description": "Whitelist slots."
          },
          "speed": {
            "type": "integer"
          },
          "highConcurrency": {
            "type": "boolean"
          },
          "highPriority": {
            "type": "boolean"
          },
          "autoRenew": {
            "type": "boolean"
          },
          "autoRenewDays": {
            "type": "integer"
          },
          "autoRenewLastAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "gbReclaimedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "expiry": {
            "type": "string",
            "format": "date-time"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "whitelist_ip": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "Order": {
        "type": "object",
        "description": "One order of the account: a proxy plan (`PROXY`), a balance top-up (`TOPUP`) or another purchase (`SUBSCRIPTION`, `LIST`, `CUSTOM`), with its plan, credentials and invoices. Plans disabled by support are not listed.",
        "properties": {
          "id": {
            "type": "string",
            "description": "For `PROXY` orders, the `orderId` of the generate and whitelist endpoints."
          },
          "type": {
            "type": "string",
            "enum": [
              "PROXY",
              "TOPUP",
              "SUBSCRIPTION",
              "LIST",
              "CUSTOM"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "plan": {
            "type": [
              "object",
              "null"
            ],
            "description": "The plan bought; null on orders without a catalog plan (top-ups, plans configured at checkout).",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "planType": {
                "type": "string"
              },
              "planTypeName": {
                "type": "string"
              },
              "bandwidth": {
                "type": "number"
              },
              "bandwidthGB": {
                "type": "number"
              },
              "duration": {
                "type": "integer",
                "description": "Days."
              },
              "ips": {
                "type": "integer"
              },
              "region": {
                "type": "string",
                "description": "Region label of the plan (`Global` when none), with the same values as `proxy.region`."
              }
            }
          },
          "proxy": {
            "type": [
              "object",
              "null"
            ],
            "description": "The proxy plan created by the order; null until it is delivered and on orders that are not proxies.",
            "properties": {
              "id": {
                "type": "string"
              },
              "username": {
                "type": "string"
              },
              "password": {
                "type": "string"
              },
              "planType": {
                "type": "string"
              },
              "planTypeName": {
                "type": "string"
              },
              "bandwidth": {
                "type": "number"
              },
              "bandwidthGB": {
                "type": "number"
              },
              "bandwidthLeft": {
                "type": "number"
              },
              "bandwidthLeftGB": {
                "type": "number"
              },
              "isUnlimited": {
                "type": "boolean"
              },
              "expiry": {
                "type": "string",
                "format": "date-time"
              },
              "isActive": {
                "type": "boolean"
              },
              "ips": {
                "type": "integer"
              },
              "whitelistedIPs": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "region": {
                "type": "string",
                "description": "Region label of the plan (`Global` when none). Premium ISP city plans report `premium-isp-city`, or `premium-isp-city-fraud-score-0` for Fraud score 0 plans, as `GET /public/proxies` does."
              }
            }
          },
          "invoices": {
            "type": "array",
            "description": "Newest first.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "total": {
                  "type": "number",
                  "description": "USD."
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "CREATED",
                    "PENDING",
                    "PAID",
                    "OVERPAID",
                    "UNDERPAID",
                    "FAILED"
                  ]
                },
                "paid": {
                  "type": "boolean"
                },
                "paidAt": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date-time"
                },
                "createdAt": {
                  "type": "string",
                  "format": "date-time"
                }
              }
            }
          }
        }
      },
      "Balance": {
        "type": "object",
        "properties": {
          "balance": {
            "type": "number",
            "description": "Wallet balance, USD. Proxy purchases and Data API calls are paid from it."
          },
          "balanceUSD": {
            "type": "number",
            "description": "Same value as `balance`."
          },
          "totalSpent": {
            "type": "number",
            "description": "Sum of the paid proxy invoices, USD (top-ups excluded)."
          },
          "totalSpentUSD": {
            "type": "number",
            "description": "Same value as `totalSpent`."
          }
        }
      },
      "GeoCountry": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Lowercase ISO 3166-1 alpha-2 code: send it as `country`. IPv6 also lists `mix` (any country)."
          },
          "name": {
            "type": "string"
          },
          "flag": {
            "type": "string",
            "description": "Flag emoji for display."
          }
        }
      },
      "GeoState": {
        "type": "object",
        "description": "A state or region. Send `code` as `state` (alias `region`).",
        "properties": {
          "code": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "state_code": {
            "type": "string",
            "description": "Residential Premium: same as `code`."
          },
          "state": {
            "type": "string",
            "description": "Residential Premium: same as `name`."
          },
          "country": {
            "type": "string",
            "description": "Residential Basic / traffic-based Datacenter: the country asked for."
          }
        }
      },
      "GeoCity": {
        "type": "object",
        "description": "A city. Residential Premium and Mobile: send `code` as `city`. Residential Basic and traffic-based Datacenter list `name` only: send it as `city` (lower-cased, spaces and punctuation removed on our side).",
        "properties": {
          "code": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "country": {
            "type": "string"
          }
        }
      },
      "GeoAsn": {
        "type": "object",
        "properties": {
          "asn": {
            "type": "string",
            "description": "Autonomous system number: send it as `asn`, with or without the `AS` prefix, together with a `country`."
          },
          "name": {
            "type": "string",
            "description": "Network operator."
          }
        }
      },
      "LocationTree": {
        "type": "object",
        "description": "Location tree keyed by slug: country code → `regions` → `cities`, with the ISPs (or carriers) available at each level. The keys and the `isps[].code` values are exactly what `POST /public/proxies/generate` takes as `country`, `state`, `city` and `isp`.",
        "additionalProperties": {
          "type": "object",
          "properties": {
            "country_name": {
              "type": "string"
            },
            "isps": {
              "type": "array",
              "description": "ISPs (Mobile: carriers) at this level. Send `code` as `isp`.",
              "items": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  }
                }
              }
            },
            "regions": {
              "type": "object",
              "additionalProperties": {
                "type": "object",
                "properties": {
                  "region_name": {
                    "type": "string"
                  },
                  "isps": {
                    "type": "array",
                    "description": "ISPs (Mobile: carriers) at this level. Send `code` as `isp`.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        }
                      }
                    }
                  },
                  "cities": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "object",
                      "properties": {
                        "city_name": {
                          "type": "string"
                        },
                        "zipcodes": {
                          "type": "array",
                          "items": {
                            "type": [
                              "string",
                              "number"
                            ]
                          }
                        },
                        "isps": {
                          "type": "array",
                          "description": "ISPs (Mobile: carriers) at this level. Send `code` as `isp`.",
                          "items": {
                            "type": "object",
                            "properties": {
                              "code": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "DatacenterGateway": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Country of the gateway."
          },
          "name": {
            "type": "string"
          },
          "host": {
            "type": "string"
          },
          "portHttp": {
            "type": "integer"
          },
          "portSocks5": {
            "type": "integer"
          }
        }
      },
      "VideoFrame": {
        "type": "object",
        "description": "One storyboard frame: the seek-bar tile closest to a chosen moment. Low resolution (usually 160×90): scenes and objects are visible, small text is not.",
        "required": [
          "n",
          "t",
          "at",
          "reason",
          "width",
          "height",
          "mime"
        ],
        "properties": {
          "n": {
            "type": "integer",
            "description": "Frame number, matches the `[frame N · m:ss · why]` marker in `content`."
          },
          "t": {
            "type": "number",
            "description": "Second the frame was taken (the storyboard's own grid)."
          },
          "at": {
            "type": "string",
            "description": "The same instant as m:ss or h:mm:ss."
          },
          "reason": {
            "type": "string",
            "enum": [
              "cue",
              "price",
              "chapter",
              "scene",
              "interval"
            ],
            "description": "Why this moment: the speaker points at the screen (cue), a price is said, a chapter starts, the picture changes, or periodic coverage."
          },
          "quote": {
            "type": "string",
            "description": "The words that triggered the frame (cue, price) or the chapter title."
          },
          "width": {
            "type": "integer"
          },
          "height": {
            "type": "integer"
          },
          "mime": {
            "type": "string",
            "const": "image/jpeg"
          },
          "data": {
            "type": "string",
            "description": "base64 JPEG. Absent when the request set `frames: false`."
          }
        }
      },
      "VideoReadResult": {
        "type": "object",
        "description": "What a model needs to understand a video without watching it. `content` is the part to hand to the model: one Markdown timeline with the description, the chapters as headings, the transcript merged into ~20-second blocks stamped `[m:ss]`, and a `[frame N · m:ss · why]` marker where each frame belongs.",
        "required": [
          "video",
          "transcript",
          "chapters",
          "frames",
          "frame_size",
          "format",
          "content",
          "tokens",
          "notes",
          "meta"
        ],
        "properties": {
          "video": {
            "type": "object",
            "required": [
              "platform",
              "id",
              "url",
              "title"
            ],
            "properties": {
              "platform": {
                "type": "string",
                "enum": [
                  "youtube"
                ]
              },
              "id": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "description": "Canonical watch URL."
              },
              "title": {
                "type": "string"
              },
              "channel": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "channel_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "duration_seconds": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "view_count": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "keywords": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "is_live": {
                "type": "boolean"
              },
              "thumbnail": {
                "type": "string"
              }
            }
          },
          "transcript": {
            "type": "object",
            "required": [
              "source",
              "language",
              "available"
            ],
            "properties": {
              "source": {
                "type": "string",
                "enum": [
                  "captions",
                  "captions_asr",
                  "none"
                ],
                "description": "`captions` = a track the author uploaded, `captions_asr` = the platform's automatic captions, `none` = no transcript (the timeline then carries only chapters and frames)."
              },
              "language": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Language of the transcript: the one spoken in the video unless `languages` asked for another track."
              },
              "available": {
                "type": "array",
                "description": "Every caption track the video offers.",
                "items": {
                  "type": "object",
                  "required": [
                    "code",
                    "kind"
                  ],
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "kind": {
                      "type": "string",
                      "enum": [
                        "manual",
                        "asr"
                      ]
                    }
                  }
                }
              },
              "segments": {
                "type": "array",
                "description": "The raw timed cues, only when the request set `segments: true`.",
                "items": {
                  "type": "object",
                  "required": [
                    "start",
                    "duration",
                    "text"
                  ],
                  "properties": {
                    "start": {
                      "type": "number"
                    },
                    "duration": {
                      "type": "number"
                    },
                    "text": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "chapters": {
            "type": "array",
            "description": "The chapters the author wrote in the description (`0:00 Intro`…), in order.",
            "items": {
              "type": "object",
              "required": [
                "start",
                "title"
              ],
              "properties": {
                "start": {
                  "type": "number"
                },
                "title": {
                  "type": "string"
                }
              }
            }
          },
          "frames": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/VideoFrame"
            }
          },
          "frame_size": {
            "type": [
              "object",
              "null"
            ],
            "description": "Size of the frames and the seconds between two storyboard tiles; null when the video has no storyboard (live, very short, or not processed yet).",
            "properties": {
              "width": {
                "type": "integer"
              },
              "height": {
                "type": "integer"
              },
              "interval": {
                "type": "number"
              }
            }
          },
          "format": {
            "type": "string",
            "const": "markdown"
          },
          "content": {
            "type": "string",
            "description": "The timeline to give the model, in reading order."
          },
          "tokens": {
            "type": "object",
            "required": [
              "estimated",
              "full",
              "truncated",
              "estimator"
            ],
            "properties": {
              "estimated": {
                "type": "integer",
                "description": "Tokens of `content` as returned."
              },
              "full": {
                "type": "integer",
                "description": "Tokens of the whole timeline before any `max_tokens` trim."
              },
              "truncated": {
                "type": "boolean"
              },
              "estimator": {
                "type": "string",
                "const": "chars/4 heuristic"
              }
            }
          },
          "notes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "What to know about this read: automatic captions, no storyboard, text trimmed to `max_tokens`."
          },
          "meta": {
            "type": "object",
            "required": [
              "bytes",
              "via_proxy"
            ],
            "properties": {
              "bytes": {
                "type": "integer",
                "description": "Bytes fetched from the platform (player payload, captions, storyboard sheets)."
              },
              "via_proxy": {
                "type": "boolean",
                "description": "True when the read went through a residential exit after the direct attempt was refused."
              }
            }
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          }
        }
      },
      "RotationResult": {
        "type": "object",
        "description": "A restarted sticky session. The next request on the same proxy string gets a new IP.",
        "required": [
          "rotated",
          "orderId",
          "sessionId",
          "port",
          "protocol",
          "rotatedAt",
          "nextAllowedAt"
        ],
        "properties": {
          "rotated": {
            "type": "boolean",
            "const": true
          },
          "orderId": {
            "type": "string"
          },
          "sessionId": {
            "type": "string",
            "description": "Session of the sticky string."
          },
          "port": {
            "type": "integer",
            "description": "Port of the sticky string."
          },
          "protocol": {
            "type": "string",
            "enum": [
              "http",
              "socks5"
            ]
          },
          "rotatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "nextAllowedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Earliest time this session can rotate again (10 seconds later)."
          }
        }
      },
      "RotationLink": {
        "type": "object",
        "description": "A rotation link of one sticky session. The token itself is shown only when the link is created.",
        "required": [
          "id",
          "sessionId",
          "port",
          "protocol",
          "tokenHint",
          "useCount",
          "createdAt",
          "revoked"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Link id, used to revoke it.",
            "example": "rlk_3f9a1c7e5b2d4a6c8e0f1a2b"
          },
          "sessionId": {
            "type": "string"
          },
          "port": {
            "type": "integer"
          },
          "protocol": {
            "type": "string",
            "enum": [
              "http",
              "socks5"
            ]
          },
          "label": {
            "type": [
              "string",
              "null"
            ],
            "description": "Your own name for the link, such as the profile it belongs to."
          },
          "tokenHint": {
            "type": "string",
            "description": "Last 4 characters of the token, to tell links apart.",
            "example": "1d0e"
          },
          "useCount": {
            "type": "integer",
            "description": "Successful rotations through this link."
          },
          "lastUsedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "revoked": {
            "type": "boolean"
          },
          "revokedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "RotationLinkCreated": {
        "allOf": [
          {
            "$ref": "#/components/schemas/RotationLink"
          },
          {
            "type": "object",
            "required": [
              "url",
              "token"
            ],
            "properties": {
              "url": {
                "type": "string",
                "format": "uri",
                "description": "The rotation link. Shown once: store it now. Anyone with it can rotate this session."
              },
              "token": {
                "type": "string",
                "pattern": "^rl_[a-f0-9]{64}$",
                "description": "The token at the end of `url`, shown once. Only a hash is kept."
              }
            }
          }
        ]
      },
      "RotateRequest": {
        "type": "object",
        "description": "The sticky session to restart: send `proxy`, or `sessionId` with `protocol` (or `port`).",
        "properties": {
          "proxy": {
            "type": "string",
            "maxLength": 2048,
            "description": "A sticky proxy string of this plan, exactly as `generate` returned it (any format)."
          },
          "sessionId": {
            "type": "string",
            "pattern": "^[A-Za-z0-9]{1,32}$",
            "description": "Instead of `proxy`: the session of your sticky string."
          },
          "protocol": {
            "type": "string",
            "enum": [
              "http",
              "socks5"
            ],
            "default": "http",
            "description": "With `sessionId`: the protocol of your sticky string."
          },
          "port": {
            "type": "integer",
            "description": "With `sessionId`, instead of `protocol`: the port of your sticky string."
          }
        }
      },
      "CreateRotationLinksRequest": {
        "type": "object",
        "description": "The sticky sessions to create links for: `proxy`, `proxies` (up to 100 strings, one link each), or `sessionId` with `protocol` (or `port`).",
        "properties": {
          "proxy": {
            "type": "string",
            "maxLength": 2048,
            "description": "A sticky proxy string of this plan, exactly as `generate` returned it (any format)."
          },
          "sessionId": {
            "type": "string",
            "pattern": "^[A-Za-z0-9]{1,32}$",
            "description": "Instead of `proxy`: the session of your sticky string."
          },
          "protocol": {
            "type": "string",
            "enum": [
              "http",
              "socks5"
            ],
            "default": "http",
            "description": "With `sessionId`: the protocol of your sticky string."
          },
          "port": {
            "type": "integer",
            "description": "With `sessionId`, instead of `protocol`: the port of your sticky string."
          },
          "proxies": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "type": "string",
              "maxLength": 2048
            },
            "description": "Several sticky proxy strings of this plan: one link per string."
          },
          "label": {
            "type": "string",
            "maxLength": 64,
            "description": "Optional name stored on every link created by this call: letters, digits, spaces and . _ : # / -"
          }
        }
      },
      "AgentAuthError": {
        "type": "object",
        "description": "Error body of the agent registration endpoints (OAuth style).",
        "required": [
          "error",
          "error_description"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Machine code: `invalid_request`, `anonymous_not_enabled`, `invalid_email`, `human_verification_required`, `rate_limited`, `agent_registration_disabled`, `temporarily_unavailable`, `invalid_code`, `claim_expired`, `too_many_attempts`."
          },
          "error_description": {
            "type": "string"
          },
          "register_human": {
            "type": "string",
            "format": "uri",
            "description": "Where a person registers in a browser, when the agent cannot continue."
          },
          "register_uri": {
            "type": "string",
            "format": "uri",
            "description": "Where to start the registration again."
          },
          "auth_md": {
            "type": "string",
            "format": "uri",
            "description": "The agent guide."
          },
          "retry_after": {
            "type": "integer",
            "description": "Seconds to wait (also in the `Retry-After` header)."
          },
          "attempts_remaining": {
            "type": "integer",
            "description": "Wrong codes still allowed before the registration is cancelled."
          }
        }
      },
      "AgentAuthPending": {
        "type": "object",
        "description": "Registration started: a 6-digit code is in the person's mailbox.",
        "required": [
          "status",
          "registration_type",
          "claim_uri",
          "expires_in"
        ],
        "properties": {
          "status": {
            "type": "string",
            "const": "pending"
          },
          "registration_type": {
            "type": "string",
            "const": "verified_email"
          },
          "claim_uri": {
            "type": "string",
            "format": "uri",
            "description": "Where to exchange the code for the key (step 2)."
          },
          "expires_in": {
            "type": "integer",
            "description": "Seconds the code stays valid (600)."
          },
          "interval": {
            "type": "integer",
            "description": "Always 0: there is nothing to poll, the person gives the code to the agent."
          },
          "message": {
            "type": "string",
            "description": "What to do next, written for the agent."
          }
        }
      },
      "AgentAuthCredential": {
        "type": "object",
        "description": "The API key, returned once.",
        "required": [
          "credential_type",
          "api_key",
          "key_prefix",
          "account_status",
          "email"
        ],
        "properties": {
          "credential_type": {
            "type": "string",
            "const": "api_key"
          },
          "api_key": {
            "type": "string",
            "description": "`qd_live_` + 64 hex characters. Shown once, never emailed: keep it in an environment variable."
          },
          "key_prefix": {
            "type": "string",
            "description": "The first characters of the key, as the dashboard lists it."
          },
          "account_status": {
            "type": "string",
            "enum": [
              "created",
              "existing"
            ],
            "description": "`created`: a new account was opened for that email. `existing`: the email already had an account and the key was added to it."
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "usage": {
            "type": "object",
            "properties": {
              "header": {
                "type": "string"
              },
              "api_base": {
                "type": "string",
                "format": "uri"
              }
            }
          },
          "docs": {
            "type": "string",
            "format": "uri"
          },
          "auth_md": {
            "type": "string",
            "format": "uri"
          },
          "note": {
            "type": "string"
          }
        }
      },
      "UcpMessage": {
        "type": "object",
        "description": "A UCP message attached to a checkout document.",
        "required": [
          "type",
          "content"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "error",
              "warning",
              "info"
            ]
          },
          "code": {
            "type": "string",
            "description": "Machine code, e.g. `requires_buyer_review`, `balance_available`, `vat_rule`, `order_created`, `payment_instrument_unavailable`, `payment_failed`, `purchase_failed`."
          },
          "path": {
            "type": "string",
            "description": "JSONPath of the field the message is about (errors only)."
          },
          "content": {
            "type": "string"
          },
          "severity": {
            "type": "string",
            "enum": [
              "recoverable",
              "requires_buyer_input",
              "requires_buyer_review",
              "fatal"
            ]
          }
        }
      },
      "UcpErrorDocument": {
        "type": "object",
        "description": "UCP error envelope: `ucp.status` is `error` and `messages[0]` carries the code.",
        "required": [
          "ucp",
          "messages"
        ],
        "properties": {
          "ucp": {
            "type": "object",
            "properties": {
              "version": {
                "type": "string"
              },
              "status": {
                "type": "string",
                "const": "error"
              }
            }
          },
          "messages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/UcpMessage"
            }
          }
        }
      },
      "UcpLineTotal": {
        "type": "object",
        "required": [
          "type",
          "amount"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "subtotal",
              "tax",
              "total"
            ]
          },
          "amount": {
            "type": "integer",
            "description": "USD cents."
          }
        }
      },
      "UcpCheckoutSession": {
        "type": "object",
        "description": "A UCP Checkout document (ucp.dev, capability `dev.ucp.shopping.checkout`, version 2026-08-25). One session holds exactly one plan, quantity 1. Amounts are USD cents.",
        "required": [
          "ucp",
          "id",
          "status",
          "currency",
          "expires_at",
          "line_items",
          "totals",
          "payment",
          "continue_url",
          "messages"
        ],
        "properties": {
          "ucp": {
            "type": "object",
            "description": "Protocol block: `version`, `status` (`success`), the `capabilities` and `payment_handlers` the session supports.",
            "properties": {
              "version": {
                "type": "string"
              },
              "status": {
                "type": "string"
              },
              "capabilities": {
                "type": "object"
              },
              "payment_handlers": {
                "type": "object"
              }
            }
          },
          "id": {
            "type": "string",
            "description": "`chk_` + 24 hex characters."
          },
          "status": {
            "type": "string",
            "enum": [
              "incomplete",
              "requires_escalation",
              "ready_for_complete",
              "complete_in_progress",
              "completed",
              "canceled"
            ],
            "description": "`ready_for_complete`: the balance covers the total, the agent can complete. `requires_escalation`: a person pays on the dashboard at `continue_url` (card, PayPal or crypto); poll until `completed`. `canceled`: cancelled by the agent or expired (6 hours)."
          },
          "currency": {
            "type": "string",
            "const": "USD"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "line_items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "item": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "Plan id from `GET /public/plans`."
                    },
                    "title": {
                      "type": "string"
                    },
                    "price": {
                      "type": "integer",
                      "description": "List price, USD cents."
                    },
                    "description": {
                      "type": "string"
                    }
                  }
                },
                "quantity": {
                  "type": "integer",
                  "const": 1
                },
                "totals": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/UcpLineTotal"
                  }
                }
              }
            }
          },
          "totals": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/UcpLineTotal"
            },
            "description": "`subtotal`, `tax` (only when VAT applies) and `total`."
          },
          "buyer": {
            "type": "object",
            "properties": {
              "email": {
                "type": "string",
                "format": "email"
              }
            }
          },
          "payment": {
            "type": "object",
            "properties": {
              "instruments": {
                "type": "array",
                "description": "The only instrument an agent holds: the account balance (`handler_id` `balance`, type `account_balance`).",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "handler_id": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string"
                    },
                    "selected": {
                      "type": "boolean"
                    }
                  }
                }
              },
              "declared_method": {
                "type": "string",
                "enum": [
                  "BALANCE",
                  "NOWPAYMENTS",
                  "PAYPAL",
                  "PAYPAL_CARD"
                ],
                "description": "The method the agent declared; it only decides whether VAT is in the totals."
              }
            }
          },
          "continue_url": {
            "type": "string",
            "format": "uri",
            "description": "Dashboard page where a person finishes this order (the plan is preselected and the session id is carried along)."
          },
          "links": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string"
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "title": {
                  "type": "string"
                }
              }
            }
          },
          "messages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/UcpMessage"
            }
          },
          "order": {
            "type": "object",
            "description": "Present once `completed`.",
            "properties": {
              "id": {
                "type": "string",
                "description": "The `orderId` for `POST /public/proxies/generate`."
              },
              "permalink_url": {
                "type": "string",
                "format": "uri"
              }
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "UnlockAttempt": {
        "type": "object",
        "description": "One attempt of the engine, in order.",
        "required": [
          "tier",
          "outcome",
          "ms",
          "bytes"
        ],
        "properties": {
          "tier": {
            "type": "string",
            "enum": [
              "tls",
              "browser",
              "solver",
              "cache"
            ],
            "description": "Tier that ran the attempt. `solver` is a step handed to the captcha solver, when the service has it enabled: its `profile` names the wall (for example `datadome`, `cloudflare`) and the replay that follows is a `tls` entry. `cache` is the single entry of an answer served from the cache: no exit was used and `bytes` is 0."
          },
          "profile": {
            "type": "string",
            "description": "Browser fingerprint used."
          },
          "exit_country": {
            "type": "string",
            "description": "Country of the exit IP, 2-letter code."
          },
          "outcome": {
            "type": "string",
            "enum": [
              "ok",
              "blocked",
              "failed"
            ],
            "description": "`ok`: the page came back; `blocked`: a challenge or refusal; `failed`: no answer (network, render or timeout)."
          },
          "ms": {
            "type": "integer",
            "description": "Duration of the attempt in milliseconds."
          },
          "bytes": {
            "type": "integer",
            "description": "Bytes the exit network moved for the attempt."
          },
          "block_class": {
            "type": "string",
            "enum": [
              "js_challenge",
              "captcha",
              "access_denied",
              "rate_limited",
              "fingerprint",
              "geo",
              "timeout",
              "unknown"
            ],
            "description": "Kind of wall, when `outcome` is `blocked`."
          },
          "reason": {
            "type": "string",
            "description": "Free-form reason of a block or failure."
          }
        }
      },
      "UnlockCost": {
        "type": "object",
        "description": "What the call cost in prepaid GB. `usd` is `bytes / 10^9 × the price per GB of the tier`; that price is on the plans page of the dashboard and, when the offer is published, in `GET /public/unlock/offer`. The figures shown in the examples are example values, not a price list.",
        "required": [
          "bytes",
          "usd",
          "billed"
        ],
        "properties": {
          "bytes": {
            "type": "integer",
            "description": "Bytes moved across every attempt and tier (same as `usage.bytes`)."
          },
          "usd": {
            "type": "number",
            "description": "Those bytes at the tier's price per GB, USD."
          },
          "billed": {
            "type": "boolean",
            "description": "`true` when the bytes were debited from the tier's prepaid GB, `false` when nothing was debited for this call (a cache hit, for instance)."
          }
        }
      },
      "UnlockErrorPayload": {
        "type": "object",
        "description": "Payload of every Web Unlocker error, REST and proxy alike (the proxy repeats `code` in the `x-qp-unlocker` header; its proxy-only codes, listed under the Unlock errors table, use the same shape). Extra keys depend on the code: `reason`, `buy_url` and the GB balance on `no_credit`; `status`, `blockReason`, `blockClass`, `vendor`, `attempts`, `attempt_log`, `tier_served`, `usage`, `cost` on `target_blocked`; `max_bytes`, `usage`, `cost` on `max_bytes_exceeded`; `retry_after` on `rate_limited`; `tier` on `no_exit_pool`; `request_id` whenever the engine was reached.",
        "required": [
          "code",
          "retryable",
          "billed",
          "hint",
          "doc_url"
        ],
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "bad_request",
              "unauthorized",
              "no_credit",
              "target_forbidden",
              "target_denied",
              "no_exit_pool",
              "max_bytes_exceeded",
              "action_failed",
              "target_blocked",
              "rate_limited",
              "render_failed",
              "upstream_failed",
              "service_unavailable",
              "timeout",
              "internal_error"
            ],
            "description": "One of the codes of the Unlock errors table (the proxy adds its proxy-only codes)."
          },
          "retryable": {
            "type": "boolean",
            "description": "Whether the same request may succeed later."
          },
          "billed": {
            "type": "boolean",
            "description": "Whether the bytes moved were debited from the prepaid GB."
          },
          "hint": {
            "type": "string",
            "description": "What to do next, in one sentence."
          },
          "doc_url": {
            "type": "string",
            "description": "The Unlock errors table: `https://quanticdata.io/docs/#unlock-errors`."
          },
          "request_id": {
            "type": "string",
            "description": "Id of the exchange, when the engine was reached (same as `x-qp-request-id`)."
          }
        },
        "additionalProperties": true
      },
      "UnlockAction": {
        "type": "object",
        "description": "One browser interaction, run before the page is captured. Set exactly one of `click`, `clickText`, `type`, `scroll`, `scrollIn`, `wait`, `waitForSelector`; `optional` and `timeoutMs` can be added to any of them. Keys inside an action are camelCase only, and an unknown key is refused with 400 `bad_request`.",
        "properties": {
          "click": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Click the element matching this CSS selector (up to 256 characters, like every selector here)."
          },
          "clickText": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Click the element whose visible text contains this string (up to 256 characters), case-insensitive. Useful for a consent or accept button whose CSS is unknown."
          },
          "within": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "With `clickText` only: CSS selector of the area to search in."
          },
          "type": {
            "type": "object",
            "description": "Type text into a field: `{\"selector\": \"#search\", \"text\": \"running shoes\"}`. The text can be up to 2000 characters.",
            "required": [
              "selector",
              "text"
            ],
            "properties": {
              "selector": {
                "type": "string",
                "minLength": 1,
                "maxLength": 256,
                "description": "CSS selector of the field."
              },
              "text": {
                "type": "string",
                "maxLength": 2000,
                "description": "Text to type."
              }
            }
          },
          "scroll": {
            "oneOf": [
              {
                "type": "string",
                "enum": [
                  "bottom",
                  "top"
                ]
              },
              {
                "type": "integer",
                "minimum": -100000,
                "maximum": 100000
              }
            ],
            "description": "Scroll the window to the `bottom`, to the `top`, or by a whole number of pixels (up to 100000 either way)."
          },
          "scrollIn": {
            "type": "object",
            "description": "Scroll inside a scrollable element, for example a results pane, instead of the window: `{\"selector\": \".feed\", \"passes\": 5}`. Each pass scrolls it to its bottom and waits for new content; it stops early when nothing more loads. `passes` is 1 to 15.",
            "required": [
              "selector"
            ],
            "properties": {
              "selector": {
                "type": "string",
                "minLength": 1,
                "maxLength": 256,
                "description": "CSS selector of the scrollable element."
              },
              "passes": {
                "type": "integer",
                "minimum": 1,
                "maximum": 15,
                "description": "How many passes to make."
              }
            }
          },
          "wait": {
            "type": "integer",
            "minimum": 0,
            "maximum": 15000,
            "description": "Wait this many milliseconds, 0 to 15000."
          },
          "waitForSelector": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Wait until an element matching this CSS selector appears."
          },
          "optional": {
            "type": "boolean",
            "default": false,
            "description": "`true`: when the action fails (element missing, timeout) the run goes on instead of failing."
          },
          "timeoutMs": {
            "type": "integer",
            "minimum": 100,
            "maximum": 30000,
            "description": "How long this action waits for its element, in milliseconds, 100 to 30000. The whole call still fits in `timeout_ms`."
          }
        },
        "examples": [
          {
            "clickText": "Accept",
            "optional": true,
            "timeoutMs": 3000
          },
          {
            "type": {
              "selector": "#search",
              "text": "running shoes"
            }
          },
          {
            "click": "button[type=submit]"
          },
          {
            "waitForSelector": ".results"
          },
          {
            "scroll": "bottom"
          }
        ]
      },
      "UnlockBatchItemRequest": {
        "type": "object",
        "description": "One unlock call of a batch: `url` plus any field of the request body of `POST /scraper/unlock` (`method`, `headers`, `country`, `mode`, `format`, `actions`, `cache_ttl`, `max_bytes`, `timeout_ms`...). A field set here wins over the same field in `defaults`. Not per item: `tier`, `state`, `city`, `rotation`, `session_id` and `session_duration` belong to the whole batch.",
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "maxLength": 2048,
            "description": "Target URL, `http://` or `https://`."
          }
        },
        "additionalProperties": true
      },
      "UnlockBatchStarted": {
        "type": "object",
        "description": "Answer of `POST /scraper/unlock/batch`.",
        "required": [
          "batch_id",
          "status",
          "total",
          "status_url"
        ],
        "properties": {
          "batch_id": {
            "type": "string",
            "description": "Id of the batch, to poll or cancel it."
          },
          "status": {
            "type": "string",
            "enum": [
              "running"
            ]
          },
          "total": {
            "type": "integer",
            "description": "Number of items accepted."
          },
          "status_url": {
            "type": "string",
            "description": "Where to poll: `GET /scraper/unlock/batch/{batch_id}` for this batch."
          }
        }
      },
      "UnlockBatchResult": {
        "type": "object",
        "description": "Outcome of one item of a batch. The fields are the ones of a single REST call, in snake_case.",
        "required": [
          "index",
          "url",
          "status",
          "blocked",
          "request_id",
          "latency_ms",
          "tier_served",
          "attempts",
          "cost"
        ],
        "properties": {
          "index": {
            "type": "integer",
            "description": "Position of the item in `requests`, from 0."
          },
          "url": {
            "type": "string"
          },
          "status": {
            "type": [
              "integer",
              "null"
            ],
            "description": "HTTP status the target answered; `null` when it never answered."
          },
          "blocked": {
            "type": "boolean",
            "description": "Every attempt came back with a challenge or refusal."
          },
          "block_class": {
            "type": "string",
            "enum": [
              "js_challenge",
              "captcha",
              "access_denied",
              "rate_limited",
              "fingerprint",
              "geo",
              "timeout",
              "unknown"
            ],
            "description": "Kind of wall, when `blocked` is true."
          },
          "vendor": {
            "type": "string",
            "description": "Anti-bot system, when recognised."
          },
          "request_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Id of the exchange, to quote to support."
          },
          "latency_ms": {
            "type": "integer",
            "description": "Milliseconds the item took, every attempt included."
          },
          "tier_served": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "tls",
              "browser",
              null
            ],
            "description": "The tier that produced the answer; `null` when there was none."
          },
          "attempts": {
            "type": "integer",
            "description": "Number of attempts across every tier."
          },
          "cost": {
            "$ref": "#/components/schemas/UnlockCost"
          },
          "error": {
            "type": "object",
            "description": "Present when the item failed: a code of the Unlock errors catalogue and its message.",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          },
          "content_type": {
            "type": "string",
            "description": "Content type of the page."
          },
          "body": {
            "type": "string",
            "description": "Only with `include=body`: the page as text, in the `format` the item asked for."
          },
          "body_base64": {
            "type": "string",
            "description": "Only with `include=body`: the page as base64, when it is not text."
          },
          "body_truncated": {
            "type": "boolean",
            "description": "`true` when the body was cut: an item keeps up to 2 MB unless it sets `max_bytes`, and a batch keeps up to 64 MB of bodies."
          }
        }
      },
      "UnlockBatchJob": {
        "type": "object",
        "description": "A batch: its progress and the outcome of its items.",
        "required": [
          "batch_id",
          "status",
          "total",
          "completed",
          "ok",
          "blocked",
          "failed",
          "created_at",
          "finished_at"
        ],
        "properties": {
          "batch_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "running",
              "completed",
              "cancelled"
            ]
          },
          "total": {
            "type": "integer",
            "description": "Number of items in the batch."
          },
          "completed": {
            "type": "integer",
            "description": "Items that have finished, whatever the outcome."
          },
          "ok": {
            "type": "integer",
            "description": "Items that came back usable."
          },
          "blocked": {
            "type": "integer",
            "description": "Items still blocked after every attempt."
          },
          "failed": {
            "type": "integer",
            "description": "Items that ended with an error."
          },
          "created_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "finished_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "`null` while the batch is running."
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/UnlockBatchResult"
            },
            "description": "The page of results selected by `offset` and `limit`. Left out of the answer of a cancel."
          }
        }
      },
      "UnlockOffer": {
        "type": "object",
        "description": "What the Web Unlocker sells right now. Every value is read from the live settings of the service. When the offer is not published, or the settings cannot be read, the answer is `{\"available\": false, \"updated_at\": \"…\"}` and nothing else.",
        "required": [
          "available"
        ],
        "properties": {
          "available": {
            "type": "boolean",
            "description": "Whether at least one tier can be bought right now."
          },
          "currency": {
            "type": "string",
            "description": "Currency of the prices."
          },
          "price_per_gb": {
            "type": "object",
            "description": "Price of 1 GB (10^9 bytes) on each tier; `null` for a tier that is not on sale.",
            "properties": {
              "premium": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Residential exits."
              },
              "mobile": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Mobile exits."
              }
            }
          },
          "packs_gb": {
            "type": "array",
            "items": {
              "type": "number"
            },
            "description": "Pack sizes on sale, in GB."
          },
          "validity_days": {
            "type": "integer",
            "description": "How many days a pack lasts."
          },
          "pay_per_success": {
            "type": "boolean",
            "description": "`true`: on the REST call and in a batch, a blocked page or a failed call debits no bytes. The forward proxy is metered on every byte either way."
          },
          "free_trial": {
            "type": "boolean",
            "description": "`true`: an account without Web Unlocker GB can make REST calls paid from the monthly free credit of the Data API, at the same price per GB. A batch always needs GB."
          },
          "captcha_solver": {
            "type": "boolean",
            "description": "`true`: DataDome and Cloudflare challenges and the captcha pages of Google and Amazon are handed to the captcha solver."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "UnlockCanarySummary": {
        "type": "object",
        "description": "Totals of one canary run, or of one anti-bot system inside it.",
        "properties": {
          "label": {
            "type": "string",
            "description": "Display name of the anti-bot system (per-system rows only)."
          },
          "measuredAt": {
            "type": "string",
            "description": "Day of the run (history rows only)."
          },
          "calls": {
            "type": "integer",
            "description": "Unlock calls made."
          },
          "ok": {
            "type": "integer",
            "description": "Calls that came back with the real page."
          },
          "rate": {
            "type": "number",
            "description": "`ok` over `calls`, in percent."
          },
          "p50Ms": {
            "type": "integer",
            "description": "Median time of a call, milliseconds."
          },
          "p95Ms": {
            "type": "integer",
            "description": "95th percentile, milliseconds."
          }
        }
      },
      "UnlockCanary": {
        "type": "object",
        "description": "One canary run: our own scheduled unlock calls against a fixed list of public test targets.",
        "properties": {
          "measuredAt": {
            "type": "string",
            "description": "Day of the run."
          },
          "runs": {
            "type": "integer",
            "description": "How many times the list of targets was run."
          },
          "targets": {
            "type": "integer",
            "description": "Number of targets on the list."
          },
          "channel": {
            "type": "string",
            "description": "Entry point the run used."
          },
          "provisional": {
            "type": "boolean"
          },
          "note": {
            "type": "string"
          },
          "summary": {
            "$ref": "#/components/schemas/UnlockCanarySummary"
          },
          "vendors": {
            "type": "object",
            "description": "The same totals per anti-bot system, keyed by its name.",
            "additionalProperties": {
              "$ref": "#/components/schemas/UnlockCanarySummary"
            }
          }
        }
      },
      "UnlockStatus": {
        "type": "object",
        "description": "Health of the Web Unlocker as measured by our own canary. No customer traffic is published.",
        "required": [
          "state",
          "canary",
          "history",
          "updated_at"
        ],
        "properties": {
          "state": {
            "type": "string",
            "enum": [
              "operational",
              "degraded",
              "unknown"
            ],
            "description": "`operational`: the latest canary is younger than 9 days and its success rate is at least 70 percent. `degraded`: it is younger than 9 days and below 70 percent. `unknown`: there is no canary, or it is older."
          },
          "canary": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/UnlockCanary"
              },
              {
                "type": "null"
              }
            ],
            "description": "The latest canary run; `null` when there is none yet."
          },
          "history": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/UnlockCanarySummary"
            },
            "description": "The last 12 canary runs, newest first."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ContactEscalation": {
        "type": "object",
        "description": "Present on a 402 when paying is not the way forward by itself: the call needs more credit than one card top-up may add (`amount_above_limit`), or the account's monthly spend cap is reached (`budget_reached`). An agent asks for a higher limit at `contact_api` with the same API key; a person uses `contact_url`.",
        "required": [
          "type",
          "reason",
          "limit_usd",
          "contact_api",
          "contact_url"
        ],
        "properties": {
          "type": {
            "type": "string",
            "const": "contact"
          },
          "reason": {
            "type": "string",
            "enum": [
              "amount_above_limit",
              "budget_reached"
            ]
          },
          "limit_usd": {
            "type": "number",
            "description": "Maximum credit one top-up may add, USD before VAT."
          },
          "contact_api": {
            "type": "string",
            "format": "uri",
            "description": "`POST /agent/contact` on the dashboard host of this brand."
          },
          "contact_url": {
            "type": "string",
            "format": "uri",
            "description": "The enterprise contact page of the site, for a person."
          }
        }
      },
      "AgentContactRequest": {
        "type": "object",
        "required": [
          "email",
          "name",
          "subject",
          "message"
        ],
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "maxLength": 254,
            "description": "The email address of the person you work for: the team answers there, never to the agent. Temporary mailboxes are refused (400 `invalid_email`)."
          },
          "name": {
            "type": "string",
            "maxLength": 100,
            "description": "Name of the person, or of the agent acting for them."
          },
          "subject": {
            "type": "string",
            "maxLength": 140
          },
          "message": {
            "type": "string",
            "maxLength": 4000,
            "description": "What is needed, with numbers: calls or rows per day, GB per month, countries, deadline. Quote the `payload` of the 402 when there is one."
          },
          "company": {
            "type": "string",
            "maxLength": 200
          },
          "company_url": {
            "type": "string",
            "format": "uri",
            "maxLength": 300,
            "description": "http(s) URL of the company."
          },
          "expected_monthly_usd": {
            "type": "number",
            "minimum": 0,
            "description": "Expected monthly spend, USD. Helps the team size the limit."
          },
          "need": {
            "type": "string",
            "enum": [
              "credit_limit",
              "enterprise",
              "dataset",
              "other"
            ],
            "description": "`credit_limit` after a 402 with `escalation`; `enterprise` for volumes, SLAs or invoicing; `dataset` for a ready-made or custom dataset."
          }
        }
      },
      "AgentContactReceived": {
        "type": "object",
        "required": [
          "type",
          "reference",
          "message",
          "what_happens_next"
        ],
        "properties": {
          "type": {
            "type": "string",
            "const": "response"
          },
          "reference": {
            "type": "string",
            "description": "Id of the request: quote it in a follow-up."
          },
          "message": {
            "type": "string"
          },
          "what_happens_next": {
            "type": "string"
          }
        }
      },
      "CloudflareLocation": {
        "type": "object",
        "description": "The caller's IP and where Cloudflare places it. Country is always there when Cloudflare knows it; region, city, postal code, timezone, coordinates and continent come when available. No network or ISP name.",
        "properties": {
          "ip": {
            "type": [
              "string",
              "null"
            ],
            "description": "The IP the request came from (through a proxy: the exit IP)."
          },
          "countryCode": {
            "type": [
              "string",
              "null"
            ],
            "description": "ISO 3166-1 alpha-2, uppercase."
          },
          "country": {
            "type": [
              "string",
              "null"
            ]
          },
          "region": {
            "type": [
              "string",
              "null"
            ]
          },
          "regionCode": {
            "type": [
              "string",
              "null"
            ]
          },
          "city": {
            "type": [
              "string",
              "null"
            ]
          },
          "postalCode": {
            "type": [
              "string",
              "null"
            ]
          },
          "timezone": {
            "type": [
              "string",
              "null"
            ],
            "description": "IANA timezone, e.g. America/New_York."
          },
          "latitude": {
            "type": [
              "number",
              "null"
            ]
          },
          "longitude": {
            "type": [
              "number",
              "null"
            ]
          },
          "continent": {
            "type": [
              "string",
              "null"
            ],
            "description": "Two-letter continent code (NA, EU, AS, ...)."
          },
          "tor": {
            "type": "boolean",
            "description": "Cloudflare files the IP as a Tor exit."
          },
          "precision": {
            "type": "string",
            "enum": [
              "city",
              "region",
              "country",
              "none"
            ],
            "description": "How far down the answer goes. `none`: no location (the request did not come through Cloudflare, or Cloudflare has no country for the IP)."
          },
          "viaCloudflare": {
            "type": "boolean"
          },
          "source": {
            "type": "string",
            "enum": [
              "cloudflare"
            ]
          }
        },
        "required": [
          "ip",
          "countryCode",
          "country",
          "region",
          "regionCode",
          "city",
          "postalCode",
          "timezone",
          "latitude",
          "longitude",
          "continent",
          "tor",
          "precision",
          "viaCloudflare",
          "source"
        ]
      }
    }
  },
  "paths": {
    "/scraper/extract": {
      "post": {
        "operationId": "scrapeUrl",
        "tags": [
          "Scrape"
        ],
        "summary": "Scrape one URL",
        "description": "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.",
        "x-aliases": [
          "/scrape"
        ],
        "x-price-key": "extract",
        "x-price-keys": [
          "extract",
          "extract_render",
          "ai_extract"
        ],
        "x-pricing-note": "`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).",
        "x-rate-limit": "per-tier",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "maxLength": 2048,
                    "description": "http/https URL to scrape. Required unless `html` is given."
                  },
                  "html": {
                    "type": "string",
                    "description": "Markup to convert instead of fetching (max 5 MB)."
                  },
                  "format": {
                    "type": "string",
                    "enum": [
                      "markdown",
                      "html",
                      "text",
                      "raw"
                    ],
                    "default": "markdown",
                    "description": "`raw` is an alias of `html`. Defaults to markdown (also when AI extraction is requested)."
                  },
                  "formats": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "markdown",
                        "html",
                        "text"
                      ]
                    },
                    "maxItems": 3,
                    "description": "Extra formats returned together under `payload.formats`."
                  },
                  "data_format": {
                    "type": "string",
                    "enum": [
                      "markdown",
                      "screenshot"
                    ],
                    "description": "Compatibility alias: `markdown` sets format, `screenshot` sets `screenshot: fullPage`."
                  },
                  "engine": {
                    "type": "string",
                    "enum": [
                      "auto",
                      "tls",
                      "fetch",
                      "render"
                    ],
                    "default": "auto",
                    "description": "`auto` starts on the TLS tier and escalates to the browser on a block; `tls`/`fetch` never escalate; `render` forces the browser."
                  },
                  "autoEscalate": {
                    "type": "boolean",
                    "description": "Allow/forbid the auto engine's escalation to the browser (ignored once the plan's render budget is spent)."
                  },
                  "tlsProfile": {
                    "type": "string",
                    "maxLength": 64,
                    "description": "TLS fingerprint profile for the TLS tier (opaque to the API; see /scraper/unlock for the known names)."
                  },
                  "render": {
                    "type": "boolean",
                    "default": false,
                    "description": "Force the stealth headless browser (JS execution). Bills the render rate."
                  },
                  "mobile": {
                    "type": "boolean",
                    "default": false,
                    "description": "Mobile viewport and user agent."
                  },
                  "waitMs": {
                    "type": "number",
                    "description": "Extra wait after load before capture, render tier (clamped by the service, max 15000)."
                  },
                  "waitForSelector": {
                    "type": "string",
                    "maxLength": 512,
                    "description": "Wait until this CSS selector appears (render tier)."
                  },
                  "scrollToBottom": {
                    "type": "boolean",
                    "default": false,
                    "description": "Auto-scroll to trigger lazy-loaded content (render tier)."
                  },
                  "actions": {
                    "type": "array",
                    "maxItems": 20,
                    "items": {
                      "$ref": "#/components/schemas/PageAction"
                    }
                  },
                  "screenshot": {
                    "oneOf": [
                      {
                        "type": "boolean"
                      },
                      {
                        "type": "string",
                        "enum": [
                          "fullPage"
                        ]
                      }
                    ],
                    "description": "`true` = viewport PNG, `fullPage` = whole page; forces render. Returned base64 under `screenshot`."
                  },
                  "xhr": {
                    "type": "boolean",
                    "description": "Record the page's XHR/fetch traffic under `xhr` (forces render). Use it to discover which API to target with a `fetchResource` action."
                  },
                  "expect": {
                    "type": "object",
                    "description": "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.",
                    "properties": {
                      "element": {
                        "type": "string"
                      },
                      "text": {
                        "type": "string"
                      }
                    }
                  },
                  "extract": {
                    "$ref": "#/components/schemas/ExtractSchema"
                  },
                  "presetId": {
                    "type": "string",
                    "description": "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": {
                    "type": "string",
                    "enum": [
                      "smart",
                      "article",
                      "full"
                    ],
                    "default": "smart",
                    "description": "`smart` = whole page minus nav/footer/cookie chrome; `article` = Readability main article; `full` = entire body. Alias `content_mode`."
                  },
                  "content_modes": {
                    "type": "array",
                    "maxItems": 3,
                    "items": {
                      "type": "string",
                      "enum": [
                        "smart",
                        "article",
                        "full"
                      ]
                    },
                    "description": "Return several content modes at once under `contents`. Alias `contentModes`."
                  },
                  "fullPage": {
                    "type": "boolean",
                    "description": "Legacy: `true` = contentMode full."
                  },
                  "mode": {
                    "type": "string",
                    "enum": [
                      "full",
                      "summary"
                    ],
                    "default": "full",
                    "description": "`summary` drops the content and returns only metadata (title, description, canonical, contentLength, engine, bytes) — the light view for audits over many pages."
                  },
                  "include_links": {
                    "type": "boolean",
                    "default": false,
                    "description": "Also return de-duplicated absolute links under `links`. Alias `includeLinks`."
                  },
                  "app_state": {
                    "oneOf": [
                      {
                        "type": "boolean"
                      },
                      {
                        "type": "string",
                        "enum": [
                          "auto",
                          "raw"
                        ]
                      }
                    ],
                    "description": "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": {
                    "type": "object",
                    "description": "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.",
                    "properties": {
                      "include": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "exclude": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "keep": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      }
                    }
                  },
                  "reveal_hidden": {
                    "type": "boolean",
                    "description": "Render tier: open `<details>`/accordions and click through tabs, capturing every panel. Alias `revealHidden`."
                  },
                  "output": {
                    "type": "object",
                    "description": "Markdown shaping; every key also accepted flat (snake_case) at the top level, flat wins.",
                    "properties": {
                      "frontmatter": {
                        "type": "boolean"
                      },
                      "toc": {
                        "type": "boolean"
                      },
                      "linksMode": {
                        "type": "string",
                        "enum": [
                          "inline",
                          "footnote",
                          "strip"
                        ]
                      },
                      "maxTokens": {
                        "type": "number",
                        "minimum": 200,
                        "maximum": 2000000
                      },
                      "imagesMode": {
                        "type": "string",
                        "enum": [
                          "inline",
                          "alt",
                          "strip"
                        ]
                      },
                      "query": {
                        "type": "string",
                        "maxLength": 512,
                        "description": "Relevance filter for LLM-oriented output."
                      },
                      "highlights": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 20,
                        "description": "Most query-relevant passages to return (requires `query`)."
                      },
                      "summarySections": {
                        "type": "boolean"
                      },
                      "chunk": {
                        "type": "object",
                        "properties": {
                          "by": {
                            "type": "string",
                            "enum": [
                              "heading",
                              "sentence",
                              "tokens"
                            ]
                          },
                          "size": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 100000
                          },
                          "overlap": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 100000
                          }
                        }
                      }
                    }
                  },
                  "frontmatter": {
                    "type": "boolean"
                  },
                  "links_mode": {
                    "type": "string",
                    "enum": [
                      "inline",
                      "footnote",
                      "strip"
                    ]
                  },
                  "toc": {
                    "type": "boolean"
                  },
                  "max_tokens": {
                    "type": "number",
                    "minimum": 200,
                    "maximum": 2000000
                  },
                  "images_mode": {
                    "type": "string",
                    "enum": [
                      "inline",
                      "alt",
                      "strip"
                    ]
                  },
                  "query": {
                    "type": "string",
                    "maxLength": 512
                  },
                  "highlights": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 20
                  },
                  "chunk": {
                    "type": "object"
                  },
                  "summary_sections": {
                    "type": "boolean"
                  },
                  "ai_prompt": {
                    "type": "string",
                    "description": "Natural-language instruction: the LLM turns the page into structured JSON under `payload.ai.data`."
                  },
                  "ai_schema": {
                    "type": "object",
                    "description": "JSON Schema the AI output must follow (deterministic shape). Either `ai_prompt` or `ai_schema` (or both) enables AI extraction."
                  },
                  "headers": {
                    "$ref": "#/components/schemas/ForwardHeaders"
                  },
                  "cookies": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    },
                    "maxProperties": 50,
                    "description": "name → value cookies sent to the target."
                  },
                  "country": {
                    "$ref": "#/components/schemas/GeoValue"
                  },
                  "state": {
                    "$ref": "#/components/schemas/GeoValue",
                    "description": "Requires `country`."
                  },
                  "city": {
                    "$ref": "#/components/schemas/GeoValue",
                    "description": "Requires `country`."
                  },
                  "rotation": {
                    "type": "string",
                    "enum": [
                      "rotating",
                      "sticky"
                    ],
                    "default": "rotating",
                    "description": "New exit IP per request, or keep one IP for the session. Any other value is treated as `rotating`."
                  },
                  "sessionId": {
                    "type": "string",
                    "maxLength": 64,
                    "description": "Sticky session id (generated if omitted)."
                  },
                  "sessionDuration": {
                    "type": "number",
                    "description": "Sticky session lifetime in minutes (clamped by the proxy layer, 3–1440, default 10)."
                  }
                }
              },
              "example": {
                "url": "https://example.com/pricing",
                "format": "markdown",
                "country": "us",
                "extract": {
                  "title": "h1",
                  "price": ".price"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Page fetched. `engine` says which tier served it and therefore which price applied.",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/ExtractResult"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "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": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "`presetId` does not resolve to one of your presets.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "Preset not found",
                  "payload": {
                    "url": "https://example.com/"
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "description": "Extraction failed on our side or timed out (70 s budget). Never billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "Extraction timed out",
                  "payload": {
                    "url": "https://example.com/"
                  }
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/ServiceDisabled"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/scraper/extract' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"url\":\"https://example.com/pricing\",\"format\":\"markdown\",\"country\":\"us\",\"extract\":{\"title\":\"h1\",\"price\":\".price\"}}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/scraper/extract',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\n        \"url\": \"https://example.com/pricing\",\n        \"format\": \"markdown\",\n        \"country\": \"us\",\n        \"extract\": {\n            \"title\": \"h1\",\n            \"price\": \".price\"\n        }\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/extract\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"url\": \"https://example.com/pricing\",\n    \"format\": \"markdown\",\n    \"country\": \"us\",\n    \"extract\": {\n      \"title\": \"h1\",\n      \"price\": \".price\"\n    }\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/extract');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'url' => 'https://example.com/pricing',\n    'format' => 'markdown',\n    'country' => 'us',\n    'extract' => [\n      'title' => 'h1',\n      'price' => '.price'\n    ]\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/scraper/serp": {
      "post": {
        "operationId": "searchSerp",
        "tags": [
          "Search"
        ],
        "summary": "Structured search results",
        "description": "One search on Google, Bing or DuckDuckGo through the residential pool, returned as JSON in the common SERP-API shape: organic results, ads, People Also Ask, related searches, knowledge panels, AI Overview and 17 Google verticals (`search_type`). `render: true` asks for the rendered Google page (People Also Ask, related questions, ads), `render: false` pins the cheaper HTTP tier, and without `render` the service picks: the HTTP tier for Google web search, a browser for the verticals that need one. Identical requests are served from a 24h cache for free (`search_metadata.from_cache`). It does not paginate on your behalf: request one `page` at a time and read `pagination.available_pages`/`has_next`, or use `/scraper/serp/bulk`. Billed per successful search by the tier that served it (`search_metadata.path`); blocked searches answer 429 and cost nothing; `autocomplete` and `reviews` always bill the request price. Bing: a page whose results answer another query (a decoy) or Bing's \"no results\" shell is never returned as a result; the service retries as a different browser identity, then once in a real browser, and if nothing genuine comes back the call ends 429 with `code` `bing-decoy` or `bing-no-results`, `attempts` and `retries` (one entry per attempt: `tier`, `outcome`, `reason`) — retry it or use `engine: \"google\"`. A Bing Success with `organic: []` always carries `search_metadata.empty_reason`.",
        "x-aliases": [
          "/serp"
        ],
        "x-price-key": "serp",
        "x-price-keys": [
          "serp",
          "serp_render"
        ],
        "x-pricing-note": "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.",
        "x-rate-limit": "per-tier",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "maxLength": 2048,
                    "description": "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": {
                    "type": "string",
                    "enum": [
                      "google",
                      "bing",
                      "duckduckgo"
                    ],
                    "default": "google"
                  },
                  "search_type": {
                    "type": "string",
                    "enum": [
                      "search",
                      "shopping",
                      "images",
                      "news",
                      "places",
                      "maps",
                      "videos",
                      "scholar",
                      "jobs",
                      "autocomplete",
                      "place_details",
                      "hotels",
                      "flights",
                      "events",
                      "product",
                      "lens",
                      "reviews",
                      "trends"
                    ],
                    "default": "search",
                    "description": "Vertical. Alias `type`; Google aliases `tbm` (shop/isch/nws/lcl/vid) and `udm` (28/2/12/1/7) are mapped too."
                  },
                  "country": {
                    "$ref": "#/components/schemas/GeoValue",
                    "description": "Proxy exit and engine locale. Alias `gl`."
                  },
                  "lang": {
                    "type": "string",
                    "maxLength": 10,
                    "description": "UI language, e.g. `en`, `it`. Alias `hl`."
                  },
                  "num": {
                    "type": "number",
                    "description": "Results to request (clamped to 1–100 by the service; Google serves ~10 per page and merges pages — see `search_metadata.paging`)."
                  },
                  "page": {
                    "type": "number",
                    "description": "Result page, 1-based."
                  },
                  "start": {
                    "type": "number",
                    "description": "Result offset (alternative to `page`)."
                  },
                  "device": {
                    "type": "string",
                    "enum": [
                      "desktop",
                      "mobile",
                      "ios",
                      "android"
                    ],
                    "default": "desktop",
                    "description": "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": {
                    "type": "boolean",
                    "description": "Forwarded as sent. `true` asks for the rendered Google page (People Also Ask, related questions, ads; billed `serp_render` when a rendered tier answers), `false` pins the cheaper HTTP tier, unset lets the service pick (the HTTP tier for Google web search, a browser for the verticals that need one). DuckDuckGo never renders; Bing renders only as the last attempt after decoys (always billed `serp`)."
                  },
                  "browser": {
                    "type": "string",
                    "enum": [
                      "chrome",
                      "firefox",
                      "safari"
                    ],
                    "description": "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": {
                    "type": "string",
                    "enum": [
                      "active",
                      "off"
                    ],
                    "description": "SafeSearch."
                  },
                  "nfpr": {
                    "oneOf": [
                      {
                        "type": "boolean"
                      },
                      {
                        "type": "integer",
                        "enum": [
                          1
                        ]
                      }
                    ],
                    "description": "Disable auto-corrected results."
                  },
                  "location": {
                    "type": "string",
                    "maxLength": 256,
                    "description": "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": {
                    "type": "string",
                    "maxLength": 512,
                    "description": "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": {
                    "type": "object",
                    "maxProperties": 24,
                    "description": "Escape hatch: extra Google URL params (keys ≤40 chars of letters, digits, `.`, `-`, `_`; values strings ≤512 chars or numbers)."
                  },
                  "jobs": {
                    "type": "boolean",
                    "description": "Jobs box on the main SERP. Alias `ibp: \"htl;jobs\"`."
                  },
                  "place_id": {
                    "type": "string",
                    "maxLength": 128,
                    "description": "`place_details`."
                  },
                  "data_id": {
                    "type": "string",
                    "maxLength": 128,
                    "description": "`place_details` / `reviews` (feature id 0x…:0x…)."
                  },
                  "product_id": {
                    "oneOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "number"
                      }
                    ],
                    "description": "`product`: the seller list of one shopping result."
                  },
                  "departure_id": {
                    "type": "string",
                    "maxLength": 64,
                    "description": "`flights`: airport/city code."
                  },
                  "arrival_id": {
                    "type": "string",
                    "maxLength": 64
                  },
                  "outbound_date": {
                    "type": "string",
                    "maxLength": 10,
                    "description": "YYYY-MM-DD."
                  },
                  "return_date": {
                    "type": "string",
                    "maxLength": 10
                  },
                  "check_in_date": {
                    "type": "string",
                    "maxLength": 10,
                    "description": "`hotels`."
                  },
                  "check_out_date": {
                    "type": "string",
                    "maxLength": 10
                  },
                  "adults": {
                    "type": "number",
                    "description": "`hotels`, clamped 1–30."
                  },
                  "children_ages": {
                    "type": "array",
                    "items": {
                      "type": "number"
                    },
                    "maxItems": 10
                  },
                  "free_cancellation": {
                    "type": "boolean"
                  },
                  "accommodation_type": {
                    "type": "string",
                    "enum": [
                      "hotels",
                      "vacation_rentals"
                    ]
                  },
                  "currency": {
                    "type": "string",
                    "maxLength": 8,
                    "description": "`hotels`/`flights` price currency (USD, EUR…)."
                  },
                  "gps_coordinates": {
                    "type": "string",
                    "maxLength": 64,
                    "description": "`maps`/`places`: map center `lat,lon[,zoom]`. Wins over `uule` and `location`."
                  },
                  "image_url": {
                    "type": "string",
                    "maxLength": 2048,
                    "description": "`lens`: http(s) URL of the image to search by."
                  },
                  "exact_matches": {
                    "type": "boolean",
                    "description": "`lens`."
                  },
                  "sort_by": {
                    "type": "string",
                    "enum": [
                      "relevance",
                      "newest",
                      "highest_rating",
                      "lowest_rating"
                    ],
                    "description": "`reviews`."
                  },
                  "filter": {
                    "type": "string",
                    "maxLength": 256,
                    "description": "`reviews`: keyword filter."
                  },
                  "next_page_token": {
                    "type": "string",
                    "maxLength": 512,
                    "description": "`reviews`: continuation token from `serpapi_pagination`."
                  },
                  "wait_for": {
                    "type": "string",
                    "maxLength": 512,
                    "description": "Render tier: CSS selector to wait for before capture."
                  },
                  "include_html": {
                    "type": "boolean",
                    "description": "Also return the page HTML under `html` (scripts stripped)."
                  },
                  "product_ids": {
                    "type": "boolean",
                    "description": "`shopping`: resolve product ids for each result (slower)."
                  }
                }
              },
              "example": {
                "query": "best coffee grinder",
                "engine": "google",
                "country": "us",
                "lang": "en",
                "num": 10
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Search succeeded. The envelope's `pagination` mirrors `payload.pagination`.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/SerpResult"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "description": "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.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceDisabled"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/scraper/serp' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"query\":\"best coffee grinder\",\"engine\":\"google\",\"country\":\"us\",\"lang\":\"en\",\"num\":10}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/scraper/serp',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\n        \"query\": \"best coffee grinder\",\n        \"engine\": \"google\",\n        \"country\": \"us\",\n        \"lang\": \"en\",\n        \"num\": 10\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/serp\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"query\": \"best coffee grinder\",\n    \"engine\": \"google\",\n    \"country\": \"us\",\n    \"lang\": \"en\",\n    \"num\": 10\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/serp');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'query' => 'best coffee grinder',\n    'engine' => 'google',\n    'country' => 'us',\n    'lang' => 'en',\n    'num' => 10\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/scraper/serp/bulk": {
      "post": {
        "operationId": "startSerpBulk",
        "tags": [
          "Search"
        ],
        "summary": "Start a multi-page search job",
        "description": "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.",
        "x-aliases": [
          "/serp/bulk"
        ],
        "x-price-key": "serp_render",
        "x-price-keys": [
          "serp",
          "serp_render"
        ],
        "x-pricing-note": "Google: `serp_render` × max_pages up front; Bing/DuckDuckGo: `serp` × max_pages. Unfetched pages refunded at settlement.",
        "x-rate-limit": "per-tier",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "query"
                ],
                "properties": {
                  "query": {
                    "type": "string",
                    "maxLength": 2048
                  },
                  "engine": {
                    "type": "string",
                    "enum": [
                      "google",
                      "bing",
                      "duckduckgo"
                    ],
                    "default": "google"
                  },
                  "search_type": {
                    "type": "string",
                    "enum": [
                      "search",
                      "news",
                      "videos",
                      "images",
                      "shopping"
                    ],
                    "default": "search",
                    "description": "Alias `type`."
                  },
                  "max_pages": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 10,
                    "default": 5
                  },
                  "country": {
                    "$ref": "#/components/schemas/GeoValue",
                    "description": "Alias `gl`."
                  },
                  "lang": {
                    "type": "string",
                    "maxLength": 10,
                    "description": "Alias `hl`."
                  },
                  "device": {
                    "type": "string",
                    "enum": [
                      "desktop",
                      "mobile",
                      "ios",
                      "android"
                    ],
                    "description": "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": {
                    "type": "boolean"
                  },
                  "wait_for": {
                    "type": "string",
                    "maxLength": 512
                  },
                  "browser": {
                    "type": "string",
                    "enum": [
                      "chrome",
                      "firefox",
                      "safari"
                    ],
                    "description": "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": {
                    "type": "string",
                    "enum": [
                      "active",
                      "off"
                    ]
                  },
                  "nfpr": {
                    "oneOf": [
                      {
                        "type": "boolean"
                      },
                      {
                        "type": "integer",
                        "enum": [
                          1
                        ]
                      }
                    ]
                  },
                  "uule": {
                    "type": "string",
                    "maxLength": 512
                  },
                  "location": {
                    "type": "string",
                    "maxLength": 256
                  },
                  "google_params": {
                    "type": "object",
                    "maxProperties": 24
                  },
                  "webhook": {
                    "type": "string",
                    "maxLength": 2048,
                    "description": "Public http(s) URL that receives the finished job by POST."
                  }
                }
              },
              "example": {
                "query": "best coffee grinder",
                "engine": "google",
                "country": "us",
                "max_pages": 3
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Job accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/JobStarted"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "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": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceDisabled"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/scraper/serp/bulk' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"query\":\"best coffee grinder\",\"engine\":\"google\",\"country\":\"us\",\"max_pages\":3}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/scraper/serp/bulk',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\n        \"query\": \"best coffee grinder\",\n        \"engine\": \"google\",\n        \"country\": \"us\",\n        \"max_pages\": 3\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/serp/bulk\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"query\": \"best coffee grinder\",\n    \"engine\": \"google\",\n    \"country\": \"us\",\n    \"max_pages\": 3\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/serp/bulk');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'query' => 'best coffee grinder',\n    'engine' => 'google',\n    'country' => 'us',\n    'max_pages' => 3\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/scraper/serp/bulk/{jobId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/jobId"
        }
      ],
      "get": {
        "operationId": "getSerpBulk",
        "tags": [
          "Search"
        ],
        "summary": "Poll a multi-page search job",
        "description": "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.",
        "x-aliases": [
          "/serp/bulk/{jobId}"
        ],
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "parameters": [
          {
            "name": "since",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Organic cursor from the previous poll's `nextCursor`."
          }
        ],
        "responses": {
          "200": {
            "description": "Job view.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/SerpBulkJob"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "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": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceDisabled"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/scraper/serp/bulk/job_8f2c1a' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/scraper/serp/bulk/job_8f2c1a',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/serp/bulk/job_8f2c1a\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/serp/bulk/job_8f2c1a');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      },
      "delete": {
        "operationId": "cancelSerpBulk",
        "tags": [
          "Search"
        ],
        "summary": "Cancel a multi-page search job",
        "description": "Stops a running bulk search job you own. Pages never fetched are refunded at settlement.",
        "x-aliases": [
          "/serp/bulk/{jobId}"
        ],
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "responses": {
          "200": {
            "description": "Cancelled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                },
                "example": {
                  "type": "response",
                  "message": "Bulk SERP cancelled",
                  "payload": {
                    "id": "sb_4d1e9c",
                    "status": "cancelled"
                  },
                  "pagination": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceDisabled"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X DELETE 'https://api.quanticdata.io/v1/scraper/serp/bulk/job_8f2c1a' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.delete(\n    'https://api.quanticdata.io/v1/scraper/serp/bulk/job_8f2c1a',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/serp/bulk/job_8f2c1a\", {\n  method: \"DELETE\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/serp/bulk/job_8f2c1a');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'DELETE',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/scraper/map": {
      "post": {
        "operationId": "mapSite",
        "tags": [
          "Map & Crawl"
        ],
        "summary": "Discover a site's URLs",
        "description": "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.",
        "x-aliases": [
          "/map"
        ],
        "x-price-key": "map",
        "x-rate-limit": "per-tier",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "maxLength": 2048,
                    "description": "Seed URL."
                  },
                  "limit": {
                    "type": "number",
                    "default": 100,
                    "description": "Max URLs to return (service cap 5000)."
                  },
                  "search": {
                    "type": "string",
                    "maxLength": 256,
                    "description": "Only return URLs containing this substring."
                  },
                  "includeSubdomains": {
                    "type": "boolean",
                    "default": false
                  },
                  "sitemapOnly": {
                    "type": "boolean",
                    "default": false,
                    "description": "Skip the homepage link scrape."
                  },
                  "group_by": {
                    "type": "string",
                    "enum": [
                      "path"
                    ],
                    "description": "Return the path tree with counts instead of the URL list. Alias `groupBy`."
                  },
                  "country": {
                    "$ref": "#/components/schemas/GeoValue"
                  }
                }
              },
              "example": {
                "url": "https://example.com",
                "limit": 100,
                "search": "blog"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "URLs discovered.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/MapResult"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "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": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceDisabled"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/scraper/map' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"url\":\"https://example.com\",\"limit\":100,\"search\":\"blog\"}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/scraper/map',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\n        \"url\": \"https://example.com\",\n        \"limit\": 100,\n        \"search\": \"blog\"\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/map\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"url\": \"https://example.com\",\n    \"limit\": 100,\n    \"search\": \"blog\"\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/map');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'url' => 'https://example.com',\n    'limit' => 100,\n    'search' => 'blog'\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/scraper/crawl": {
      "post": {
        "operationId": "startCrawl",
        "tags": [
          "Map & Crawl"
        ],
        "summary": "Start a site crawl",
        "description": "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.",
        "x-aliases": [
          "/crawl"
        ],
        "x-price-key": "crawl_page",
        "x-price-keys": [
          "crawl_page",
          "extract_render"
        ],
        "x-pricing-note": "`crawl_page` × min(limit, 500) up front, or `extract_render` × pages when render is true. Refund of the unfetched share at settlement.",
        "x-rate-limit": "per-tier",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "maxLength": 2048,
                    "description": "Seed URL."
                  },
                  "limit": {
                    "type": "number",
                    "default": 50,
                    "description": "Max pages (cap 500). Billed on this up front."
                  },
                  "depth": {
                    "type": "number",
                    "default": 3,
                    "description": "Max link depth from the seed (cap 10)."
                  },
                  "format": {
                    "type": "string",
                    "enum": [
                      "markdown",
                      "html",
                      "text"
                    ],
                    "default": "markdown"
                  },
                  "contentMode": {
                    "type": "string",
                    "enum": [
                      "smart",
                      "article",
                      "full"
                    ],
                    "default": "smart",
                    "description": "Alias `content_mode`."
                  },
                  "render": {
                    "type": "boolean",
                    "default": false,
                    "description": "Render every page with the stealth browser (slower, rendered rate)."
                  },
                  "sameDomain": {
                    "type": "boolean",
                    "default": true
                  },
                  "allowSubdomains": {
                    "type": "boolean",
                    "default": false
                  },
                  "include": {
                    "type": "array",
                    "maxItems": 50,
                    "items": {
                      "type": "string",
                      "maxLength": 256
                    },
                    "description": "URL substrings/globs to include, e.g. [\"/guides/*\"]."
                  },
                  "exclude": {
                    "type": "array",
                    "maxItems": 50,
                    "items": {
                      "type": "string",
                      "maxLength": 256
                    }
                  },
                  "country": {
                    "$ref": "#/components/schemas/GeoValue"
                  }
                }
              },
              "example": {
                "url": "https://docs.example.com",
                "limit": 50,
                "depth": 3,
                "include": [
                  "/guides/*"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Crawl started.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/JobStarted"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "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": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceDisabled"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/scraper/crawl' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"url\":\"https://docs.example.com\",\"limit\":50,\"depth\":3,\"include\":[\"/guides/*\"]}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/scraper/crawl',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\n        \"url\": \"https://docs.example.com\",\n        \"limit\": 50,\n        \"depth\": 3,\n        \"include\": [\n            \"/guides/*\"\n        ]\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/crawl\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"url\": \"https://docs.example.com\",\n    \"limit\": 50,\n    \"depth\": 3,\n    \"include\": [\n      \"/guides/*\"\n    ]\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/crawl');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'url' => 'https://docs.example.com',\n    'limit' => 50,\n    'depth' => 3,\n    'include' => ['/guides/*']\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/scraper/crawl/{jobId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/jobId"
        }
      ],
      "get": {
        "operationId": "getCrawl",
        "tags": [
          "Map & Crawl"
        ],
        "summary": "Poll a crawl job",
        "description": "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.",
        "x-aliases": [
          "/crawl/{jobId}"
        ],
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "parameters": [
          {
            "name": "since",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Page cursor from the previous poll's `nextCursor`."
          },
          {
            "name": "include_content",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            },
            "description": "Omit to get the full job; `false` strips page content."
          }
        ],
        "responses": {
          "200": {
            "description": "Job view.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/CrawlJob"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "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": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceDisabled"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/scraper/crawl/job_8f2c1a' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/scraper/crawl/job_8f2c1a',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/crawl/job_8f2c1a\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/crawl/job_8f2c1a');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      },
      "delete": {
        "operationId": "cancelCrawl",
        "tags": [
          "Map & Crawl"
        ],
        "summary": "Cancel a crawl job",
        "description": "Stops a running crawl you own; pages never fetched are refunded at settlement.",
        "x-aliases": [
          "/crawl/{jobId}"
        ],
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "responses": {
          "200": {
            "description": "Cancelled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                },
                "example": {
                  "type": "response",
                  "message": "Crawl cancelled",
                  "payload": {
                    "id": "cr_d5b8a1",
                    "status": "cancelled"
                  },
                  "pagination": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceDisabled"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X DELETE 'https://api.quanticdata.io/v1/scraper/crawl/job_8f2c1a' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.delete(\n    'https://api.quanticdata.io/v1/scraper/crawl/job_8f2c1a',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/crawl/job_8f2c1a\", {\n  method: \"DELETE\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/crawl/job_8f2c1a');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'DELETE',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/scraper/batch": {
      "post": {
        "operationId": "startBatch",
        "tags": [
          "Batch"
        ],
        "summary": "Scrape many URLs asynchronously",
        "description": "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.",
        "x-aliases": [
          "/batch"
        ],
        "x-price-key": "batch_url",
        "x-price-keys": [
          "batch_url",
          "extract_render"
        ],
        "x-pricing-note": "`batch_url` × urls up front (or `extract_render` × urls when rendering). Failed URLs refunded at settlement.",
        "x-rate-limit": "per-tier",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "urls"
                ],
                "properties": {
                  "urls": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 5000,
                    "items": {
                      "type": "string",
                      "maxLength": 2048
                    }
                  },
                  "format": {
                    "type": "string",
                    "enum": [
                      "markdown",
                      "html",
                      "text"
                    ],
                    "default": "markdown"
                  },
                  "engine": {
                    "type": "string",
                    "enum": [
                      "auto",
                      "tls",
                      "fetch",
                      "render"
                    ],
                    "default": "auto"
                  },
                  "render": {
                    "type": "boolean",
                    "default": false,
                    "description": "Force the headless browser for every URL."
                  },
                  "extract": {
                    "$ref": "#/components/schemas/ExtractSchema"
                  },
                  "contentMode": {
                    "type": "string",
                    "enum": [
                      "smart",
                      "article",
                      "full"
                    ],
                    "default": "smart",
                    "description": "Alias `content_mode`."
                  },
                  "fullPage": {
                    "type": "boolean",
                    "description": "Legacy: contentMode full."
                  },
                  "mode": {
                    "type": "string",
                    "enum": [
                      "full",
                      "summary"
                    ],
                    "default": "full",
                    "description": "`summary` stores per-URL metadata only (title, description, canonical, contentLength)."
                  },
                  "concurrency": {
                    "type": "number",
                    "default": 5,
                    "minimum": 1,
                    "maximum": 20,
                    "description": "Simultaneous fetches (clamped 1–20; your tier's batch concurrency also applies)."
                  },
                  "webhook": {
                    "type": "string",
                    "maxLength": 2048,
                    "description": "Public http(s) URL that receives the finished job by POST."
                  },
                  "country": {
                    "$ref": "#/components/schemas/GeoValue"
                  }
                }
              },
              "example": {
                "urls": [
                  "https://example.com/a",
                  "https://example.com/b"
                ],
                "format": "markdown",
                "mode": "summary"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch started.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/JobStarted"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "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": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceDisabled"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/scraper/batch' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"urls\":[\"https://example.com/a\",\"https://example.com/b\"],\"format\":\"markdown\",\"mode\":\"summary\"}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/scraper/batch',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\n        \"urls\": [\n            \"https://example.com/a\",\n            \"https://example.com/b\"\n        ],\n        \"format\": \"markdown\",\n        \"mode\": \"summary\"\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/batch\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"urls\": [\n      \"https://example.com/a\",\n      \"https://example.com/b\"\n    ],\n    \"format\": \"markdown\",\n    \"mode\": \"summary\"\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/batch');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'urls' => ['https://example.com/a', 'https://example.com/b'],\n    'format' => 'markdown',\n    'mode' => 'summary'\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/scraper/batch/{jobId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/jobId"
        }
      ],
      "get": {
        "operationId": "getBatch",
        "tags": [
          "Batch"
        ],
        "summary": "Poll a batch job",
        "description": "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.",
        "x-aliases": [
          "/batch/{jobId}"
        ],
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "parameters": [
          {
            "name": "since",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Item cursor from the previous poll's `nextCursor`."
          },
          {
            "name": "include_content",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            },
            "description": "`true` includes each item's page content."
          }
        ],
        "responses": {
          "200": {
            "description": "Job view.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/BatchJob"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "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": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceDisabled"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/scraper/batch/job_8f2c1a' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/scraper/batch/job_8f2c1a',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/batch/job_8f2c1a\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/batch/job_8f2c1a');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      },
      "delete": {
        "operationId": "cancelBatch",
        "tags": [
          "Batch"
        ],
        "summary": "Cancel a batch job",
        "description": "Stops a running batch you own; URLs never fetched are refunded at settlement.",
        "x-aliases": [
          "/batch/{jobId}"
        ],
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "responses": {
          "200": {
            "description": "Cancelled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                },
                "example": {
                  "type": "response",
                  "message": "Batch cancelled",
                  "payload": {
                    "id": "bt_91ac07",
                    "status": "cancelled"
                  },
                  "pagination": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceDisabled"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X DELETE 'https://api.quanticdata.io/v1/scraper/batch/job_8f2c1a' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.delete(\n    'https://api.quanticdata.io/v1/scraper/batch/job_8f2c1a',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/batch/job_8f2c1a\", {\n  method: \"DELETE\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/batch/job_8f2c1a');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'DELETE',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/scraper/cost": {
      "get": {
        "operationId": "estimateScraperCost",
        "tags": [
          "Scrape"
        ],
        "summary": "Price a call before sending it",
        "description": "Returns what a scrape, batch, crawl, SERP or map call can cost on this account, from the configured prices alone. Nothing is fetched, nothing is charged and no rate-limit token is taken, so it is safe to call before every job. Use it to size a `max_cost` ceiling: pass the ceiling you have in mind and the answer says whether the call fits under it, whether the browser tier would still be allowed and how many units fit. It does not predict the outcome of a call: the real charge depends on the tier that answers and on the bytes moved, and only a usable result is charged.",
        "x-price-key": null,
        "x-rate-limit": "none",
        "parameters": [
          {
            "name": "kind",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "extract",
                "batch",
                "crawl",
                "serp",
                "map"
              ],
              "default": "extract"
            },
            "description": "The call to price."
          },
          {
            "name": "proxy_type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "residential",
                "datacenter",
                "mobile"
              ],
              "default": "residential"
            },
            "description": "Proxy tier of an `extract`, `batch` or `crawl`. Ignored for `serp` and `map`."
          },
          {
            "name": "render",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            },
            "description": "`true` prices the call with the browser tier forced."
          },
          {
            "name": "units",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000000,
              "default": 1
            },
            "description": "URLs of a batch, pages of a crawl, or number of calls."
          },
          {
            "name": "ai",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            },
            "description": "`true` adds AI extraction to an `extract`."
          },
          {
            "name": "max_cost",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "description": "Optional ceiling in USD. When present the answer carries `under_max_cost`."
          }
        ],
        "responses": {
          "200": {
            "description": "The estimate. Money fields are USD list prices of this account's plan.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "kind": {
                              "type": "string",
                              "enum": [
                                "extract",
                                "batch",
                                "crawl",
                                "serp",
                                "map"
                              ]
                            },
                            "proxy_type": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "The tier priced, or `null` for `serp` and `map`."
                            },
                            "units": {
                              "type": "integer"
                            },
                            "http": {
                              "type": "object",
                              "description": "The tier that answers an ordinary request.",
                              "properties": {
                                "price_key": {
                                  "type": "string",
                                  "description": "The billing key the unit is charged under (the same keys as on the pricing page)."
                                },
                                "base_usd": {
                                  "type": "number",
                                  "description": "Flat part per unit, in USD."
                                },
                                "per_gb_usd": {
                                  "type": [
                                    "number",
                                    "null"
                                  ],
                                  "description": "Bandwidth meter in USD per GB, when the key has one."
                                },
                                "cap_usd": {
                                  "type": [
                                    "number",
                                    "null"
                                  ],
                                  "description": "Ceiling of the bandwidth part for one unit, when the key has one."
                                },
                                "max_usd": {
                                  "type": "number",
                                  "description": "The most one unit can cost on this tier."
                                },
                                "typical_page_usd": {
                                  "type": "number",
                                  "description": "What a 100 KB page costs on this tier."
                                }
                              }
                            },
                            "render": {
                              "oneOf": [
                                {
                                  "type": "object",
                                  "description": "The browser tier the call can escalate to.",
                                  "properties": {
                                    "price_key": {
                                      "type": "string",
                                      "description": "The billing key the unit is charged under (the same keys as on the pricing page)."
                                    },
                                    "base_usd": {
                                      "type": "number",
                                      "description": "Flat part per unit, in USD."
                                    },
                                    "per_gb_usd": {
                                      "type": [
                                        "number",
                                        "null"
                                      ],
                                      "description": "Bandwidth meter in USD per GB, when the key has one."
                                    },
                                    "cap_usd": {
                                      "type": [
                                        "number",
                                        "null"
                                      ],
                                      "description": "Ceiling of the bandwidth part for one unit, when the key has one."
                                    },
                                    "max_usd": {
                                      "type": "number",
                                      "description": "The most one unit can cost on this tier."
                                    },
                                    "typical_page_usd": {
                                      "type": "number",
                                      "description": "What a 100 KB page costs on this tier."
                                    }
                                  }
                                },
                                {
                                  "type": "null"
                                }
                              ],
                              "description": "`null` when the call has no browser tier (`map`)."
                            },
                            "extra_per_unit_usd": {
                              "type": "number",
                              "description": "Added per unit whatever the tier (AI extraction), when asked."
                            },
                            "min_usd": {
                              "type": "number",
                              "description": "The least the whole request can cost: every unit on the ordinary tier, light pages."
                            },
                            "max_usd": {
                              "type": "number",
                              "description": "The most the whole request can cost: every unit on the browser tier, at its ceiling."
                            },
                            "under_max_cost": {
                              "type": "object",
                              "description": "Present only when `max_cost` was passed.",
                              "properties": {
                                "max_cost_usd": {
                                  "type": "number"
                                },
                                "fits": {
                                  "type": "boolean",
                                  "description": "Whether every unit fits under the ceiling on the tier asked."
                                },
                                "browser_allowed": {
                                  "type": "boolean",
                                  "description": "Whether the ceiling still leaves room for the browser tier."
                                },
                                "units_that_fit": {
                                  "type": "integer",
                                  "description": "How many units fit under the ceiling."
                                }
                              }
                            },
                            "billing_enabled": {
                              "type": "boolean"
                            },
                            "currency": {
                              "type": "string",
                              "enum": [
                                "USD"
                              ]
                            },
                            "note": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/scraper/cost' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/scraper/cost',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/cost\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/cost');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/scraper/unlock": {
      "post": {
        "operationId": "unlockRequest",
        "tags": [
          "Web Unlocker"
        ],
        "summary": "Replay a request through the Web Unlocker",
        "description": "Send a request the way your own HTTP client would (`url`, `method`, `headers`, `body`) and get it back replayed through a residential or mobile exit under a real browser TLS fingerprint. `mode` decides how far the engine goes: `auto` (default) retries a blocked GET/HEAD/OPTIONS on a fresh exit under a different fingerprint and escalates to a headless browser that answers JavaScript challenges; `tls` never opens the browser; `browser` renders straight away. Any other method gets exactly one attempt (a response means the target saw it, and replaying a POST could double-submit). `format` returns `body` as HTML, Markdown or plain text (`bodyBase64` stays the raw page); `max_bytes` caps what one call may move; `timeout_ms` is the total budget, attempts and render included. `actions` runs clicks, typing, scrolls and waits in the browser before the capture; `cache_ttl` answers a repeated GET from a stored copy, which moves no bytes and costs nothing. A page still blocked after every attempt comes back as 200 with `blocked: true`, `blockClass`, `vendor` and `hint`, never as a silent success; `fail_on_block: true` turns it into 424 `target_blocked`. Every answer carries `request_id`, `latency_ms`, `tier_served`, `attempt_log` and `cost`. When the service has the captcha solver enabled, DataDome and AWS WAF challenges are handed to it; any other interactive captcha is returned as `blockClass: \"captcha\"`. This is the same engine as the forward proxy (top of this section), without the proxy protocol: no certificate to install; the same call works on `https://app.quanticdata.io/api/v1/scraper/unlock`. Billing is different from every other Data API call: it is metered in bytes against the tier's prepaid Web Unlocker GB (`premium` = residential exits, `mobile` = mobile exits), not the wallet, and every attempt counts (retries, a blocked page, the browser's page load). Errors: one catalogue for the REST call and the proxy, see Unlock errors above. Field names: every camelCase field is also accepted in snake_case (`fail_on_block`, `success_status_codes`, `tls_profile`, `session_id`, `session_duration`, `keep_headers`, `wait_for_selector`, `wait_ms`, `return_cookies`, `auto_render`), and `max_bytes` / `timeout_ms` / `cache_ttl` are also accepted as `maxBytes` / `timeoutMs` / `cacheTtl`. Many URLs at once: `POST /scraper/unlock/batch`.",
        "x-price-key": "unlock_request",
        "x-pricing-note": "Billed per GB on `usage.bytes`, debited from the prepaid Web Unlocker GB of the chosen tier, never from the wallet. The price per GB of each tier is on the [plans page](https://app.quanticdata.io/plans?network=UNLOCK) of the dashboard and, when the offer is published, in `GET /public/unlock/offer`. 402 when the tier has no usable GB (never bought, used up or expired).",
        "x-rate-limit": "per-tier",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "camelCase and snake_case spellings are both accepted for every field (`failOnBlock` / `fail_on_block`, `timeoutMs` / `timeout_ms`, `maxBytes` / `max_bytes`, `successStatusCodes` / `success_status_codes`, `tlsProfile` / `tls_profile`, `sessionId` / `session_id`, `sessionDuration` / `session_duration`, `keepHeaders` / `keep_headers`, `waitForSelector` / `wait_for_selector`, `waitMs` / `wait_ms`, `returnCookies` / `return_cookies`, `autoRender` / `auto_render`, `cacheTtl` / `cache_ttl`). The keys inside an `actions` entry are camelCase only.",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "maxLength": 2048,
                    "description": "Target URL, `http://` or `https://`. Private, reserved and internal addresses are refused (403 `target_forbidden`); some destinations are not served (403 `target_denied`)."
                  },
                  "method": {
                    "type": "string",
                    "pattern": "^[A-Za-z]{1,16}$",
                    "default": "GET"
                  },
                  "headers": {
                    "$ref": "#/components/schemas/ForwardHeaders",
                    "description": "Headers your own client would send. Most are replaced by a coherent browser fingerprint (User-Agent, Accept, Sec-Fetch-*); auth, cookie, content-type and custom headers are forwarded verbatim. `keepHeaders: true` forwards everything as-is."
                  },
                  "body": {
                    "type": "string",
                    "description": "Request body as UTF-8 text (JSON, form data…). Use this OR `bodyBase64`."
                  },
                  "bodyBase64": {
                    "type": "string",
                    "description": "Request body as base64 for binary payloads. Max 8 MB decoded."
                  },
                  "tier": {
                    "type": "string",
                    "enum": [
                      "premium",
                      "mobile"
                    ],
                    "default": "premium",
                    "description": "Which prepaid pool pays and which exits are used. Anything other than `mobile` is `premium`."
                  },
                  "mode": {
                    "type": "string",
                    "enum": [
                      "auto",
                      "tls",
                      "browser"
                    ],
                    "default": "auto",
                    "description": "How far the engine goes. `auto`: TLS tier first, a new exit and fingerprint on each blocked attempt, then the headless browser (it can start in parallel after repeated blocks); `tls`: TLS tier only, never the browser, a blocked page is returned as-is; `browser`: straight to the headless browser (GET/HEAD). The answer says which tier produced it in `tier_served`. Replaces `autoRender` (`mode: \"tls\"` is the old `autoRender: false`) and `render: \"html\"` (`mode: \"browser\"`)."
                  },
                  "format": {
                    "type": "string",
                    "enum": [
                      "html",
                      "markdown",
                      "text"
                    ],
                    "default": "html",
                    "description": "Format of `body` for HTML responses: the page as HTML, converted to Markdown, or reduced to its text. `bodyBase64` is always the raw page. Ignored when the response is not HTML (JSON, XML, binary); the format served is echoed in `format`."
                  },
                  "max_bytes": {
                    "type": "integer",
                    "minimum": 1024,
                    "description": "Cap on the bytes this call may move across every attempt (request and response bodies, the browser's page load included). The TLS tier stops downloading past the cap; when the bytes moved exceed it the answer is 403 `max_bytes_exceeded` with `usage` and `cost`: the bytes moved are debited. Also accepted as `maxBytes`."
                  },
                  "timeout_ms": {
                    "type": "integer",
                    "minimum": 1000,
                    "maximum": 120000,
                    "default": 60000,
                    "description": "Total budget of the call in milliseconds: every attempt, the browser render and its settle time fit inside it, never in addition. When it runs out before a response the answer is 504 `timeout`. Also accepted as `timeoutMs`."
                  },
                  "fail_on_block": {
                    "type": "boolean",
                    "default": false,
                    "description": "`true`: a page still blocked after every attempt answers 424 `target_blocked` (same diagnostics in `payload`) instead of a 200 with `blocked: true`. The GB moved are debited either way. Also accepted as `failOnBlock`."
                  },
                  "actions": {
                    "type": "array",
                    "maxItems": 20,
                    "items": {
                      "$ref": "#/components/schemas/UnlockAction"
                    },
                    "description": "Browser interactions to run, in order, before the page is captured: at most 20. Actions force the browser tier (`tier_served: \"browser\"`), so they work on GET and HEAD only; together with `mode: \"tls\"` (or `render: false`, `autoRender: false`) they are refused with 400 `bad_request`. REST only: the proxy has no header for them."
                  },
                  "cache_ttl": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 86400,
                    "default": 0,
                    "description": "Seconds a usable answer may be served from the cache; 0 is off. A GET the site answered 2xx and that was not blocked is kept for your account for that long. A later call with the same `url`, `mode`, `format`, `country`, `tier`, render kind and `actions` is answered from the copy: `cache: \"hit\"`, no bytes moved, nothing billed. Also accepted as `cacheTtl`; `x-qp-cache-ttl` on the proxy."
                  },
                  "country": {
                    "$ref": "#/components/schemas/GeoValue",
                    "description": "Exit country, 2-letter code. Without it the exit country is, in order: the site's own country from its ccTLD (`.de`, `.fr`), then the country of your account, then `us`. `customerCountry` / `customer_country` is not a request field: the engine reads the account's country from the account itself."
                  },
                  "state": {
                    "$ref": "#/components/schemas/GeoValue",
                    "description": "Requires `country`."
                  },
                  "city": {
                    "$ref": "#/components/schemas/GeoValue",
                    "description": "Requires `country`."
                  },
                  "rotation": {
                    "type": "string",
                    "enum": [
                      "rotating",
                      "sticky"
                    ],
                    "default": "rotating"
                  },
                  "sessionId": {
                    "type": "string",
                    "maxLength": 64,
                    "description": "Sticky session id — reuse it across calls to keep one exit IP."
                  },
                  "sessionDuration": {
                    "type": "number",
                    "description": "Sticky session lifetime in minutes."
                  },
                  "tlsProfile": {
                    "type": "string",
                    "enum": [
                      "chrome",
                      "firefox",
                      "safari",
                      "safari_ios",
                      "edge",
                      "brave",
                      "mobile"
                    ],
                    "default": "chrome"
                  },
                  "mobile": {
                    "type": "boolean",
                    "default": false,
                    "description": "Mobile Safari fingerprint (fingerprint only — the product tier is `tier`)."
                  },
                  "render": {
                    "oneOf": [
                      {
                        "type": "string",
                        "enum": [
                          "html",
                          "png"
                        ]
                      },
                      {
                        "type": "boolean"
                      }
                    ],
                    "description": "`png` returns a screenshot of the page from the headless browser (GET/HEAD, one render token). `html` or `true` is the same as `mode: \"browser\"`; `false` is the same as `mode: \"tls\"`. `mode` wins when both are sent."
                  },
                  "autoRender": {
                    "type": "boolean",
                    "default": true,
                    "deprecated": true,
                    "description": "Deprecated, use `mode`: `autoRender: false` is `mode: \"tls\"` (no browser escalation of a blocked GET). Still accepted, also as `auto_render`."
                  },
                  "keepHeaders": {
                    "type": "boolean",
                    "default": false,
                    "description": "Send your own identity headers (User-Agent, Accept, Sec-Fetch-*) verbatim instead of the fingerprint's."
                  },
                  "successStatusCodes": {
                    "type": "array",
                    "maxItems": 20,
                    "items": {
                      "type": "integer",
                      "minimum": 100,
                      "maximum": 599
                    },
                    "description": "Origin statuses to accept as success — never treated as a block, never retried."
                  },
                  "timeoutMs": {
                    "type": "integer",
                    "minimum": 1000,
                    "maximum": 120000,
                    "description": "Same as `timeout_ms` (older spelling): the total budget of the call, not a per-attempt timeout."
                  },
                  "failOnBlock": {
                    "type": "boolean",
                    "default": false,
                    "description": "Same as `fail_on_block` (older spelling)."
                  },
                  "waitForSelector": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 256,
                    "description": "Browser tier: CSS selector to wait for before capture."
                  },
                  "waitMs": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 15000,
                    "description": "Browser tier: extra settle time in milliseconds after the page loads."
                  },
                  "returnCookies": {
                    "type": "boolean",
                    "default": false,
                    "description": "Return the origin's cookie jar under `cookies`."
                  },
                  "cookies": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    },
                    "maxProperties": 50,
                    "description": "Cookies merged into the Cookie header sent to the target (e.g. a clearance obtained earlier)."
                  }
                }
              },
              "examples": {
                "basic": {
                  "summary": "One page with the default ladder",
                  "value": {
                    "url": "https://example.com/",
                    "country": "us",
                    "tier": "premium",
                    "mode": "auto",
                    "format": "html",
                    "timeout_ms": 60000,
                    "max_bytes": 5000000
                  }
                },
                "actions_and_cache": {
                  "summary": "Browser actions, then keep the answer for one hour",
                  "value": {
                    "url": "https://example.com/search",
                    "country": "us",
                    "format": "markdown",
                    "cache_ttl": 3600,
                    "actions": [
                      {
                        "clickText": "Accept",
                        "optional": true,
                        "timeoutMs": 3000
                      },
                      {
                        "type": {
                          "selector": "#search",
                          "text": "running shoes"
                        }
                      },
                      {
                        "click": "button[type=submit]"
                      },
                      {
                        "waitForSelector": ".results"
                      },
                      {
                        "scroll": "bottom"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The target's response, replayed, or the block page it answered with (`blocked: true`, see the second example). Both carry the diagnostics (`request_id`, `latency_ms`, `tier_served`, `attempt_log`) and the cost of the call (`usage`, `cost`). The third example is an answer served from the cache. The `cost.usd` figures in the examples are example values, not a price list.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/UnlockResult"
                        }
                      }
                    }
                  ]
                },
                "examples": {
                  "success": {
                    "summary": "Page served by the TLS tier on the first attempt (example values)",
                    "value": {
                      "type": "response",
                      "message": "Unlocker request successful",
                      "payload": {
                        "request_id": "7c1f1b2e-5d3a-4a9e-9c0b-2f6e8a1d4b73",
                        "status": 200,
                        "headers": {
                          "content-type": "text/html; charset=utf-8",
                          "cache-control": "max-age=600"
                        },
                        "body": "<!doctype html><html><head><title>Example Domain</title></head><body><p>This domain is for use in illustrative examples in documents.</p></body></html>",
                        "bodyBase64": "PCFkb2N0eXBlIGh0bWw+PGh0bWw+PGhlYWQ+PHRpdGxlPkV4YW1wbGUgRG9tYWluPC90aXRsZT48L2hlYWQ+PGJvZHk+PGgxPkV4YW1wbGUgRG9tYWluPC9oMT48cD5UaGlzIGRvbWFpbiBpcyBmb3IgdXNlIGluIGlsbHVzdHJhdGl2ZSBleGFtcGxlcyBpbiBkb2N1bWVudHMuPC9wPjwvYm9keT48L2h0bWw+",
                        "finalUrl": "https://example.com/",
                        "contentType": "text/html; charset=utf-8",
                        "profile": "chrome",
                        "attempts": 1,
                        "cache": "off",
                        "blocked": false,
                        "clearance": "miss",
                        "exitSessionId": "s_2f91",
                        "strategy": {
                          "startTier": "tls",
                          "hedged": false
                        },
                        "rendered": false,
                        "escalated": false,
                        "mode": "auto",
                        "tier_served": "tls",
                        "format": "html",
                        "tier": "premium",
                        "geo": {
                          "country": "us",
                          "state": null,
                          "city": null,
                          "rotation": "rotating"
                        },
                        "latency_ms": 1840,
                        "attempt_log": [
                          {
                            "tier": "tls",
                            "profile": "chrome",
                            "exit_country": "us",
                            "outcome": "ok",
                            "ms": 1840,
                            "bytes": 18432
                          }
                        ],
                        "usage": {
                          "bytes": 18432,
                          "unlock_gb_remaining": 4.98,
                          "unlock_gb_purchased": 5
                        },
                        "cost": {
                          "bytes": 18432,
                          "usd": 0.000044,
                          "billed": true
                        }
                      },
                      "pagination": {}
                    }
                  },
                  "blocked": {
                    "summary": "Still blocked after three TLS attempts and the browser (no fail_on_block) (example values)",
                    "value": {
                      "type": "response",
                      "message": "Unlocker request successful",
                      "payload": {
                        "request_id": "0b7d9e42-1c35-4f8a-b6d2-9e4f3a7c5d11",
                        "status": 403,
                        "headers": {
                          "content-type": "text/html; charset=utf-8",
                          "cache-control": "private, max-age=0, no-store"
                        },
                        "body": "<!doctype html><html><head><title>Access denied</title></head><body><p>Please verify you are a human</p></body></html>",
                        "bodyBase64": "PCFkb2N0eXBlIGh0bWw+PGh0bWw+PGhlYWQ+PHRpdGxlPkFjY2VzcyBkZW5pZWQ8L3RpdGxlPjwvaGVhZD48Ym9keT48aDE+UGxlYXNlIHZlcmlmeSB5b3UgYXJlIGEgaHVtYW48L2gxPjwvYm9keT48L2h0bWw+",
                        "finalUrl": "https://example.com/pricing",
                        "contentType": "text/html; charset=utf-8",
                        "profile": "chrome",
                        "attempts": 4,
                        "cache": "off",
                        "blocked": true,
                        "blockReason": "js_challenge",
                        "blockClass": "js_challenge",
                        "vendor": "cloudflare",
                        "hint": "Every TLS attempt and the browser were refused from us. Try tier \"mobile\" or another country, or a sticky session that already holds a clearance cookie.",
                        "clearance": "miss",
                        "exitSessionId": "s_7a04",
                        "strategy": {
                          "startTier": "tls",
                          "hedged": true
                        },
                        "rendered": true,
                        "escalated": true,
                        "mode": "auto",
                        "tier_served": "browser",
                        "format": "html",
                        "tier": "premium",
                        "geo": {
                          "country": "us",
                          "state": null,
                          "city": null,
                          "rotation": "rotating"
                        },
                        "latency_ms": 13095,
                        "attempt_log": [
                          {
                            "tier": "tls",
                            "profile": "chrome",
                            "exit_country": "us",
                            "outcome": "blocked",
                            "ms": 1210,
                            "bytes": 42010,
                            "block_class": "js_challenge",
                            "reason": "js_challenge"
                          },
                          {
                            "tier": "tls",
                            "profile": "firefox",
                            "exit_country": "us",
                            "outcome": "blocked",
                            "ms": 980,
                            "bytes": 41366,
                            "block_class": "js_challenge",
                            "reason": "js_challenge"
                          },
                          {
                            "tier": "tls",
                            "profile": "safari",
                            "exit_country": "us",
                            "outcome": "blocked",
                            "ms": 1105,
                            "bytes": 41620,
                            "block_class": "js_challenge",
                            "reason": "js_challenge"
                          },
                          {
                            "tier": "browser",
                            "profile": "chrome",
                            "exit_country": "us",
                            "outcome": "blocked",
                            "ms": 9800,
                            "bytes": 309504,
                            "block_class": "js_challenge",
                            "reason": "challenge:challenge-platform"
                          }
                        ],
                        "usage": {
                          "bytes": 434500,
                          "unlock_gb_remaining": 4.979,
                          "unlock_gb_purchased": 5
                        },
                        "cost": {
                          "bytes": 434500,
                          "usd": 0.001043,
                          "billed": true
                        }
                      },
                      "pagination": {}
                    }
                  },
                  "cache_hit": {
                    "summary": "Answered from the cache (cache_ttl set, a copy was there): nothing moved, nothing billed",
                    "value": {
                      "type": "response",
                      "message": "Unlocker request successful",
                      "payload": {
                        "request_id": "c2a4f6b8-3d1e-4f70-9a2b-5e8c1d7f0a36",
                        "status": 200,
                        "headers": {
                          "content-type": "text/html; charset=utf-8",
                          "cache-control": "max-age=600"
                        },
                        "body": "<!doctype html><html><head><title>Example Domain</title></head><body><p>This domain is for use in illustrative examples in documents.</p></body></html>",
                        "bodyBase64": "PCFkb2N0eXBlIGh0bWw+PGh0bWw+PGhlYWQ+PHRpdGxlPkV4YW1wbGUgRG9tYWluPC90aXRsZT48L2hlYWQ+PGJvZHk+PGgxPkV4YW1wbGUgRG9tYWluPC9oMT48cD5UaGlzIGRvbWFpbiBpcyBmb3IgdXNlIGluIGlsbHVzdHJhdGl2ZSBleGFtcGxlcyBpbiBkb2N1bWVudHMuPC9wPjwvYm9keT48L2h0bWw+",
                        "finalUrl": "https://example.com/",
                        "contentType": "text/html; charset=utf-8",
                        "profile": "chrome",
                        "attempts": 0,
                        "blocked": false,
                        "rendered": false,
                        "escalated": false,
                        "mode": "auto",
                        "tier_served": "tls",
                        "format": "html",
                        "tier": "premium",
                        "geo": {
                          "country": "us",
                          "state": null,
                          "city": null,
                          "rotation": "rotating"
                        },
                        "latency_ms": 12,
                        "cache": "hit",
                        "cached_at": "2026-11-11T09:30:01.000Z",
                        "attempt_log": [
                          {
                            "tier": "cache",
                            "outcome": "ok",
                            "ms": 12,
                            "bytes": 0
                          }
                        ],
                        "usage": {
                          "bytes": 0,
                          "unlock_gb_remaining": 4.98,
                          "unlock_gb_purchased": 5
                        },
                        "cost": {
                          "bytes": 0,
                          "usd": 0,
                          "billed": false
                        }
                      },
                      "pagination": {}
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`bad_request`: a parameter is invalid; `message` names it and the rule it broke. Nothing ran, nothing billed.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/UnlockErrorPayload"
                        }
                      }
                    }
                  ]
                },
                "examples": {
                  "bad_request": {
                    "summary": "Invalid parameter",
                    "value": {
                      "type": "error",
                      "message": "Invalid timeout_ms. Must be an integer between 1000 and 120000",
                      "payload": {
                        "code": "bad_request",
                        "retryable": false,
                        "billed": false,
                        "hint": "Fix the parameter named in the message and send the request again.",
                        "doc_url": "https://quanticdata.io/docs/#unlock-errors"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "description": "`no_credit`: the tier has no usable Web Unlocker GB, never bought, used up or expired. `message` says which and ends with the link to buy GB (paid from the wallet, separate from the Data API free credit); `payload.reason` is `never_bought`, `used_up` or `expired` and `payload.buy_url` is the same link. Nothing billed.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/UnlockErrorPayload"
                        }
                      }
                    }
                  ]
                },
                "examples": {
                  "no_credit": {
                    "summary": "No GB on the tier",
                    "value": {
                      "type": "error",
                      "message": "This account has no residential Web Unlocker GB yet. The unlocker is prepaid per GB, separate from the Data API free credit, and paid from your wallet balance. Buy GB, then retry, your API key stays the same: https://app.quanticdata.io/plans?network=UNLOCK&utm_source=api&utm_medium=402&utm_campaign=web-unlocker",
                      "payload": {
                        "code": "no_credit",
                        "retryable": false,
                        "billed": false,
                        "hint": "Buy GB from the dashboard, then retry with the same key or proxy user.",
                        "doc_url": "https://quanticdata.io/docs/#unlock-errors",
                        "reason": "never_bought",
                        "tier": "premium",
                        "unlock_gb_remaining": 0,
                        "unlock_gb_purchased": 0,
                        "expires_at": null,
                        "expired": false,
                        "buy_url": "https://app.quanticdata.io/plans?network=UNLOCK&utm_source=api&utm_medium=402&utm_campaign=web-unlocker"
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`target_forbidden` (private, reserved or internal address), `target_denied` (a destination the unlocker does not serve) or `no_exit_pool` (the account has no exit pool for the tier, e.g. `mobile` without a mobile sub-user): the request did not run, nothing billed. `max_bytes_exceeded`: the bytes moved went over `max_bytes`; `payload.usage` and `payload.cost` say how many, and they are debited.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/UnlockErrorPayload"
                        }
                      }
                    }
                  ]
                },
                "examples": {
                  "no_exit_pool": {
                    "summary": "No exit pool for the tier",
                    "value": {
                      "type": "error",
                      "message": "The mobile Web Unlocker has no exit pool for your account yet.",
                      "payload": {
                        "code": "no_exit_pool",
                        "retryable": false,
                        "billed": false,
                        "hint": "Buy GB on this tier so its exit pool is set up, or use tier \"premium\".",
                        "doc_url": "https://quanticdata.io/docs/#unlock-errors",
                        "tier": "mobile"
                      }
                    }
                  },
                  "target_forbidden": {
                    "summary": "Private or reserved address",
                    "value": {
                      "type": "error",
                      "message": "This target is not allowed through the unlocker (private or reserved address).",
                      "payload": {
                        "code": "target_forbidden",
                        "retryable": false,
                        "billed": false,
                        "hint": "The unlocker only fetches public hosts.",
                        "doc_url": "https://quanticdata.io/docs/#unlock-errors",
                        "url": "http://10.0.0.8/admin"
                      }
                    }
                  },
                  "target_denied": {
                    "summary": "Destination not served",
                    "value": {
                      "type": "error",
                      "message": "This destination is not served by the unlocker.",
                      "payload": {
                        "code": "target_denied",
                        "retryable": false,
                        "billed": false,
                        "hint": "Pick another target; this one is on the deny list.",
                        "doc_url": "https://quanticdata.io/docs/#unlock-errors",
                        "url": "https://example-bank.test/login"
                      }
                    }
                  },
                  "max_bytes_exceeded": {
                    "summary": "Over max_bytes (example values)",
                    "value": {
                      "type": "error",
                      "message": "The call moved more bytes than max_bytes allows.",
                      "payload": {
                        "code": "max_bytes_exceeded",
                        "retryable": false,
                        "billed": true,
                        "hint": "Raise max_bytes, or leave it out to accept the full page.",
                        "doc_url": "https://quanticdata.io/docs/#unlock-errors",
                        "request_id": "3a9c5e71-8f2d-4b06-a1e4-6c7d2f9b0e55",
                        "max_bytes": 2097152,
                        "usage": {
                          "bytes": 2654208,
                          "unlock_gb_remaining": 4.977,
                          "unlock_gb_purchased": 5
                        },
                        "cost": {
                          "bytes": 2654208,
                          "usd": 0.00637,
                          "billed": true
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`action_failed`, only with `actions`: the page loaded but one of the actions could not run. `message` names the action by its position and shape and says why. Not retryable as it is, nothing billed.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/UnlockErrorPayload"
                        }
                      }
                    }
                  ]
                },
                "examples": {
                  "action_failed": {
                    "summary": "A selector that matched nothing",
                    "value": {
                      "type": "error",
                      "message": "Action 2 failed ({\"waitForSelector\":\".results\"}): nothing on the page matched it within 15000 ms",
                      "payload": {
                        "code": "action_failed",
                        "retryable": false,
                        "billed": false,
                        "hint": "The page loaded but one of your actions could not run. Check the selector or the text of the action named in the message.",
                        "doc_url": "https://quanticdata.io/docs/#unlock-errors",
                        "url": "https://example.com/search?q=shoes",
                        "request_id": "7c1f0a9e2b4d6e80",
                        "latency_ms": 17480,
                        "mode": "auto",
                        "attempt_log": []
                      }
                    }
                  }
                }
              }
            }
          },
          "424": {
            "description": "`target_blocked`, only with `fail_on_block: true`: every attempt came back blocked. Same diagnostics as the 200 form (`status` of the block page, `blockReason`, `blockClass`, `vendor`, `attempts`, `attempt_log`, `tier_served`); the GB moved are debited (`usage`, `cost`). Retryable: later, on the `mobile` tier, from another country or with `mode: \"browser\"`.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/UnlockErrorPayload"
                        }
                      }
                    }
                  ]
                },
                "examples": {
                  "target_blocked": {
                    "summary": "Blocked on every tier (example values)",
                    "value": {
                      "type": "error",
                      "message": "The target refused the request on every tier.",
                      "payload": {
                        "code": "target_blocked",
                        "retryable": true,
                        "billed": true,
                        "hint": "Retry with mode \"browser\", another country, or a sticky session; drop fail_on_block to receive the blocked page as a 200.",
                        "doc_url": "https://quanticdata.io/docs/#unlock-errors",
                        "request_id": "0b7d9e42-1c35-4f8a-b6d2-9e4f3a7c5d11",
                        "status": 403,
                        "blockReason": "js_challenge",
                        "blockClass": "js_challenge",
                        "vendor": "cloudflare",
                        "attempts": 4,
                        "tier_served": "browser",
                        "rendered": true,
                        "escalated": true,
                        "latency_ms": 13095,
                        "attempt_log": [
                          {
                            "tier": "tls",
                            "profile": "chrome",
                            "exit_country": "us",
                            "outcome": "blocked",
                            "ms": 1210,
                            "bytes": 42010,
                            "block_class": "js_challenge",
                            "reason": "js_challenge"
                          },
                          {
                            "tier": "tls",
                            "profile": "firefox",
                            "exit_country": "us",
                            "outcome": "blocked",
                            "ms": 980,
                            "bytes": 41366,
                            "block_class": "js_challenge",
                            "reason": "js_challenge"
                          },
                          {
                            "tier": "tls",
                            "profile": "safari",
                            "exit_country": "us",
                            "outcome": "blocked",
                            "ms": 1105,
                            "bytes": 41620,
                            "block_class": "js_challenge",
                            "reason": "js_challenge"
                          },
                          {
                            "tier": "browser",
                            "profile": "chrome",
                            "exit_country": "us",
                            "outcome": "blocked",
                            "ms": 9800,
                            "bytes": 309504,
                            "block_class": "js_challenge",
                            "reason": "challenge:challenge-platform"
                          }
                        ],
                        "usage": {
                          "bytes": 434500,
                          "unlock_gb_remaining": 4.979,
                          "unlock_gb_purchased": 5
                        },
                        "cost": {
                          "bytes": 434500,
                          "usd": 0.001043,
                          "billed": true
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`rate_limited`: the requests per minute or the concurrent requests of the account's tier (see Rate limits and tiers). Back off for `Retry-After` seconds. Not billed.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/UnlockErrorPayload"
                        }
                      }
                    }
                  ]
                },
                "examples": {
                  "rate_limited": {
                    "summary": "Per-minute limit of the tier",
                    "value": {
                      "type": "error",
                      "message": "Too many requests for this account right now.",
                      "payload": {
                        "code": "rate_limited",
                        "retryable": true,
                        "billed": false,
                        "hint": "Wait for Retry-After seconds, lower your concurrency, or move to a plan with a higher limit.",
                        "doc_url": "https://quanticdata.io/docs/#unlock-errors",
                        "retry_after": 5
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "`internal_error`: an error on our side. Retryable; not billed. Quote `request_id` to support when it persists.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/UnlockErrorPayload"
                        }
                      }
                    }
                  ]
                },
                "examples": {
                  "internal_error": {
                    "summary": "Error on our side",
                    "value": {
                      "type": "error",
                      "message": "The unlocker hit an internal error.",
                      "payload": {
                        "code": "internal_error",
                        "retryable": true,
                        "billed": false,
                        "hint": "Retry; if it persists contact support with the request_id.",
                        "doc_url": "https://quanticdata.io/docs/#unlock-errors",
                        "request_id": "e4d1c6a0-2b7f-4c58-9a13-7f0e5b2d8c91"
                      }
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Temporary, retryable, never billed: `upstream_failed` (the exit or the target could not be reached), `render_failed` (the browser could not load the page) or `service_unavailable` (the engine or the API is not answering; also while the Data API is switched off for the account). On the proxy the same codes answer 503, never 407.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/UnlockErrorPayload"
                        }
                      }
                    }
                  ]
                },
                "examples": {
                  "upstream_failed": {
                    "summary": "Exit or target unreachable",
                    "value": {
                      "type": "error",
                      "message": "The exit or the target could not be reached.",
                      "payload": {
                        "code": "upstream_failed",
                        "retryable": true,
                        "billed": false,
                        "hint": "Retry: the next attempt runs on a fresh exit.",
                        "doc_url": "https://quanticdata.io/docs/#unlock-errors",
                        "request_id": "9f2b4d6e-0a1c-4e83-b5d7-3c8e1f6a2d40"
                      }
                    }
                  },
                  "render_failed": {
                    "summary": "Browser could not load the page",
                    "value": {
                      "type": "error",
                      "message": "The browser could not load the page.",
                      "payload": {
                        "code": "render_failed",
                        "retryable": true,
                        "billed": false,
                        "hint": "Retry; if it keeps failing use mode \"tls\" or a longer timeout_ms.",
                        "doc_url": "https://quanticdata.io/docs/#unlock-errors",
                        "request_id": "1d8e3f5a-7b2c-4906-8e4d-5a6f7c3b9e22"
                      }
                    }
                  },
                  "service_unavailable": {
                    "summary": "Engine not answering",
                    "value": {
                      "type": "error",
                      "message": "The unlocker service is not responding.",
                      "payload": {
                        "code": "service_unavailable",
                        "retryable": true,
                        "billed": false,
                        "hint": "Retry in a few seconds.",
                        "doc_url": "https://quanticdata.io/docs/#unlock-errors"
                      }
                    }
                  }
                }
              }
            }
          },
          "504": {
            "description": "`timeout`: `timeout_ms` ran out before a response (every attempt and the browser render share that budget). Retryable; not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/UnlockErrorPayload"
                        }
                      }
                    }
                  ]
                },
                "examples": {
                  "timeout": {
                    "summary": "Budget exhausted",
                    "value": {
                      "type": "error",
                      "message": "No response before timeout_ms ran out.",
                      "payload": {
                        "code": "timeout",
                        "retryable": true,
                        "billed": false,
                        "hint": "Raise timeout_ms (up to 120000) or use mode \"tls\" for a faster first answer.",
                        "doc_url": "https://quanticdata.io/docs/#unlock-errors",
                        "request_id": "6b0c2e4d-9a8f-4d17-b3e5-2f1a7c9d0e68",
                        "timeout_ms": 60000
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST https://app.quanticdata.io/api/v1/scraper/unlock \\\n  -H \"Authorization: Bearer qd_live_YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"url\": \"https://example.com/\", \"country\": \"us\"}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    \"https://app.quanticdata.io/api/v1/scraper/unlock\",\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\"url\": \"https://example.com/\", \"country\": \"us\"},\n    timeout=130,\n)\npage = r.json()[\"payload\"]\nprint(page[\"status\"], page[\"blocked\"], page[\"latency_ms\"], page[\"cost\"])\nprint(page[\"body\"][:500])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://app.quanticdata.io/api/v1/scraper/unlock\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer qd_live_YOUR_API_KEY\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({ url: \"https://example.com/\", country: \"us\" }),\n});\nconst { payload: page } = await res.json();\nconsole.log(page.status, page.blocked, page.latency_ms, page.cost);\nconsole.log(page.body.slice(0, 500));",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init(\"https://app.quanticdata.io/api/v1/scraper/unlock\");\ncurl_setopt_array($ch, [\n  CURLOPT_POST => true,\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_TIMEOUT => 130,\n  CURLOPT_HTTPHEADER => [\"Authorization: Bearer qd_live_YOUR_API_KEY\", \"Content-Type: application/json\"],\n  CURLOPT_POSTFIELDS => json_encode([\"url\" => \"https://example.com/\", \"country\" => \"us\"]),\n]);\n$page = json_decode(curl_exec($ch), true)[\"payload\"];\necho $page[\"status\"], \" \", $page[\"blocked\"] ? \"blocked\" : \"ok\", \" \", $page[\"latency_ms\"], \" ms\\n\";\necho substr($page[\"body\"], 0, 500);",
            "x-id": "php"
          },
          {
            "lang": "go",
            "label": "Go",
            "source": "package main\n\nimport (\n\t\"bytes\"\n\t\"encoding/json\"\n\t\"fmt\"\n\t\"net/http\"\n)\n\nfunc main() {\n\tbody, _ := json.Marshal(map[string]string{\"url\": \"https://example.com/\", \"country\": \"us\"})\n\treq, _ := http.NewRequest(\"POST\", \"https://app.quanticdata.io/api/v1/scraper/unlock\", bytes.NewReader(body))\n\treq.Header.Set(\"Authorization\", \"Bearer qd_live_YOUR_API_KEY\")\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tvar out struct {\n\t\tPayload struct {\n\t\t\tStatus    int    `json:\"status\"`\n\t\t\tBlocked   bool   `json:\"blocked\"`\n\t\t\tLatencyMs int    `json:\"latency_ms\"`\n\t\t\tBody      string `json:\"body\"`\n\t\t} `json:\"payload\"`\n\t}\n\tjson.NewDecoder(res.Body).Decode(&out)\n\tfmt.Println(out.Payload.Status, out.Payload.Blocked, out.Payload.LatencyMs, len(out.Payload.Body))\n}",
            "x-id": "go"
          }
        ]
      }
    },
    "/scraper/unlock/batch": {
      "post": {
        "operationId": "startUnlockBatch",
        "tags": [
          "Web Unlocker"
        ],
        "summary": "Unlock many URLs asynchronously",
        "description": "Starts an asynchronous job of 1 to 100 unlock calls and answers 202 with its `batch_id` at once. Each entry of `requests` is a REST call: `url` plus any field of `POST /scraper/unlock`, `actions` and `cache_ttl` included. `defaults` holds fields applied to every item; an item's own field wins. `urls` is a shorthand for `requests` when the items are plain URLs: send one or the other. One batch runs on one tier and one exit setup, so `tier` is set at the top level, and `state`, `city`, `rotation`, `session_id` and `session_duration` only in `defaults`; `country` may differ per item unless `defaults` sets a state or a city. `fail_on_block` has no effect: every result carries `blocked`. `concurrency` (1 to 5, default 3) is how many items run at the same time. Poll `GET /scraper/unlock/batch/{batch_id}` for the results, or pass `webhook_url` to receive the finished batch in one POST. Same API key, same gate and same rate limits as the REST call; a batch with browser items takes one browser-render token when it is submitted. Billing: a batch spends the same prepaid GB of the tier, and every item is metered like a single call. The tier needs usable GB when the batch starts: without them the answer is 402 `no_credit`, and a batch never runs on a trial. Errors use the Unlock errors catalogue above.",
        "x-price-key": "unlock_request",
        "x-pricing-note": "Every item is billed like a single call: per GB on the bytes it moved, from the prepaid Web Unlocker GB of the tier. The price per GB of each tier is on the [plans page](https://app.quanticdata.io/plans?network=UNLOCK) of the dashboard and, when the offer is published, in `GET /public/unlock/offer`.",
        "x-rate-limit": "per-tier",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "Send `requests`, or `urls` as a shorthand, not both: 1 to 100 items.",
                "properties": {
                  "requests": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 100,
                    "items": {
                      "$ref": "#/components/schemas/UnlockBatchItemRequest"
                    },
                    "description": "The unlock calls to run."
                  },
                  "urls": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 100,
                    "items": {
                      "type": "string",
                      "maxLength": 2048
                    },
                    "description": "Shorthand for `requests` when every item is only a URL."
                  },
                  "defaults": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Fields of `POST /scraper/unlock` applied to every item (`country`, `mode`, `format`, `cache_ttl`, `timeout_ms`...); an item's own field wins. `state`, `city`, `rotation`, `session_id` and `session_duration` can only be set here. `url` cannot."
                  },
                  "webhook_url": {
                    "type": "string",
                    "maxLength": 2048,
                    "description": "Public `http://` or `https://` URL, at most 2048 characters. When the batch ends it receives one POST with the batch view: the same JSON as `GET /scraper/unlock/batch/{batch_id}`, without bodies."
                  },
                  "concurrency": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 5,
                    "default": 3,
                    "description": "How many items run at the same time."
                  },
                  "tier": {
                    "type": "string",
                    "enum": [
                      "premium",
                      "mobile"
                    ],
                    "default": "premium",
                    "description": "Which prepaid pool pays the batch and which exits are used, for every item. `defaults.tier` is read the same way."
                  }
                }
              },
              "example": {
                "requests": [
                  {
                    "url": "https://example.com/a"
                  },
                  {
                    "url": "https://example.com/b",
                    "mode": "browser",
                    "wait_for_selector": "#prices"
                  },
                  {
                    "url": "https://example.com/c"
                  }
                ],
                "defaults": {
                  "country": "us",
                  "format": "markdown",
                  "cache_ttl": 3600
                },
                "concurrency": 3,
                "webhook_url": "https://hooks.example.com/unlock-batch"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Batch accepted and running.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/UnlockBatchStarted"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Batch accepted",
                  "payload": {
                    "batch_id": "ub_5e1c9a40d27f",
                    "status": "running",
                    "total": 3,
                    "status_url": "/api/v1/scraper/unlock/batch/ub_5e1c9a40d27f"
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "description": "`bad_request`: the body or an item is invalid; `message` names the item (`requests[3]: …`) and the rule it broke. Nothing ran, nothing billed.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/UnlockErrorPayload"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "error",
                  "message": "requests[1]: rotation applies to the whole batch; set it in defaults",
                  "payload": {
                    "code": "bad_request",
                    "retryable": false,
                    "billed": false,
                    "hint": "Fix the parameter named in the message and send the request again.",
                    "doc_url": "https://quanticdata.io/docs/#unlock-errors"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "description": "`no_credit`: the tier has no usable Web Unlocker GB, never bought, used up or expired. `payload.reason` says which and `payload.buy_url` is the page to buy GB. A batch never runs on a trial. Nothing ran, nothing billed.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/UnlockErrorPayload"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "error",
                  "message": "This account has no residential Web Unlocker GB yet. The unlocker is prepaid per GB, separate from the Data API free credit, and paid from your wallet balance. Buy GB, then retry, your API key stays the same: https://app.quanticdata.io/plans?network=UNLOCK&utm_source=api&utm_medium=402&utm_campaign=web-unlocker",
                  "payload": {
                    "code": "no_credit",
                    "retryable": false,
                    "billed": false,
                    "hint": "Buy GB from the dashboard, then retry with the same key or proxy user.",
                    "doc_url": "https://quanticdata.io/docs/#unlock-errors",
                    "reason": "never_bought",
                    "tier": "premium",
                    "unlock_gb_remaining": 0,
                    "unlock_gb_purchased": 0,
                    "expires_at": null,
                    "expired": false,
                    "buy_url": "https://app.quanticdata.io/plans?network=UNLOCK&utm_source=api&utm_medium=402&utm_campaign=web-unlocker"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`no_exit_pool`: the account has no exit pool for the tier (e.g. `mobile` without mobile GB). Nothing ran, nothing billed.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/UnlockErrorPayload"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "error",
                  "message": "The mobile Web Unlocker has no exit pool for your account yet. Buy mobile unlocker GB, or use the premium tier.",
                  "payload": {
                    "code": "no_exit_pool",
                    "retryable": false,
                    "billed": false,
                    "hint": "Buy GB on this tier so its exit pool is set up, or use tier \"premium\".",
                    "doc_url": "https://quanticdata.io/docs/#unlock-errors",
                    "tier": "mobile"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`rate_limited`: the requests per minute, the concurrent requests or the browser-render budget of the account's tier (see Rate limits and tiers). Back off for `Retry-After` seconds. Not billed.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/UnlockErrorPayload"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "error",
                  "message": "Too many requests for this account right now.",
                  "payload": {
                    "code": "rate_limited",
                    "retryable": true,
                    "billed": false,
                    "hint": "Wait for Retry-After seconds, lower your concurrency, or move to a plan with a higher limit.",
                    "doc_url": "https://quanticdata.io/docs/#unlock-errors",
                    "retry_after": 5
                  }
                }
              }
            }
          },
          "500": {
            "description": "`internal_error`: an error on our side. Retryable; not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/UnlockErrorPayload"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "error",
                  "message": "The unlocker hit an internal error.",
                  "payload": {
                    "code": "internal_error",
                    "retryable": true,
                    "billed": false,
                    "hint": "Retry; if it persists contact support with the request_id.",
                    "doc_url": "https://quanticdata.io/docs/#unlock-errors"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`service_unavailable`: the engine or the API is not answering. Retryable; nothing was started or billed.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/UnlockErrorPayload"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "error",
                  "message": "The unlocker service is not responding.",
                  "payload": {
                    "code": "service_unavailable",
                    "retryable": true,
                    "billed": false,
                    "hint": "Retry in a few seconds.",
                    "doc_url": "https://quanticdata.io/docs/#unlock-errors"
                  }
                }
              }
            }
          },
          "504": {
            "description": "`timeout`: the engine did not accept the request in time. Retryable; not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/UnlockErrorPayload"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "error",
                  "message": "No response before timeout_ms ran out.",
                  "payload": {
                    "code": "timeout",
                    "retryable": true,
                    "billed": false,
                    "hint": "Raise timeout_ms (up to 120000) or use mode \"tls\" for a faster first answer.",
                    "doc_url": "https://quanticdata.io/docs/#unlock-errors"
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/scraper/unlock/batch' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"requests\":[{\"url\":\"https://example.com/a\"},{\"url\":\"https://example.com/b\",\"mode\":\"browser\",\"wait_for_selector\":\"#prices\"},{\"url\":\"https://example.com/c\"}],\"defaults\":{\"country\":\"us\",\"format\":\"markdown\",\"cache_ttl\":3600},\"concurrency\":3,\"webhook_url\":\"https://hooks.example.com/unlock-batch\"}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/scraper/unlock/batch',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\n        \"requests\": [\n            {\n                \"url\": \"https://example.com/a\"\n            },\n            {\n                \"url\": \"https://example.com/b\",\n                \"mode\": \"browser\",\n                \"wait_for_selector\": \"#prices\"\n            },\n            {\n                \"url\": \"https://example.com/c\"\n            }\n        ],\n        \"defaults\": {\n            \"country\": \"us\",\n            \"format\": \"markdown\",\n            \"cache_ttl\": 3600\n        },\n        \"concurrency\": 3,\n        \"webhook_url\": \"https://hooks.example.com/unlock-batch\"\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/unlock/batch\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"requests\": [\n      {\n        \"url\": \"https://example.com/a\"\n      },\n      {\n        \"url\": \"https://example.com/b\",\n        \"mode\": \"browser\",\n        \"wait_for_selector\": \"#prices\"\n      },\n      {\n        \"url\": \"https://example.com/c\"\n      }\n    ],\n    \"defaults\": {\n      \"country\": \"us\",\n      \"format\": \"markdown\",\n      \"cache_ttl\": 3600\n    },\n    \"concurrency\": 3,\n    \"webhook_url\": \"https://hooks.example.com/unlock-batch\"\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/unlock/batch');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'requests' => [[\n      'url' => 'https://example.com/a'\n    ], [\n      'url' => 'https://example.com/b',\n      'mode' => 'browser',\n      'wait_for_selector' => '#prices'\n    ], [\n      'url' => 'https://example.com/c'\n    ]],\n    'defaults' => [\n      'country' => 'us',\n      'format' => 'markdown',\n      'cache_ttl' => 3600\n    ],\n    'concurrency' => 3,\n    'webhook_url' => 'https://hooks.example.com/unlock-batch'\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/scraper/unlock/batch/{batch_id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/unlockBatchId"
        }
      ],
      "get": {
        "operationId": "getUnlockBatch",
        "tags": [
          "Web Unlocker"
        ],
        "summary": "Poll an unlock batch",
        "description": "Progress and results of a batch you own: `status`, the counters (`total`, `completed`, `ok`, `blocked`, `failed`) and `results`, one entry per item with the diagnostics and the cost of a single call. Bodies are left out unless you ask `include=body`; then each item carries `body` (text, in the `format` it asked for) or `body_base64`. `offset` and `limit` page through `results`: 50 per page by default, at most 100. A batch is kept for one hour after it ends. Free to poll.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "parameters": [
          {
            "name": "include",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "body"
              ]
            },
            "description": "`body` adds each item's page to `results`."
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            },
            "description": "First result to return."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            },
            "description": "How many results to return."
          }
        ],
        "responses": {
          "200": {
            "description": "The batch view. The `cost.usd` figures in the example are example values, not a price list.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/UnlockBatchJob"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Batch status",
                  "payload": {
                    "batch_id": "ub_5e1c9a40d27f",
                    "status": "completed",
                    "total": 3,
                    "completed": 3,
                    "ok": 1,
                    "blocked": 1,
                    "failed": 1,
                    "created_at": "2026-11-11T09:30:00.000Z",
                    "finished_at": "2026-11-11T09:31:02.000Z",
                    "results": [
                      {
                        "index": 0,
                        "url": "https://example.com/a",
                        "status": 200,
                        "blocked": false,
                        "request_id": "7c1f1b2e-5d3a-4a9e-9c0b-2f6e8a1d4b73",
                        "latency_ms": 1840,
                        "tier_served": "tls",
                        "attempts": 1,
                        "cost": {
                          "bytes": 18432,
                          "usd": 0.000044,
                          "billed": true
                        },
                        "content_type": "text/html; charset=utf-8"
                      },
                      {
                        "index": 1,
                        "url": "https://example.com/b",
                        "status": 403,
                        "blocked": true,
                        "block_class": "js_challenge",
                        "vendor": "cloudflare",
                        "request_id": "0b7d9e42-1c35-4f8a-b6d2-9e4f3a7c5d11",
                        "latency_ms": 13095,
                        "tier_served": "browser",
                        "attempts": 4,
                        "cost": {
                          "bytes": 434500,
                          "usd": 0.001043,
                          "billed": true
                        },
                        "content_type": "text/html; charset=utf-8"
                      },
                      {
                        "index": 2,
                        "url": "https://example.com/c",
                        "status": null,
                        "blocked": false,
                        "request_id": "6b0c2e4d-9a8f-4d17-b3e5-2f1a7c9d0e68",
                        "latency_ms": 60000,
                        "tier_served": null,
                        "attempts": 1,
                        "cost": {
                          "bytes": 0,
                          "usd": 0,
                          "billed": false
                        },
                        "error": {
                          "code": "timeout",
                          "message": "No response before timeout_ms ran out."
                        }
                      }
                    ]
                  },
                  "pagination": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "The batch id is unknown, belongs to another account, or the batch ended more than one hour ago: one and the same answer, so an id cannot be probed. The payload has the shape of the Unlock errors catalogue, with `code: \"bad_request\"`.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/UnlockErrorPayload"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "error",
                  "message": "Batch not found. A batch is kept for one hour after it finishes.",
                  "payload": {
                    "code": "bad_request",
                    "retryable": false,
                    "billed": false,
                    "hint": "Fix the parameter named in the message and send the request again.",
                    "doc_url": "https://quanticdata.io/docs/#unlock-errors"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`rate_limited`: the requests per minute, the concurrent requests or the browser-render budget of the account's tier (see Rate limits and tiers). Back off for `Retry-After` seconds. Not billed.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/UnlockErrorPayload"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "error",
                  "message": "Too many requests for this account right now.",
                  "payload": {
                    "code": "rate_limited",
                    "retryable": true,
                    "billed": false,
                    "hint": "Wait for Retry-After seconds, lower your concurrency, or move to a plan with a higher limit.",
                    "doc_url": "https://quanticdata.io/docs/#unlock-errors",
                    "retry_after": 5
                  }
                }
              }
            }
          },
          "500": {
            "description": "`internal_error`: an error on our side. Retryable; not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/UnlockErrorPayload"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "error",
                  "message": "The unlocker hit an internal error.",
                  "payload": {
                    "code": "internal_error",
                    "retryable": true,
                    "billed": false,
                    "hint": "Retry; if it persists contact support with the request_id.",
                    "doc_url": "https://quanticdata.io/docs/#unlock-errors"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`service_unavailable`: the engine or the API is not answering. Retryable; nothing was started or billed.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/UnlockErrorPayload"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "error",
                  "message": "The unlocker service is not responding.",
                  "payload": {
                    "code": "service_unavailable",
                    "retryable": true,
                    "billed": false,
                    "hint": "Retry in a few seconds.",
                    "doc_url": "https://quanticdata.io/docs/#unlock-errors"
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/scraper/unlock/batch/ub_5e1c9a40d27f' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/scraper/unlock/batch/ub_5e1c9a40d27f',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/unlock/batch/ub_5e1c9a40d27f\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/unlock/batch/ub_5e1c9a40d27f');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      },
      "delete": {
        "operationId": "cancelUnlockBatch",
        "tags": [
          "Web Unlocker"
        ],
        "summary": "Cancel an unlock batch",
        "description": "Cancels the items of a batch you own that have not started. Items already running finish and are metered like any call; items never started move no bytes and cost nothing. The answer is the batch view without `results`; what was gathered so far stays readable with `GET /scraper/unlock/batch/{batch_id}`. Free.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "responses": {
          "200": {
            "description": "Cancelled: the counters of the batch, without `results`.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/UnlockBatchJob"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Batch cancelled",
                  "payload": {
                    "batch_id": "ub_5e1c9a40d27f",
                    "status": "cancelled",
                    "total": 3,
                    "completed": 1,
                    "ok": 1,
                    "blocked": 0,
                    "failed": 0,
                    "created_at": "2026-11-11T09:30:00.000Z",
                    "finished_at": "2026-11-11T09:30:05.000Z"
                  },
                  "pagination": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "The batch id is unknown, belongs to another account, or the batch ended more than one hour ago: one and the same answer, so an id cannot be probed. The payload has the shape of the Unlock errors catalogue, with `code: \"bad_request\"`.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/UnlockErrorPayload"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "error",
                  "message": "Batch not found. A batch is kept for one hour after it finishes.",
                  "payload": {
                    "code": "bad_request",
                    "retryable": false,
                    "billed": false,
                    "hint": "Fix the parameter named in the message and send the request again.",
                    "doc_url": "https://quanticdata.io/docs/#unlock-errors"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`rate_limited`: the requests per minute, the concurrent requests or the browser-render budget of the account's tier (see Rate limits and tiers). Back off for `Retry-After` seconds. Not billed.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/UnlockErrorPayload"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "error",
                  "message": "Too many requests for this account right now.",
                  "payload": {
                    "code": "rate_limited",
                    "retryable": true,
                    "billed": false,
                    "hint": "Wait for Retry-After seconds, lower your concurrency, or move to a plan with a higher limit.",
                    "doc_url": "https://quanticdata.io/docs/#unlock-errors",
                    "retry_after": 5
                  }
                }
              }
            }
          },
          "500": {
            "description": "`internal_error`: an error on our side. Retryable; not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/UnlockErrorPayload"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "error",
                  "message": "The unlocker hit an internal error.",
                  "payload": {
                    "code": "internal_error",
                    "retryable": true,
                    "billed": false,
                    "hint": "Retry; if it persists contact support with the request_id.",
                    "doc_url": "https://quanticdata.io/docs/#unlock-errors"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`service_unavailable`: the engine or the API is not answering. Retryable; nothing was started or billed.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/UnlockErrorPayload"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "error",
                  "message": "The unlocker service is not responding.",
                  "payload": {
                    "code": "service_unavailable",
                    "retryable": true,
                    "billed": false,
                    "hint": "Retry in a few seconds.",
                    "doc_url": "https://quanticdata.io/docs/#unlock-errors"
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X DELETE 'https://api.quanticdata.io/v1/scraper/unlock/batch/ub_5e1c9a40d27f' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.delete(\n    'https://api.quanticdata.io/v1/scraper/unlock/batch/ub_5e1c9a40d27f',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/unlock/batch/ub_5e1c9a40d27f\", {\n  method: \"DELETE\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/unlock/batch/ub_5e1c9a40d27f');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'DELETE',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/scraper/unlock/ca": {
      "get": {
        "operationId": "downloadUnlockerCa",
        "tags": [
          "Web Unlocker"
        ],
        "summary": "Download the unlocker CA certificate",
        "description": "The interception CA used by the Web Unlocker forward proxy (CONNECT mode). The proxy terminates your TLS to read and rewrite the request, so an HTTP client that keeps certificate verification on must trust this file for the target host: save it once as `unlocker-ca.pem` and pass it to the client (`curl --cacert unlocker-ca.pem …`, `verify=\"unlocker-ca.pem\"`), as in the proxy snippets at the top of this section. Not needed for POST /scraper/unlock, nor for the proxy's direct mode. Public by nature, kept behind the key so downloads are attributable. Free.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "responses": {
          "200": {
            "description": "PEM certificate (attachment `qp-unlocker-ca.pem`, cacheable 1h).",
            "content": {
              "application/x-pem-file": {
                "schema": {
                  "type": "string"
                },
                "example": "-----BEGIN CERTIFICATE-----\nMIIB…\n-----END CERTIFICATE-----\n"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "description": "The certificate could not be fetched from the unlocker service right now.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "Unlocker certificate is temporarily unavailable"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/scraper/unlock/ca' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/scraper/unlock/ca',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\nr.raise_for_status()\nopen(\"response.out\", \"wb\").write(r.content)",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/unlock/ca\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst bytes = Buffer.from(await res.arrayBuffer());\nrequire(\"node:fs\").writeFileSync(\"response.out\", bytes);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/unlock/ca');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\nfile_put_contents('response.out', $raw);",
            "x-id": "php"
          }
        ]
      }
    },
    "/public/unlock/offer": {
      "get": {
        "operationId": "getUnlockOffer",
        "tags": [
          "Web Unlocker"
        ],
        "summary": "Price per GB, packs and options on sale",
        "description": "What the Web Unlocker sells right now, without a key. `available` says whether it is on sale and its offer is published: while it is `false` the answer holds only `available` and `updated_at`, and the price is on the plans page of the dashboard. `price_per_gb` is the price of 1 GB on each tier, `null` for a tier that is not on sale. `packs_gb` lists the pack sizes and `validity_days` how long a pack lasts. Three switches follow: `pay_per_success`, `free_trial` and `captcha_solver`. The plans page of the dashboard and, when the offer is published, this endpoint are where the price is: these docs do not print it. The numbers in the example below are placeholders (`0`), not prices. The answer is the JSON object itself, without the `type` / `message` / `payload` envelope of the other endpoints. Cached for 5 minutes. Free.",
        "security": [],
        "x-envelope": false,
        "x-price-key": null,
        "x-rate-limit": "No key and no limit of its own; the answer is cached for 5 minutes.",
        "responses": {
          "200": {
            "description": "The current offer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnlockOffer"
                },
                "examples": {
                  "shape": {
                    "summary": "Shape of the answer: the two prices are placeholders, not live values",
                    "value": {
                      "available": true,
                      "currency": "USD",
                      "price_per_gb": {
                        "premium": 0,
                        "mobile": 0
                      },
                      "packs_gb": [
                        1,
                        5,
                        25,
                        100,
                        500
                      ],
                      "validity_days": 30,
                      "pay_per_success": false,
                      "free_trial": false,
                      "captcha_solver": false,
                      "updated_at": "2026-11-11T00:00:00.000Z"
                    }
                  }
                }
              }
            },
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string"
                },
                "description": "`public, max-age=300`."
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/public/unlock/offer'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/public/unlock/offer',\n    timeout=120,\n)\nr.raise_for_status()\nprint(r.json())",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/unlock/offer\", {\n  method: \"GET\"\n});\nif (!res.ok) throw new Error(`HTTP ${res.status}`);\nconsole.log(await res.json());",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/unlock/offer');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\nprint_r(json_decode($raw, true));",
            "x-id": "php"
          }
        ]
      }
    },
    "/public/unlock/status": {
      "get": {
        "operationId": "getUnlockStatus",
        "tags": [
          "Web Unlocker"
        ],
        "summary": "Health of the Web Unlocker from our canary",
        "description": "The health of the Web Unlocker as our own canary measures it: a scheduled run of real unlock calls against a fixed list of public test targets, grouped by anti-bot system. `state` is `operational` when the latest run is younger than 9 days and its success rate is at least 70 percent, `degraded` when it is younger and below, `unknown` when there is no run or it is older. `canary` is the latest run and `history` the last 12, newest first. Only canary traffic is published, never customer traffic. The answer is the JSON object itself, without the `type` / `message` / `payload` envelope of the other endpoints. The numbers in the example below are those of the canary of 4 November 2026, shown as an example: the endpoint returns the latest run. No key. Cached for 5 minutes. Free.",
        "security": [],
        "x-envelope": false,
        "x-price-key": null,
        "x-rate-limit": "No key and no limit of its own; the answer is cached for 5 minutes.",
        "responses": {
          "200": {
            "description": "The current state, the latest canary and the history.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnlockStatus"
                },
                "examples": {
                  "operational": {
                    "summary": "Example values: the canary of 11 November 2026, one of its per-system rows shown",
                    "value": {
                      "state": "operational",
                      "canary": {
                        "measuredAt": "2026-11-11",
                        "runs": 3,
                        "targets": 27,
                        "channel": "engine-local",
                        "provisional": false,
                        "note": "Captcha demo pages (hCaptcha, reCAPTCHA) are run but excluded: interactive captchas are not solved.",
                        "summary": {
                          "calls": 81,
                          "ok": 72,
                          "rate": 88.9,
                          "p50Ms": 4103,
                          "p95Ms": 28793
                        },
                        "vendors": {
                          "datadome": {
                            "label": "DataDome",
                            "calls": 9,
                            "ok": 8,
                            "rate": 88.9,
                            "p50Ms": 3557,
                            "p95Ms": 14903
                          }
                        }
                      },
                      "history": [
                        {
                          "measuredAt": "2026-11-11",
                          "calls": 81,
                          "ok": 72,
                          "rate": 88.9,
                          "p50Ms": 4103,
                          "p95Ms": 28793
                        },
                        {
                          "measuredAt": "2026-11-04",
                          "calls": 51,
                          "ok": 43,
                          "rate": 84.3,
                          "p50Ms": 7212,
                          "p95Ms": 35325
                        }
                      ],
                      "updated_at": "2026-11-11T00:00:00.000Z"
                    }
                  }
                }
              }
            },
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string"
                },
                "description": "`public, max-age=300`."
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/public/unlock/status'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/public/unlock/status',\n    timeout=120,\n)\nr.raise_for_status()\nprint(r.json())",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/unlock/status\", {\n  method: \"GET\"\n});\nif (!res.ok) throw new Error(`HTTP ${res.status}`);\nconsole.log(await res.json());",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/unlock/status');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\nprint_r(json_decode($raw, true));",
            "x-id": "php"
          }
        ]
      }
    },
    "/scraper/ai": {
      "post": {
        "operationId": "aiAgent",
        "tags": [
          "AI extraction"
        ],
        "summary": "Natural-language scraping agent",
        "description": "Describe a task in plain English; a model drives the scraper API as a tool — formats the request, fetches the page(s) through residential proxies, can search and map when the task needs it, and returns the extracted JSON under `data` with the pages it visited under `steps`. Use it when you do not want to write selectors or a schema; use /scraper/extract with `extract`/`ai_schema` when you already know the page. Not deterministic and not the cheapest path for repeated layouts (see /scraper/parser/generate). Billed as the `ai_extract` base fee plus one `extract` per page fetched, `serp` per search, `map` per map, plus LLM tokens × ai_token_markup, capped at the `ai_extract` meter's capUsd; the pre-check reserves that cap.",
        "x-price-key": "ai_extract",
        "x-price-keys": [
          "ai_extract",
          "extract",
          "serp",
          "map"
        ],
        "x-pricing-note": "ai_extract + steps × extract + searches × serp + mapped × map + tokens × ai_token_markup, capped at meters.ai_extract.capUsd.",
        "x-rate-limit": "per-tier",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "task"
                ],
                "properties": {
                  "task": {
                    "type": "string",
                    "description": "Plain-English instruction, e.g. \"get every product with its name and price from this page\"."
                  },
                  "url": {
                    "type": "string",
                    "description": "Starting URL, if the task does not already contain one."
                  }
                }
              },
              "example": {
                "task": "Get every plan and its monthly price",
                "url": "https://example.com/pricing"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Extraction finished.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/AiAgentResult"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "AI extraction successful",
                  "payload": {
                    "data": {
                      "plans": [
                        {
                          "name": "Starter",
                          "price_usd": 9
                        },
                        {
                          "name": "Growth",
                          "price_usd": 29
                        }
                      ]
                    },
                    "steps": [
                      {
                        "url": "https://example.com/pricing",
                        "status": 200,
                        "engine": "tls"
                      }
                    ],
                    "searches": 0,
                    "mapped": 0,
                    "model": "gpt-4o-mini",
                    "bytes": 48213,
                    "usage": {
                      "input_tokens": 3120,
                      "output_tokens": 180,
                      "cost_usd": 0.0019,
                      "free_usd": 0.0019,
                      "paid_usd": 0
                    }
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "description": "Missing task, or the agent reported a client-side problem (bad URL, page unusable).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "description": "Agent failure or the AI agent is not configured on this instance. Never billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/ServiceDisabled"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/scraper/ai' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"task\":\"Get every plan and its monthly price\",\"url\":\"https://example.com/pricing\"}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/scraper/ai',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\n        \"task\": \"Get every plan and its monthly price\",\n        \"url\": \"https://example.com/pricing\"\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/ai\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"task\": \"Get every plan and its monthly price\",\n    \"url\": \"https://example.com/pricing\"\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/ai');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'task' => 'Get every plan and its monthly price',\n    'url' => 'https://example.com/pricing'\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/scraper/places-ai": {
      "post": {
        "operationId": "aiPlacesFinder",
        "tags": [
          "AI extraction"
        ],
        "summary": "AI Places Finder",
        "description": "Describe what you are looking for (\"find every car repair shop in Naples\"); the model crafts the Google local queries, paginates, de-duplicates and returns the aggregated businesses, optionally enriched from each knowledge panel (phone, website, hours, full address). For a deterministic, per-row-priced alternative use the `google_maps_places` collector. Billed as the `places_ai` base plus `serp_render` per search run plus LLM tokens × ai_token_markup, capped at the `places_ai` meter's capUsd; the pre-check reserves that cap.",
        "x-price-key": "places_ai",
        "x-price-keys": [
          "places_ai",
          "serp_render"
        ],
        "x-pricing-note": "places_ai + searches × serp_render + tokens × ai_token_markup, capped at meters.places_ai.capUsd.",
        "x-rate-limit": "per-tier",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "task"
                ],
                "properties": {
                  "task": {
                    "type": "string"
                  },
                  "country": {
                    "type": "string",
                    "description": "ISO country override for the proxy exit and `gl`."
                  },
                  "enrich": {
                    "type": "boolean",
                    "default": true,
                    "description": "Fill phone/website/hours/address from each business's knowledge panel."
                  },
                  "max_enrich": {
                    "type": "number",
                    "default": 15,
                    "description": "Knowledge-panel lookups budget (cap 30)."
                  }
                }
              },
              "example": {
                "task": "find every car repair shop in Naples",
                "country": "it",
                "max_enrich": 10
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Places found.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/AiFinderResult"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Places search successful",
                  "payload": {
                    "places": [
                      {
                        "name": "Autofficina Esposito",
                        "rating": 4.6,
                        "reviews": 212,
                        "address": "Via Toledo 12, 80134 Napoli NA",
                        "phone": "+39 081 000 0000",
                        "website": "https://example.it"
                      }
                    ],
                    "total": 38,
                    "enriched": 10,
                    "queries": [
                      "autofficina Napoli",
                      "meccanico Napoli"
                    ],
                    "summary": "38 repair shops across central Naples.",
                    "model": "gpt-4o-mini",
                    "usage": {
                      "input_tokens": 9800,
                      "output_tokens": 2200,
                      "cost_usd": 0.0218,
                      "free_usd": 0.0218,
                      "paid_usd": 0
                    }
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "description": "Finder failure or not configured on this instance. Never billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/ServiceDisabled"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/scraper/places-ai' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"task\":\"find every car repair shop in Naples\",\"country\":\"it\",\"max_enrich\":10}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/scraper/places-ai',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\n        \"task\": \"find every car repair shop in Naples\",\n        \"country\": \"it\",\n        \"max_enrich\": 10\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/places-ai\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"task\": \"find every car repair shop in Naples\",\n    \"country\": \"it\",\n    \"max_enrich\": 10\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/places-ai');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'task' => 'find every car repair shop in Naples',\n    'country' => 'it',\n    'max_enrich' => 10\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/scraper/shopping-ai": {
      "post": {
        "operationId": "aiShoppingFinder",
        "tags": [
          "AI extraction"
        ],
        "summary": "AI Shopping Finder",
        "description": "Describe the product (\"find the cheapest Nintendo Switch OLED in Italy\"); the model crafts Google Shopping queries, paginates, de-duplicates and returns the aggregated products with merchant and price. For a deterministic alternative use /scraper/serp with `search_type: shopping` or the `google_shopping` collector. Billed as the `shopping_ai` base plus `serp_render` per search plus LLM tokens × ai_token_markup, capped at the `shopping_ai` meter's capUsd; the pre-check reserves that cap.",
        "x-price-key": "shopping_ai",
        "x-price-keys": [
          "shopping_ai",
          "serp_render"
        ],
        "x-pricing-note": "shopping_ai + searches × serp_render + tokens × ai_token_markup, capped at meters.shopping_ai.capUsd.",
        "x-rate-limit": "per-tier",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "task"
                ],
                "properties": {
                  "task": {
                    "type": "string"
                  },
                  "country": {
                    "type": "string",
                    "description": "ISO country override for the proxy exit, `gl` and currency."
                  }
                }
              },
              "example": {
                "task": "cheapest Nintendo Switch OLED",
                "country": "it"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Products found.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/AiFinderResult"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Shopping search successful",
                  "payload": {
                    "products": [
                      {
                        "title": "Nintendo Switch OLED Bianco",
                        "price": "€ 299,00",
                        "merchant": "Example Store",
                        "link": "https://example.it/p/switch-oled"
                      }
                    ],
                    "total": 24,
                    "queries": [
                      "Nintendo Switch OLED prezzo"
                    ],
                    "searches": [
                      {
                        "query": "Nintendo Switch OLED prezzo",
                        "results": 24
                      }
                    ],
                    "summary": "Lowest price €299 at Example Store.",
                    "model": "gpt-4o-mini",
                    "usage": {
                      "input_tokens": 7100,
                      "output_tokens": 900,
                      "cost_usd": 0.0121,
                      "free_usd": 0.0121,
                      "paid_usd": 0
                    }
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "description": "Finder failure or not configured on this instance. Never billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/ServiceDisabled"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/scraper/shopping-ai' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"task\":\"cheapest Nintendo Switch OLED\",\"country\":\"it\"}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/scraper/shopping-ai',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\n        \"task\": \"cheapest Nintendo Switch OLED\",\n        \"country\": \"it\"\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/shopping-ai\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"task\": \"cheapest Nintendo Switch OLED\",\n    \"country\": \"it\"\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/shopping-ai');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'task' => 'cheapest Nintendo Switch OLED',\n    'country' => 'it'\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/scraper/ai-visibility": {
      "post": {
        "operationId": "aiVisibilityAudit",
        "tags": [
          "AI visibility"
        ],
        "summary": "AI visibility audit",
        "description": "Answers one question about a page — can an AI assistant read it, and does it cite it? — on two levels. On-page (always): AI crawler access from the real robots.txt (24 bots), Content-Signal, a fetch that identifies itself as an AI crawler, noindex/nosnippet/noai directives, text without JavaScript, structured data and resolvable entities, citable form (questions, opening answer, lists/tables, numbers, chunk-sized sections), dated and authored content — scored per pillar with blockers that cap the total and the evidence behind every check. Citations (only when `queries` is given): the questions are really asked to Perplexity, ChatGPT, Claude, Google AI Overview, Bing Copilot and a DeepSeek-over-Google-SERP engine, and the answer reports who is cited or at least mentioned, plus share of voice against `competitors`. It does not change the page and the citation panel is capped at 10 queries per call and a daily per-account cap on LLM engine calls. Billed as the on-page audit fee plus one `ai_visibility_citation` per (query × engine) that actually answered, plus `serp` for the 2 retrievability SERPs and the 5 offsite SERPs when run.",
        "x-price-key": "ai_visibility",
        "x-price-keys": [
          "ai_visibility",
          "ai_visibility_citation",
          "serp"
        ],
        "x-pricing-note": "ai_visibility + answered (query × engine) × ai_visibility_citation + (2 retrieval + 5 offsite) × serp, only for SERPs that answered. Pre-check reserves the worst case.",
        "x-rate-limit": "per-tier",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "maxLength": 2048
                  },
                  "queries": {
                    "type": "array",
                    "maxItems": 10,
                    "items": {
                      "type": "string"
                    },
                    "description": "Questions to ask the engines. Absent = on-page audit only."
                  },
                  "engines": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "perplexity",
                        "openai",
                        "anthropic",
                        "aio",
                        "copilot",
                        "deepseek"
                      ]
                    },
                    "description": "Subset of engines for the citation panel; default all six. `deepseek` = our Google top-10 handed to DeepSeek (cheapest)."
                  },
                  "competitors": {
                    "type": "array",
                    "maxItems": 20,
                    "items": {
                      "type": "string"
                    },
                    "description": "Domains to name explicitly in the share of voice."
                  },
                  "brand": {
                    "type": "string",
                    "maxLength": 80,
                    "description": "Name to look for in answer text (\"mentioned\")."
                  },
                  "country": {
                    "$ref": "#/components/schemas/GeoValue"
                  },
                  "no_render": {
                    "type": "boolean",
                    "default": false,
                    "description": "Skip the rendered pass (cheaper). Alias `noRender`."
                  },
                  "no_bot_fetch": {
                    "type": "boolean",
                    "default": false,
                    "description": "Skip the extra request that identifies as an AI crawler. Alias `noBotFetch`."
                  },
                  "no_retrieval": {
                    "type": "boolean",
                    "default": false,
                    "description": "Skip the 2 retrievability SERPs (rank for the page's own H1 question, index status). Alias `noRetrieval`."
                  },
                  "offsite": {
                    "type": "boolean",
                    "default": false,
                    "description": "Also search the brand on YouTube, Reddit, Wikipedia, LinkedIn and review sites (5 SERPs)."
                  }
                }
              },
              "example": {
                "url": "https://example.com/blog/how-to-choose-a-proxy",
                "queries": [
                  "how do I choose a residential proxy provider?"
                ],
                "engines": [
                  "perplexity",
                  "aio"
                ],
                "brand": "Example"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Audit finished. `billing` says how many citation calls and SERPs were charged.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/AiVisibilityResult"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "AI visibility audit successful",
                  "payload": {
                    "url": "https://example.com/blog/how-to-choose-a-proxy",
                    "finalUrl": "https://example.com/blog/how-to-choose-a-proxy",
                    "domain": "example.com",
                    "score": {
                      "overall": 71,
                      "pillars": {
                        "access": 90,
                        "content": 68,
                        "structure": 60,
                        "citability": 66
                      },
                      "scoredPillars": [
                        "access",
                        "content",
                        "structure",
                        "citability"
                      ],
                      "blockers": [],
                      "uncapped": 71
                    },
                    "checks": [
                      {
                        "id": "robots_gptbot",
                        "pillar": "access",
                        "status": "pass",
                        "weight": 8,
                        "title": "GPTBot allowed",
                        "detail": "robots.txt does not disallow GPTBot.",
                        "evidence": {
                          "rule": null
                        }
                      }
                    ],
                    "topFixes": [
                      {
                        "id": "author_resolvable",
                        "status": "fail",
                        "title": "Author not resolvable",
                        "fix": "Add an author Person node with url or sameAs."
                      }
                    ],
                    "access": {
                      "robotsTxtFound": true,
                      "robotsTxtUrl": "https://example.com/robots.txt",
                      "blockedCritical": [],
                      "sitemaps": [
                        "https://example.com/sitemap.xml"
                      ],
                      "llmsTxt": false
                    },
                    "content": {
                      "contentOnlyInJs": false,
                      "fkGrade": 9.1
                    },
                    "structure": {
                      "jsonldTypes": [
                        "Article"
                      ],
                      "hasAuthor": true,
                      "authorResolvable": false
                    },
                    "citations": {
                      "rows": [
                        {
                          "query": "how do I choose a residential proxy provider?",
                          "engine": "perplexity",
                          "cited": false,
                          "mentioned": true,
                          "rank": null,
                          "citedDomains": [
                            "competitor.example"
                          ]
                        }
                      ],
                      "usage": {
                        "perplexity": {
                          "searches": 1
                        }
                      }
                    },
                    "geo": {
                      "country": null
                    },
                    "billing": {
                      "citation_calls_billed": 2,
                      "offsite_serps_billed": 2
                    },
                    "usage": {
                      "cost_usd": 0.023,
                      "free_usd": 0.023,
                      "paid_usd": 0
                    }
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "description": "Key/plan rate limit, or the account's daily cap on external AI-engine calls (payload: limit, remaining, reset_at, requested).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceDisabled"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/scraper/ai-visibility' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"url\":\"https://example.com/blog/how-to-choose-a-proxy\",\"queries\":[\"how do I choose a residential proxy provider?\"],\"engines\":[\"perplexity\",\"aio\"],\"brand\":\"Example\"}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/scraper/ai-visibility',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\n        \"url\": \"https://example.com/blog/how-to-choose-a-proxy\",\n        \"queries\": [\n            \"how do I choose a residential proxy provider?\"\n        ],\n        \"engines\": [\n            \"perplexity\",\n            \"aio\"\n        ],\n        \"brand\": \"Example\"\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/ai-visibility\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"url\": \"https://example.com/blog/how-to-choose-a-proxy\",\n    \"queries\": [\n      \"how do I choose a residential proxy provider?\"\n    ],\n    \"engines\": [\n      \"perplexity\",\n      \"aio\"\n    ],\n    \"brand\": \"Example\"\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/ai-visibility');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'url' => 'https://example.com/blog/how-to-choose-a-proxy',\n    'queries' => ['how do I choose a residential proxy provider?'],\n    'engines' => ['perplexity', 'aio'],\n    'brand' => 'Example'\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/scraper/seo-audit": {
      "post": {
        "operationId": "seoAudit",
        "tags": [
          "SEO audit"
        ],
        "summary": "No-JS vs rendered SEO audit",
        "description": "Fetches a URL twice — once as a pure HTTP bot (no JavaScript) and once fully rendered — and returns what search engines see in each view, the diff (title/description changes, H1 or content only after JS, missing canonical) and the bot-facing meta (robots, OpenGraph, JSON-LD types). It is a page-level technical check, not a site crawl or a keyword tool. The full audit takes one browser-render token; with `no_render` only the no-JS view is produced and the call bills the plain scrape price. If the render pass fails on our side you still get the no-JS view at the plain scrape price.",
        "x-aliases": [
          "/seo-audit"
        ],
        "x-price-key": "seo_audit",
        "x-price-keys": [
          "seo_audit",
          "extract"
        ],
        "x-pricing-note": "seo_audit when the render pass ran; extract when no_render is true or the render pass errored.",
        "x-rate-limit": "per-tier",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "maxLength": 2048
                  },
                  "country": {
                    "$ref": "#/components/schemas/GeoValue"
                  },
                  "no_render": {
                    "type": "boolean",
                    "default": false,
                    "description": "Skip the rendered pass. Alias `noRender`."
                  }
                }
              },
              "example": {
                "url": "https://example.com"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Audit finished.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/SeoAuditResult"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "SEO audit successful",
                  "payload": {
                    "url": "https://example.com",
                    "finalUrl": "https://example.com/",
                    "noJs": {
                      "status": 200,
                      "title": "Example Domain",
                      "description": null,
                      "canonical": null,
                      "h1": "Example Domain",
                      "wordCount": 28,
                      "hasContent": false
                    },
                    "render": {
                      "status": 200,
                      "title": "Example Domain",
                      "description": null,
                      "canonical": null,
                      "h1": "Example Domain",
                      "wordCount": 28,
                      "hasContent": false
                    },
                    "diff": {
                      "titleChanged": false,
                      "descriptionChanged": false,
                      "h1OnlyInRender": false,
                      "canonicalMissingNoJs": true,
                      "contentOnlyInJs": false
                    },
                    "meta": {
                      "robots": null,
                      "ogTitle": null,
                      "ogUrl": null,
                      "twitterCard": null,
                      "jsonldTypes": []
                    },
                    "durationMs": 4210,
                    "geo": {
                      "country": null
                    },
                    "usage": {
                      "cost_usd": 0.0012,
                      "free_usd": 0.0012,
                      "paid_usd": 0
                    }
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceDisabled"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/scraper/seo-audit' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"url\":\"https://example.com\"}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/scraper/seo-audit',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\n        \"url\": \"https://example.com\"\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/seo-audit\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"url\": \"https://example.com\"\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/seo-audit');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'url' => 'https://example.com'\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/scraper/collectors": {
      "get": {
        "operationId": "listCollectors",
        "tags": [
          "Collectors"
        ],
        "summary": "Collector catalog",
        "description": "Every ready-made collector with its identity and version, semantic `input_schema` (JSON Schema — what to POST to `run_url`), full `output_schema`, examples, hourly health probe and YOUR price per delivered result (list price × tier discount). The catalog is the source of truth: collectors are added and versioned without an API change, so read it rather than hard-coding slugs. Free.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "search",
                "seo",
                "social",
                "apps",
                "real_estate",
                "local",
                "jobs",
                "news",
                "ecommerce",
                "travel",
                "leads",
                "company",
                "classifieds",
                "finance",
                "dev",
                "knowledge",
                "gaming",
                "osint",
                "research"
              ]
            },
            "description": "Only collectors of this category."
          }
        ],
        "responses": {
          "200": {
            "description": "Catalog.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "collectors": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/CollectorCatalogEntry"
                              }
                            },
                            "billing": {
                              "type": "object",
                              "properties": {
                                "enabled": {
                                  "type": "boolean"
                                },
                                "discount_multiplier": {
                                  "type": "number"
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Collectors",
                  "payload": {
                    "collectors": [
                      {
                        "slug": "google_maps_places",
                        "name": "Google Maps places",
                        "version": "1.1.0",
                        "category": "local",
                        "category_label": "Local & Maps",
                        "tagline": "Businesses for a keyword in a location — name, rating, address, phone, website, coordinates.",
                        "description": "Searches Google's local results for a keyword in a location and delivers de-duplicated place records with contact and geo fields.",
                        "unit": "place",
                        "engines": [
                          "serp"
                        ],
                        "price": {
                          "list_usd": 0.001,
                          "your_usd": 0.001,
                          "price_key": "collector_google_maps_places",
                          "per_1k_usd": 1,
                          "min_billable_results": 0,
                          "min_run_usd": 0
                        },
                        "max_results": 300,
                        "input_schema": {
                          "type": "object",
                          "properties": {
                            "query": {
                              "type": "string",
                              "title": "Keyword",
                              "minLength": 2,
                              "maxLength": 120,
                              "examples": [
                                "pizza restaurants"
                              ]
                            },
                            "location": {
                              "type": "string",
                              "title": "Location",
                              "minLength": 2,
                              "maxLength": 120,
                              "examples": [
                                "Brooklyn, NY"
                              ]
                            },
                            "country": {
                              "type": "string",
                              "format": "country"
                            },
                            "lang": {
                              "type": "string",
                              "format": "lang"
                            },
                            "max_results": {
                              "type": "integer",
                              "default": 20,
                              "minimum": 1,
                              "maximum": 300
                            },
                            "enrich_details": {
                              "type": "boolean",
                              "default": true
                            }
                          },
                          "required": [
                            "query",
                            "location"
                          ],
                          "additionalProperties": false
                        },
                        "output_schema": {
                          "fields": [
                            {
                              "name": "rank",
                              "type": "integer",
                              "description": "1-based position across the merged pages."
                            },
                            {
                              "name": "name",
                              "type": "string",
                              "description": "Business name."
                            },
                            {
                              "name": "rating",
                              "type": "number",
                              "nullable": true,
                              "description": "Star rating (1–5)."
                            },
                            {
                              "name": "place_id",
                              "type": "string",
                              "nullable": true,
                              "description": "Google place id."
                            }
                          ]
                        },
                        "examples": [
                          {
                            "title": "Pizza in Brooklyn",
                            "input": {
                              "query": "pizza restaurants",
                              "location": "Brooklyn, NY",
                              "country": "us",
                              "max_results": 20
                            }
                          }
                        ],
                        "health_input": {
                          "query": "pizza",
                          "location": "Brooklyn, NY",
                          "country": "us",
                          "max_results": 10
                        },
                        "health": {
                          "status": "healthy",
                          "checked_at": "2026-10-07T08:00:12.000Z",
                          "latency_ms": 6210,
                          "result_count": 10,
                          "error": null,
                          "success_rate_24h": 1,
                          "last_ok_at": "2026-10-07T08:00:12.000Z"
                        },
                        "run_url": "/api/v1/scraper/collectors/google_maps_places/run"
                      }
                    ],
                    "billing": {
                      "enabled": true,
                      "discount_multiplier": 1
                    }
                  },
                  "pagination": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/ServiceDisabled"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/scraper/collectors' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/scraper/collectors',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/collectors\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/collectors');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/scraper/collectors/{slug}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/slug"
        }
      ],
      "get": {
        "operationId": "getCollector",
        "tags": [
          "Collectors"
        ],
        "summary": "One collector",
        "description": "The catalog entry of one collector plus its changelog and the last 24 health probes. Free.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "responses": {
          "200": {
            "description": "Collector.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "collector": {
                              "$ref": "#/components/schemas/CollectorCatalogEntry"
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Collector",
                  "payload": {
                    "collector": {
                      "slug": "google_maps_places",
                      "name": "Google Maps places",
                      "version": "1.1.0",
                      "category": "local",
                      "category_label": "Local & Maps",
                      "tagline": "Businesses for a keyword in a location.",
                      "description": "…",
                      "unit": "place",
                      "engines": [
                        "serp"
                      ],
                      "price": {
                        "list_usd": 0.001,
                        "your_usd": 0.001,
                        "price_key": "collector_google_maps_places",
                        "per_1k_usd": 1,
                        "min_billable_results": 0,
                        "min_run_usd": 0
                      },
                      "max_results": 300,
                      "input_schema": {
                        "type": "object",
                        "properties": {},
                        "required": [
                          "query",
                          "location"
                        ],
                        "additionalProperties": false
                      },
                      "output_schema": {
                        "fields": []
                      },
                      "examples": [],
                      "health_input": {},
                      "health": {
                        "status": "healthy",
                        "checked_at": "2026-10-07T08:00:12.000Z",
                        "latency_ms": 6210,
                        "result_count": 10,
                        "error": null,
                        "success_rate_24h": 1,
                        "last_ok_at": "2026-10-07T08:00:12.000Z"
                      },
                      "run_url": "/api/v1/scraper/collectors/google_maps_places/run",
                      "changelog": [
                        {
                          "version": "1.1.0",
                          "date": "2026-08-21",
                          "notes": "Paginates past offset 240."
                        }
                      ],
                      "health_history": [
                        {
                          "checked_at": "2026-10-07T08:00:12.000Z",
                          "ok": true,
                          "latency_ms": 6210,
                          "result_count": 10,
                          "error": null
                        }
                      ]
                    }
                  },
                  "pagination": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Unknown slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "Unknown collector \"foo\""
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/ServiceDisabled"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/scraper/collectors/google_maps_places' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/scraper/collectors/google_maps_places',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/collectors/google_maps_places\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/collectors/google_maps_places');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/scraper/collectors/{slug}/run": {
      "parameters": [
        {
          "$ref": "#/components/parameters/slug"
        }
      ],
      "post": {
        "operationId": "runCollector",
        "tags": [
          "Collectors"
        ],
        "summary": "Run a collector",
        "description": "The body is the collector's semantic input exactly as published in its `input_schema` (flat, or wrapped as `{\"input\": {...}}`), plus runner options: `async: true` forces background processing (also `mode: \"async\"` or `wait: false`). Short runs answer synchronously with the rows; long ones (the collector decides from the input size) answer 202 with a `statusUrl` to poll. Identical input re-sent inside the dedup window returns the existing run (`deduplicated: true`) — nothing new is created or charged. Per-account brakes (runs per hour, concurrent runs, failure streak) answer 429 with Retry-After. Billed per DELIVERED row at the collector's unit price × your tier discount (some collectors have a small per-run floor, see `price.min_billable_results`); zero rows = zero charge, failed runs are never billed. The worst case (unit × max_results) must be covered by free tier + balance or the run is refused with 402.",
        "x-price-key": "collector_result",
        "x-pricing-note": "Per delivered row: pricing.json key `collector_<slug>` when it exists, else `collector_result`. GET /scraper/collectors returns the resolved key and your discounted price for every collector.",
        "x-rate-limit": "per-tier",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "The collector's `input_schema` fields (validated against it: unknown keys are rejected, `max_results` is clamped to the collector's cap) plus the runner options below.",
                "properties": {
                  "async": {
                    "type": "boolean",
                    "default": false,
                    "description": "Force background processing (202 + statusUrl)."
                  },
                  "mode": {
                    "type": "string",
                    "enum": [
                      "async"
                    ],
                    "description": "Alias of `async: true`."
                  },
                  "wait": {
                    "type": "boolean",
                    "description": "`false` = alias of `async: true`."
                  },
                  "input": {
                    "type": "object",
                    "description": "Optional wrapper for the collector input."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "query": "pizza restaurants",
                "location": "Brooklyn, NY",
                "country": "us",
                "max_results": 20
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Synchronous run finished with rows.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/CollectorRun"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Collector run complete",
                  "payload": {
                    "run_id": "cmgfq2x1b0001",
                    "slug": "google_maps_places",
                    "version": "1.1.0",
                    "status": "done",
                    "input": {
                      "query": "pizza restaurants",
                      "location": "Brooklyn, NY",
                      "country": "us",
                      "max_results": 20
                    },
                    "count": 20,
                    "partial": false,
                    "cost": {
                      "usd": 0.02,
                      "unit_usd": 0.001,
                      "unit": "place",
                      "billed": true
                    },
                    "error": null,
                    "results": [
                      {
                        "rank": 1,
                        "name": "Joe's Pizza",
                        "rating": 4.5,
                        "reviews": 3120,
                        "category": "Pizza restaurant",
                        "address": "7 Carmine St, New York, NY 10014",
                        "phone": "+1 212-366-1182",
                        "website": "joespizzanyc.com",
                        "latitude": 40.7306,
                        "longitude": -74.0027,
                        "place_id": "ChIJ…",
                        "data_id": "0x89c259…:0x…",
                        "found_by": "pizza restaurants Brooklyn, NY"
                      }
                    ],
                    "notes": [],
                    "created_at": "2026-10-07T09:20:01.000Z",
                    "started_at": "2026-10-07T09:20:01.000Z",
                    "finished_at": "2026-10-07T09:20:14.000Z",
                    "usage": {
                      "cost_usd": 0.02,
                      "free_usd": 0.02,
                      "paid_usd": 0
                    }
                  },
                  "pagination": {}
                }
              }
            }
          },
          "202": {
            "description": "Run queued (or an identical run already in progress): poll `statusUrl`.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "run_id": {
                              "type": "string"
                            },
                            "status": {
                              "type": "string",
                              "enum": [
                                "queued",
                                "running"
                              ]
                            },
                            "statusUrl": {
                              "type": "string"
                            },
                            "deduplicated": {
                              "type": "boolean"
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Collector run queued",
                  "payload": {
                    "run_id": "cmgfq2x1b0001",
                    "status": "queued",
                    "statusUrl": "/api/v1/scraper/collectors/runs/cmgfq2x1b0001"
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "description": "Input does not match the collector's `input_schema` (`payload.errors`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "Invalid input: location is required",
                  "payload": {
                    "errors": [
                      "location is required"
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "404": {
            "description": "Unknown slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "422": {
            "description": "Input that can never resolve (documentation placeholder, undelegated TLD) — before or after the run; retrying the same input cannot help. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "Invalid input: example.com is a documentation placeholder",
                  "payload": {
                    "errors": [
                      "example.com is a documentation placeholder"
                    ],
                    "error_kind": "input"
                  }
                }
              }
            }
          },
          "424": {
            "description": "The run failed at the source (blocked, timed out, layout changed). JSON body with `run_id` and `error`; not billed, safe to retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "Collector run failed",
                  "payload": {
                    "run_id": "cmgfq2x1b0002",
                    "slug": "google_maps_places",
                    "version": "1.1.0",
                    "status": "failed",
                    "input": {},
                    "count": 0,
                    "partial": false,
                    "cost": {
                      "usd": 0,
                      "unit_usd": 0.001,
                      "unit": "place",
                      "billed": false
                    },
                    "error": "source timed out after 3 attempts",
                    "created_at": "2026-10-07T09:20:01.000Z",
                    "started_at": "2026-10-07T09:20:01.000Z",
                    "finished_at": "2026-10-07T09:21:01.000Z"
                  }
                }
              }
            }
          },
          "429": {
            "description": "Key/plan rate limit, or a per-account collector brake (`payload.code`: RUNS_PER_HOUR, CONCURRENT_RUNS, FAIL_STREAK, USER_PAUSED) with Retry-After.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "Too many collector runs this hour.",
                  "payload": {
                    "code": "RUNS_PER_HOUR",
                    "limit": 60,
                    "in_last_hour": 60,
                    "retry_after": 900,
                    "plan": "payg"
                  }
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/ServiceDisabled"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/scraper/collectors/google_maps_places/run' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"query\":\"pizza restaurants\",\"location\":\"Brooklyn, NY\",\"country\":\"us\",\"max_results\":20}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/scraper/collectors/google_maps_places/run',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\n        \"query\": \"pizza restaurants\",\n        \"location\": \"Brooklyn, NY\",\n        \"country\": \"us\",\n        \"max_results\": 20\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/collectors/google_maps_places/run\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"query\": \"pizza restaurants\",\n    \"location\": \"Brooklyn, NY\",\n    \"country\": \"us\",\n    \"max_results\": 20\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/collectors/google_maps_places/run');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'query' => 'pizza restaurants',\n    'location' => 'Brooklyn, NY',\n    'country' => 'us',\n    'max_results' => 20\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/scraper/collectors/runs": {
      "get": {
        "operationId": "listCollectorRuns",
        "tags": [
          "Collectors"
        ],
        "summary": "Your collector runs",
        "description": "Newest first, without result rows. Page with `next_cursor`. Free.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "`next_cursor` from the previous page."
          },
          {
            "name": "slug",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Only runs of this collector."
          }
        ],
        "responses": {
          "200": {
            "description": "Runs.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "runs": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/CollectorRun"
                              }
                            },
                            "next_cursor": {
                              "type": [
                                "string",
                                "null"
                              ]
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Collector runs",
                  "payload": {
                    "runs": [
                      {
                        "run_id": "cmgfq2x1b0001",
                        "slug": "google_maps_places",
                        "version": "1.1.0",
                        "status": "done",
                        "input": {
                          "query": "pizza restaurants",
                          "location": "Brooklyn, NY"
                        },
                        "count": 20,
                        "partial": false,
                        "cost": {
                          "usd": 0.02,
                          "unit_usd": 0.001,
                          "unit": "place",
                          "billed": true
                        },
                        "error": null,
                        "created_at": "2026-10-07T09:20:01.000Z",
                        "started_at": "2026-10-07T09:20:01.000Z",
                        "finished_at": "2026-10-07T09:20:14.000Z"
                      }
                    ],
                    "next_cursor": null
                  },
                  "pagination": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/ServiceDisabled"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/scraper/collectors/runs' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/scraper/collectors/runs',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/collectors/runs\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/collectors/runs');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/scraper/collectors/runs/{runId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/runId"
        }
      ],
      "get": {
        "operationId": "getCollectorRun",
        "tags": [
          "Collectors"
        ],
        "summary": "One run with its rows",
        "description": "The run you own with its delivered results. `format=csv` streams the rows as CSV (columns follow the collector's `output_schema`). Free.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "parameters": [
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "csv"
              ]
            },
            "description": "`csv` returns a file instead of the JSON envelope."
          }
        ],
        "responses": {
          "200": {
            "description": "Run view (JSON) or CSV file.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/CollectorRun"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Collector run",
                  "payload": {
                    "run_id": "cmgfq2x1b0001",
                    "slug": "google_maps_places",
                    "version": "1.1.0",
                    "status": "done",
                    "input": {
                      "query": "pizza restaurants",
                      "location": "Brooklyn, NY",
                      "country": "us",
                      "max_results": 20
                    },
                    "count": 20,
                    "partial": false,
                    "cost": {
                      "usd": 0.02,
                      "unit_usd": 0.001,
                      "unit": "place",
                      "billed": true
                    },
                    "error": null,
                    "results": [
                      {
                        "rank": 1,
                        "name": "Joe's Pizza"
                      }
                    ],
                    "created_at": "2026-10-07T09:20:01.000Z",
                    "started_at": "2026-10-07T09:20:01.000Z",
                    "finished_at": "2026-10-07T09:20:14.000Z",
                    "usage": {
                      "cost_usd": 0.02,
                      "free_usd": 0.02,
                      "paid_usd": 0
                    }
                  },
                  "pagination": {}
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string"
                },
                "example": "rank,name,rating,reviews,category,address,phone,website\n1,Joe's Pizza,4.5,3120,Pizza restaurant,\"7 Carmine St, New York, NY 10014\",+1 212-366-1182,joespizzanyc.com\n"
              }
            }
          },
          "400": {
            "description": "Malformed run id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/ServiceDisabled"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/scraper/collectors/runs/cmgfq2x1b0001' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/scraper/collectors/runs/cmgfq2x1b0001',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/collectors/runs/cmgfq2x1b0001\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/collectors/runs/cmgfq2x1b0001');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/scraper/datasets": {
      "get": {
        "operationId": "listDatasets",
        "tags": [
          "Datasets"
        ],
        "summary": "Your recent dataset runs",
        "description": "The last 20 runs, newest first, with status reconciled against the live job for runs still marked running, the settled cost, and whether the rows are still stored. Free.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "responses": {
          "200": {
            "description": "Datasets.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "datasets": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/DatasetSummary"
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Datasets",
                  "payload": {
                    "datasets": [
                      {
                        "id": "cmgf0",
                        "jobId": "ds_7a1c22",
                        "name": null,
                        "prompt": "Car rental companies in Bologna with phone and website",
                        "columns": "[{\"name\":\"company\",\"type\":\"string\"},{\"name\":\"phone\",\"type\":\"phone\"},{\"name\":\"website\",\"type\":\"url\"}]",
                        "country": "it",
                        "status": "completed",
                        "rowCount": 42,
                        "billableRows": 40,
                        "refresh": false,
                        "createdAt": "2026-10-06T14:02:11.000Z",
                        "completedAt": "2026-10-06T14:09:40.000Z",
                        "purgedAt": null,
                        "costUsd": 1.86,
                        "stored": true,
                        "storedRows": 42,
                        "storedBytes": 18311,
                        "purged": false,
                        "dropped": null
                      }
                    ]
                  },
                  "pagination": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/ServiceDisabled"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/scraper/datasets' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/scraper/datasets',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/datasets\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/datasets');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      },
      "post": {
        "operationId": "createDataset",
        "tags": [
          "Datasets"
        ],
        "summary": "Build a dataset from a prompt",
        "description": "One plain-language prompt → a structured dataset. The service plans queries, searches, maps and scrapes, extracts the requested columns and returns validated rows; `refresh: true` re-reads a known URL set (`refreshUrls`) without discovery at a reduced row fee. Returns a job id immediately; poll `GET /scraper/datasets/{jobId}`, download the file, or pass a `webhook` (public host only, delivered after settlement with the hygiene filters applied). Billing is value-based: the run's budget `limits.max_cost_usd` (default $5, max $500, min $0.05) is charged up front and the unspent share is refunded at settlement, so you pay only for delivered, validated records (`dataset_row`, or `dataset_row_refresh` on a refresh) plus premium columns found (email, phone, deep) plus the pipeline units consumed. Low-confidence rows, off-target pages and blocked pages are never billed.",
        "x-price-key": "dataset_row",
        "x-price-keys": [
          "dataset_row",
          "dataset_row_refresh"
        ],
        "x-pricing-note": "max_cost_usd charged up front, refunded down to actual spend. Actual spend = delivered validated rows × dataset_row (dataset_row_refresh on refresh) + premium field fees + metered pipeline units (serp/map/extract/AI).",
        "x-rate-limit": "per-tier",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "prompt"
                ],
                "properties": {
                  "prompt": {
                    "type": "string",
                    "maxLength": 2000,
                    "description": "What the dataset is."
                  },
                  "columns": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": [
                        "name"
                      ],
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "type": {
                          "type": "string",
                          "enum": [
                            "string",
                            "number",
                            "email",
                            "phone",
                            "url",
                            "boolean",
                            "deep"
                          ],
                          "description": "`email`, `phone` and `deep` are premium (billed only when found)."
                        },
                        "description": {
                          "type": "string"
                        }
                      }
                    },
                    "description": "Omit to let the planner infer columns from the prompt."
                  },
                  "country": {
                    "$ref": "#/components/schemas/GeoValue"
                  },
                  "sources": {
                    "type": "object",
                    "properties": {
                      "include": {
                        "type": "array",
                        "maxItems": 50,
                        "items": {
                          "type": "string"
                        }
                      },
                      "exclude": {
                        "type": "array",
                        "maxItems": 50,
                        "items": {
                          "type": "string"
                        }
                      }
                    },
                    "description": "Domain allow/deny lists."
                  },
                  "limits": {
                    "type": "object",
                    "properties": {
                      "max_rows": {
                        "type": "integer"
                      },
                      "max_pages": {
                        "type": "integer"
                      },
                      "max_cost_usd": {
                        "type": "number",
                        "minimum": 0.05,
                        "maximum": 500,
                        "default": 5
                      }
                    }
                  },
                  "webhook": {
                    "type": "string",
                    "maxLength": 2048,
                    "description": "Public http(s) URL that receives the finished, filtered dataset by POST."
                  },
                  "refresh": {
                    "type": "boolean",
                    "default": false
                  },
                  "refreshUrls": {
                    "type": "array",
                    "maxItems": 1000,
                    "items": {
                      "type": "string",
                      "maxLength": 2048
                    },
                    "description": "Required with `refresh: true`."
                  }
                }
              },
              "example": {
                "prompt": "Car rental companies in Bologna with phone and website",
                "columns": [
                  {
                    "name": "company",
                    "type": "string"
                  },
                  {
                    "name": "phone",
                    "type": "phone"
                  },
                  {
                    "name": "website",
                    "type": "url"
                  }
                ],
                "country": "it",
                "limits": {
                  "max_rows": 50,
                  "max_cost_usd": 3
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Dataset job started.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/JobStarted"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Dataset started",
                  "payload": {
                    "id": "ds_7a1c22",
                    "status": "running",
                    "prompt": "Car rental companies in Bologna with phone and website",
                    "columns": [
                      {
                        "name": "company",
                        "type": "string"
                      },
                      {
                        "name": "phone",
                        "type": "phone"
                      },
                      {
                        "name": "website",
                        "type": "url"
                      }
                    ],
                    "limits": {
                      "max_rows": 50,
                      "max_pages": 200,
                      "max_cost_usd": 3
                    },
                    "statusUrl": "/api/v1/scraper/datasets/ds_7a1c22",
                    "usage": {
                      "cost_usd": 3,
                      "free_usd": 2,
                      "paid_usd": 1,
                      "balance": 9
                    }
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "503": {
            "description": "The Data API group is off for your key, or the dataset builder is not enabled on this instance (configuration, not a transient error).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/scraper/datasets' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"prompt\":\"Car rental companies in Bologna with phone and website\",\"columns\":[{\"name\":\"company\",\"type\":\"string\"},{\"name\":\"phone\",\"type\":\"phone\"},{\"name\":\"website\",\"type\":\"url\"}],\"country\":\"it\",\"limits\":{\"max_rows\":50,\"max_cost_usd\":3}}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/scraper/datasets',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\n        \"prompt\": \"Car rental companies in Bologna with phone and website\",\n        \"columns\": [\n            {\n                \"name\": \"company\",\n                \"type\": \"string\"\n            },\n            {\n                \"name\": \"phone\",\n                \"type\": \"phone\"\n            },\n            {\n                \"name\": \"website\",\n                \"type\": \"url\"\n            }\n        ],\n        \"country\": \"it\",\n        \"limits\": {\n            \"max_rows\": 50,\n            \"max_cost_usd\": 3\n        }\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/datasets\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"prompt\": \"Car rental companies in Bologna with phone and website\",\n    \"columns\": [\n      {\n        \"name\": \"company\",\n        \"type\": \"string\"\n      },\n      {\n        \"name\": \"phone\",\n        \"type\": \"phone\"\n      },\n      {\n        \"name\": \"website\",\n        \"type\": \"url\"\n      }\n    ],\n    \"country\": \"it\",\n    \"limits\": {\n      \"max_rows\": 50,\n      \"max_cost_usd\": 3\n    }\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/datasets');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'prompt' => 'Car rental companies in Bologna with phone and website',\n    'columns' => [[\n      'name' => 'company',\n      'type' => 'string'\n    ], [\n      'name' => 'phone',\n      'type' => 'phone'\n    ], [\n      'name' => 'website',\n      'type' => 'url'\n    ]],\n    'country' => 'it',\n    'limits' => [\n      'max_rows' => 50,\n      'max_cost_usd' => 3\n    ]\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/scraper/datasets/{jobId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/jobId"
        }
      ],
      "get": {
        "operationId": "getDataset",
        "tags": [
          "Datasets"
        ],
        "summary": "Poll a dataset job",
        "description": "Progress, the collection trace (`steps`) and the rows so far, filtered for you (removal list, your exclusion list, rows already delivered to you). A run the service has already forgotten (about an hour after it finishes) is served from storage (`source: storage`, no progress/steps). Free.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "parameters": [
          {
            "name": "since",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Row cursor from the previous poll's `nextCursor`."
          },
          {
            "name": "mode",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "summary"
              ]
            },
            "description": "`summary` omits rows."
          }
        ],
        "responses": {
          "200": {
            "description": "Job view.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/DatasetJob"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Dataset status",
                  "payload": {
                    "id": "ds_7a1c22",
                    "status": "completed",
                    "prompt": "Car rental companies in Bologna with phone and website",
                    "columns": [
                      {
                        "name": "company",
                        "type": "string"
                      },
                      {
                        "name": "phone",
                        "type": "phone"
                      },
                      {
                        "name": "website",
                        "type": "url"
                      }
                    ],
                    "files": null,
                    "progress": {
                      "queries_run": 6,
                      "sites_mapped": 12,
                      "pages_scraped": 58,
                      "pages_failed": 3,
                      "rows": 42,
                      "dropped_offtarget": 4,
                      "cost_so_far_usd": 1.86
                    },
                    "limits": {
                      "max_rows": 50,
                      "max_pages": 200,
                      "max_cost_usd": 3
                    },
                    "entity": "car rental company",
                    "billable": {
                      "row_fees_usd": 1.62,
                      "unit_usd": 0.24
                    },
                    "steps": [
                      {
                        "phase": "plan",
                        "detail": "entity: car rental company; 6 queries",
                        "ts": 1759759331000
                      }
                    ],
                    "rows": [
                      {
                        "fields": {
                          "company": "Bologna Rent",
                          "phone": "+39 051 000000",
                          "website": "https://example.it"
                        },
                        "_source_url": "https://example.it/contatti",
                        "_fetched_at": "2026-10-06T14:05:10.000Z",
                        "confidence": 0.93,
                        "billed_fields": [
                          "phone"
                        ],
                        "fee_usd": 0.05
                      }
                    ],
                    "row_count": 42,
                    "billable_rows": 40,
                    "nextCursor": 42,
                    "createdAt": 1759759331000,
                    "finishedAt": 1759759780000
                  },
                  "pagination": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceDisabled"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/scraper/datasets/job_8f2c1a' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/scraper/datasets/job_8f2c1a',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/datasets/job_8f2c1a\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/datasets/job_8f2c1a');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      },
      "delete": {
        "operationId": "cancelDataset",
        "tags": [
          "Datasets"
        ],
        "summary": "Cancel a dataset job",
        "description": "Stops a running job you own; the unspent budget is refunded at settlement. To delete the stored record of a finished run use `DELETE /scraper/datasets/{jobId}/record`.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "responses": {
          "200": {
            "description": "Cancelled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                },
                "example": {
                  "type": "response",
                  "message": "Dataset cancelled",
                  "payload": {
                    "id": "ds_7a1c22",
                    "status": "cancelled"
                  },
                  "pagination": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceDisabled"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X DELETE 'https://api.quanticdata.io/v1/scraper/datasets/job_8f2c1a' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.delete(\n    'https://api.quanticdata.io/v1/scraper/datasets/job_8f2c1a',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/datasets/job_8f2c1a\", {\n  method: \"DELETE\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/datasets/job_8f2c1a');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'DELETE',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/scraper/datasets/{jobId}/download": {
      "parameters": [
        {
          "$ref": "#/components/parameters/jobId"
        }
      ],
      "get": {
        "operationId": "downloadDataset",
        "tags": [
          "Datasets"
        ],
        "summary": "Download a dataset file",
        "description": "The run's rows as CSV or JSON, partial runs included (rows collected before an interruption are delivered too). Always built from rows that passed the list-hygiene filter. 404 while the run is still going or when it produced no rows. Free.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "parameters": [
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "csv",
                "json"
              ],
              "default": "csv"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "File attachment `dataset-{jobId}.csv|json`.",
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                },
                "example": "company,phone,website,_source_url\nBologna Rent,+39 051 000000,https://example.it,https://example.it/contatti\n"
              },
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "columns": {
                      "type": "array"
                    },
                    "rows": {
                      "type": "array"
                    },
                    "rowCount": {
                      "type": "integer"
                    }
                  }
                },
                "example": {
                  "columns": [
                    {
                      "name": "company",
                      "type": "string"
                    }
                  ],
                  "rows": [
                    {
                      "company": "Bologna Rent",
                      "_source_url": "https://example.it/contatti"
                    }
                  ],
                  "rowCount": 1
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Unknown job, not yours, or file not ready (run not finished or no rows).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "File not ready — the run has not finished or produced no rows"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceDisabled"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/scraper/datasets/job_8f2c1a/download' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/scraper/datasets/job_8f2c1a/download',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\nr.raise_for_status()\nopen(\"response.out\", \"wb\").write(r.content)",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/datasets/job_8f2c1a/download\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst bytes = Buffer.from(await res.arrayBuffer());\nrequire(\"node:fs\").writeFileSync(\"response.out\", bytes);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/datasets/job_8f2c1a/download');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\nfile_put_contents('response.out', $raw);",
            "x-id": "php"
          }
        ]
      }
    },
    "/scraper/datasets/{jobId}/record": {
      "parameters": [
        {
          "$ref": "#/components/parameters/jobId"
        }
      ],
      "patch": {
        "operationId": "renameDataset",
        "tags": [
          "Datasets"
        ],
        "summary": "Rename a dataset run",
        "description": "Sets the run's label (max 120 characters); an empty string or null clears it and the prompt becomes the label again. The prompt itself is never rewritten. Free.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 120
                  }
                }
              },
              "example": {
                "name": "Bologna car rentals — October"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Renamed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                },
                "example": {
                  "type": "response",
                  "message": "Dataset renamed",
                  "payload": {
                    "jobId": "ds_7a1c22",
                    "name": "Bologna car rentals — October",
                    "prompt": "Car rental companies in Bologna with phone and website"
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/ServiceDisabled"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X PATCH 'https://api.quanticdata.io/v1/scraper/datasets/job_8f2c1a/record' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"name\":\"Bologna car rentals — October\"}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.patch(\n    'https://api.quanticdata.io/v1/scraper/datasets/job_8f2c1a/record',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\n        \"name\": \"Bologna car rentals — October\"\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/datasets/job_8f2c1a/record\", {\n  method: \"PATCH\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"name\": \"Bologna car rentals — October\"\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/datasets/job_8f2c1a/record');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'PATCH',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'name' => 'Bologna car rentals — October'\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      },
      "delete": {
        "operationId": "deleteDatasetRecord",
        "tags": [
          "Datasets"
        ],
        "summary": "Delete a dataset run's stored record",
        "description": "Permanently removes the record and its stored rows. A run still in flight must be cancelled first (400). Irreversible. Free.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "responses": {
          "200": {
            "description": "Deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                },
                "example": {
                  "type": "response",
                  "message": "Dataset deleted",
                  "payload": {
                    "jobId": "ds_7a1c22"
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "description": "The run is still running — cancel it first.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "Cancel the run before deleting it."
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/ServiceDisabled"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X DELETE 'https://api.quanticdata.io/v1/scraper/datasets/job_8f2c1a/record' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.delete(\n    'https://api.quanticdata.io/v1/scraper/datasets/job_8f2c1a/record',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/datasets/job_8f2c1a/record\", {\n  method: \"DELETE\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/datasets/job_8f2c1a/record');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'DELETE',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/scraper/parser/generate": {
      "post": {
        "operationId": "generateParser",
        "tags": [
          "Parser presets"
        ],
        "summary": "Generate CSS selectors with an LLM, once",
        "description": "Looks at a page once with a model and returns CSS selectors (`parser`) that extract the fields you asked for — ready to pass as `extract` on every later scrape of that layout, where no model is involved and the plain scrape price applies. Every selector is run against the page before it is returned: `report`, `missed` and `coverage` tell you which fields are reliable. Give `url` (fetched through the pool, `render: true` for SPA pages) or `html` you already have (max 3 MB, no proxy bandwidth). Charged once as a setup step, and only when the parser extracts something (`coverage` > 0).",
        "x-price-key": "parser_generate",
        "x-pricing-note": "parser_generate, only when coverage > 0.",
        "x-rate-limit": "per-tier",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "maxLength": 2048,
                    "description": "Required unless `html` is given."
                  },
                  "html": {
                    "type": "string"
                  },
                  "fields": {
                    "type": "object",
                    "maxProperties": 25,
                    "additionalProperties": {
                      "type": "string",
                      "maxLength": 300
                    },
                    "description": "field name → what it is. Required unless `prompt` is given."
                  },
                  "prompt": {
                    "type": "string",
                    "maxLength": 2000,
                    "description": "Free-text alternative to `fields` (the model names them)."
                  },
                  "render": {
                    "type": "boolean",
                    "default": false
                  },
                  "country": {
                    "$ref": "#/components/schemas/GeoValue"
                  }
                }
              },
              "example": {
                "url": "https://example.com/products/42",
                "fields": {
                  "title": "product name",
                  "price": "current price with currency",
                  "sku": "SKU code"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Parser generated (message says when no usable selector could be produced; then not charged).",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/GenerateParserResult"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Parser generated",
                  "payload": {
                    "parser": {
                      "title": "h1.product-title",
                      "price": {
                        "selector": "span.price",
                        "attr": null
                      },
                      "sku": "dd.sku"
                    },
                    "report": [
                      {
                        "field": "title",
                        "selector": "h1.product-title",
                        "sample": "Trail Runner 2",
                        "missed": false
                      },
                      {
                        "field": "price",
                        "selector": "span.price",
                        "sample": "€ 129,00",
                        "missed": false
                      },
                      {
                        "field": "sku",
                        "selector": "dd.sku",
                        "sample": "TR2-42",
                        "missed": false
                      }
                    ],
                    "missed": [],
                    "coverage": 1,
                    "repaired": false,
                    "usage": {
                      "cost_usd": 0.02,
                      "free_usd": 0.02,
                      "paid_usd": 0
                    }
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "503": {
            "description": "Data API off for your key, or the generator's model is not configured.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/scraper/parser/generate' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"url\":\"https://example.com/products/42\",\"fields\":{\"title\":\"product name\",\"price\":\"current price with currency\",\"sku\":\"SKU code\"}}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/scraper/parser/generate',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\n        \"url\": \"https://example.com/products/42\",\n        \"fields\": {\n            \"title\": \"product name\",\n            \"price\": \"current price with currency\",\n            \"sku\": \"SKU code\"\n        }\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/parser/generate\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"url\": \"https://example.com/products/42\",\n    \"fields\": {\n      \"title\": \"product name\",\n      \"price\": \"current price with currency\",\n      \"sku\": \"SKU code\"\n    }\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/parser/generate');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'url' => 'https://example.com/products/42',\n    'fields' => [\n      'title' => 'product name',\n      'price' => 'current price with currency',\n      'sku' => 'SKU code'\n    ]\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/scraper/parser/presets": {
      "get": {
        "operationId": "listParserPresets",
        "tags": [
          "Parser presets"
        ],
        "summary": "List your presets",
        "description": "Every stored parser of your account with its stats and version history. Free.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "responses": {
          "200": {
            "description": "Presets.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "presets": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/ParserPreset"
                              }
                            }
                          },
                          "additionalProperties": true
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Presets",
                  "payload": {
                    "presets": [
                      {
                        "id": "pst_7Qk3",
                        "name": "example-product",
                        "sourceUrl": "https://example.com/products/42",
                        "fields": {
                          "title": "product name",
                          "price": "current price"
                        },
                        "render": false,
                        "parser": {
                          "title": "h1.product-title",
                          "price": "span.price"
                        },
                        "version": 1,
                        "autoHeal": true,
                        "createdAt": 1759759331000,
                        "updatedAt": 1759759331000,
                        "lastHealAt": null,
                        "stats": {
                          "runs": 12,
                          "lastRunAt": 1759830000000,
                          "fields": {
                            "title": {
                              "hits": 12,
                              "misses": 0
                            },
                            "price": {
                              "hits": 11,
                              "misses": 1
                            }
                          },
                          "recent": [
                            1,
                            1,
                            0.5,
                            1
                          ]
                        },
                        "history": [
                          {
                            "version": 1,
                            "parser": {
                              "title": "h1.product-title",
                              "price": "span.price"
                            },
                            "at": 1759759331000,
                            "reason": "created",
                            "coverage": 1
                          }
                        ]
                      }
                    ]
                  },
                  "pagination": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceDisabled"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/scraper/parser/presets' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/scraper/parser/presets',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/parser/presets\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/parser/presets');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      },
      "post": {
        "operationId": "createParserPreset",
        "tags": [
          "Parser presets"
        ],
        "summary": "Save a parser as a preset",
        "description": "Stores a parser (usually the one /scraper/parser/generate just returned) under a name. Scrape with `presetId` instead of an inline `extract` schema and every run is scored per field; when the recent success rate decays and `autoHeal` is on, the preset regenerates itself from `sourceUrl` and bumps its version. Ownership is server-side: a client-supplied tenant is ignored. Free to store.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "parser"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "maxLength": 120
                  },
                  "parser": {
                    "$ref": "#/components/schemas/ExtractSchema",
                    "description": "Non-empty, at most 25 fields."
                  },
                  "sourceUrl": {
                    "type": "string",
                    "maxLength": 2048,
                    "description": "Page the parser was learned from — self-healing refetches it."
                  },
                  "fields": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    },
                    "description": "field → description, so a heal can regenerate the same shape."
                  },
                  "render": {
                    "type": "boolean",
                    "default": false
                  },
                  "autoHeal": {
                    "type": "boolean"
                  }
                }
              },
              "example": {
                "name": "example-product",
                "parser": {
                  "title": "h1.product-title",
                  "price": "span.price"
                },
                "sourceUrl": "https://example.com/products/42",
                "fields": {
                  "title": "product name",
                  "price": "current price"
                },
                "autoHeal": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/ParserPreset"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Preset created",
                  "payload": {
                    "id": "pst_7Qk3",
                    "name": "example-product",
                    "sourceUrl": "https://example.com/products/42",
                    "fields": {
                      "title": "product name",
                      "price": "current price"
                    },
                    "render": false,
                    "parser": {
                      "title": "h1.product-title",
                      "price": "span.price"
                    },
                    "version": 1,
                    "autoHeal": true,
                    "createdAt": 1759759331000,
                    "updatedAt": 1759759331000,
                    "lastHealAt": null,
                    "stats": {
                      "runs": 0,
                      "lastRunAt": null,
                      "fields": {},
                      "recent": []
                    },
                    "history": [
                      {
                        "version": 1,
                        "parser": {
                          "title": "h1.product-title",
                          "price": "span.price"
                        },
                        "at": 1759759331000,
                        "reason": "created"
                      }
                    ]
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceDisabled"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/scraper/parser/presets' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"name\":\"example-product\",\"parser\":{\"title\":\"h1.product-title\",\"price\":\"span.price\"},\"sourceUrl\":\"https://example.com/products/42\",\"fields\":{\"title\":\"product name\",\"price\":\"current price\"},\"autoHeal\":true}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/scraper/parser/presets',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\n        \"name\": \"example-product\",\n        \"parser\": {\n            \"title\": \"h1.product-title\",\n            \"price\": \"span.price\"\n        },\n        \"sourceUrl\": \"https://example.com/products/42\",\n        \"fields\": {\n            \"title\": \"product name\",\n            \"price\": \"current price\"\n        },\n        \"autoHeal\": true\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/parser/presets\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"name\": \"example-product\",\n    \"parser\": {\n      \"title\": \"h1.product-title\",\n      \"price\": \"span.price\"\n    },\n    \"sourceUrl\": \"https://example.com/products/42\",\n    \"fields\": {\n      \"title\": \"product name\",\n      \"price\": \"current price\"\n    },\n    \"autoHeal\": true\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/parser/presets');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'name' => 'example-product',\n    'parser' => [\n      'title' => 'h1.product-title',\n      'price' => 'span.price'\n    ],\n    'sourceUrl' => 'https://example.com/products/42',\n    'fields' => [\n      'title' => 'product name',\n      'price' => 'current price'\n    ],\n    'autoHeal' => true\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/scraper/parser/presets/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/presetId"
        }
      ],
      "get": {
        "operationId": "getParserPreset",
        "tags": [
          "Parser presets"
        ],
        "summary": "Read a preset",
        "description": "Parser, stats and version history. A preset belonging to someone else answers 404. Free.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "responses": {
          "200": {
            "description": "Preset.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/ParserPreset"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Preset",
                  "payload": {
                    "id": "pst_7Qk3",
                    "name": "example-product",
                    "parser": {
                      "title": "h1.product-title",
                      "price": "span.price"
                    },
                    "version": 1,
                    "autoHeal": true,
                    "createdAt": 1759759331000,
                    "updatedAt": 1759759331000,
                    "lastHealAt": null,
                    "stats": {
                      "runs": 12,
                      "lastRunAt": 1759830000000,
                      "fields": {},
                      "recent": []
                    },
                    "history": []
                  },
                  "pagination": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceDisabled"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/scraper/parser/presets/pst_7Qk3' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/scraper/parser/presets/pst_7Qk3',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/parser/presets/pst_7Qk3\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/parser/presets/pst_7Qk3');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      },
      "put": {
        "operationId": "updateParserPreset",
        "tags": [
          "Parser presets"
        ],
        "summary": "Update a preset",
        "description": "Rename, replace the parser (bumps the version), toggle `autoHeal`, update `fields`/`sourceUrl`. Only the keys you send change. Free.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "parser": {
                    "$ref": "#/components/schemas/ExtractSchema",
                    "description": "Non-empty, at most 25 fields."
                  },
                  "autoHeal": {
                    "type": "boolean"
                  },
                  "fields": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    }
                  },
                  "sourceUrl": {
                    "type": "string"
                  }
                }
              },
              "example": {
                "autoHeal": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/ParserPreset"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Preset updated",
                  "payload": {
                    "id": "pst_7Qk3",
                    "name": "example-product",
                    "parser": {
                      "title": "h1.product-title",
                      "price": "span.price"
                    },
                    "version": 1,
                    "autoHeal": false,
                    "createdAt": 1759759331000,
                    "updatedAt": 1759840000000,
                    "lastHealAt": null,
                    "stats": {
                      "runs": 12,
                      "lastRunAt": 1759830000000,
                      "fields": {},
                      "recent": []
                    },
                    "history": []
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceDisabled"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X PUT 'https://api.quanticdata.io/v1/scraper/parser/presets/pst_7Qk3' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"autoHeal\":false}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.put(\n    'https://api.quanticdata.io/v1/scraper/parser/presets/pst_7Qk3',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\n        \"autoHeal\": false\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/parser/presets/pst_7Qk3\", {\n  method: \"PUT\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"autoHeal\": false\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/parser/presets/pst_7Qk3');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'PUT',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'autoHeal' => false\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      },
      "delete": {
        "operationId": "deleteParserPreset",
        "tags": [
          "Parser presets"
        ],
        "summary": "Delete a preset",
        "description": "Removes the preset and its version history. Scrapes that still send its `presetId` answer 404 afterwards. Free.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "responses": {
          "200": {
            "description": "Deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                },
                "example": {
                  "type": "response",
                  "message": "Preset deleted",
                  "payload": {
                    "ok": true
                  },
                  "pagination": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceDisabled"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X DELETE 'https://api.quanticdata.io/v1/scraper/parser/presets/pst_7Qk3' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.delete(\n    'https://api.quanticdata.io/v1/scraper/parser/presets/pst_7Qk3',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/parser/presets/pst_7Qk3\", {\n  method: \"DELETE\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/parser/presets/pst_7Qk3');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'DELETE',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/scraper/parser/presets/{id}/heal": {
      "parameters": [
        {
          "$ref": "#/components/parameters/presetId"
        }
      ],
      "post": {
        "operationId": "healParserPreset",
        "tags": [
          "Parser presets"
        ],
        "summary": "Regenerate a preset's parser now",
        "description": "The manual trigger of the repair that runs automatically when a preset decays: refetches `sourceUrl`, asks the model for fresh selectors and adopts them only if they extract more of the page than the current ones. `force: true` bypasses the cooldown between heals. Billed like a generation, and only when a new version was actually produced (`healed: true`).",
        "x-price-key": "parser_generate",
        "x-pricing-note": "parser_generate only when healed is true.",
        "x-rate-limit": "per-tier",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "force": {
                    "type": "boolean",
                    "default": false
                  }
                }
              },
              "example": {
                "force": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Heal attempted (message says whether a new version was adopted).",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/HealResult"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Preset healed",
                  "payload": {
                    "healed": true,
                    "reason": "coverage improved",
                    "version": 2,
                    "coverageBefore": 0.5,
                    "coverageAfter": 1,
                    "parser": {
                      "title": "h1[itemprop=name]",
                      "price": "span.price-now"
                    },
                    "usage": {
                      "cost_usd": 0.02,
                      "free_usd": 0.02,
                      "paid_usd": 0
                    }
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "503": {
            "description": "Data API off for your key, or the generator's model is not configured.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/scraper/parser/presets/pst_7Qk3/heal' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"force\":false}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/scraper/parser/presets/pst_7Qk3/heal',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\n        \"force\": false\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/parser/presets/pst_7Qk3/heal\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"force\": false\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/parser/presets/pst_7Qk3/heal');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'force' => false\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/scraper/parser/presets/{id}/stats": {
      "parameters": [
        {
          "$ref": "#/components/parameters/presetId"
        }
      ],
      "get": {
        "operationId": "getParserPresetStats",
        "tags": [
          "Parser presets"
        ],
        "summary": "How well a preset still works",
        "description": "Lifetime success rate per field, mean coverage over the recent window and whether the preset now counts as decayed (the signal that triggers self-healing). Free — it is the health check of a parser you already paid to build.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "responses": {
          "200": {
            "description": "Stats.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/PresetStatsView"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Preset stats",
                  "payload": {
                    "id": "pst_7Qk3",
                    "name": "example-product",
                    "version": 2,
                    "runs": 12,
                    "lastRunAt": 1759830000000,
                    "successRateByField": {
                      "title": 1,
                      "price": 0.917
                    },
                    "recentCoverage": 0.96,
                    "decayed": false,
                    "autoHeal": true,
                    "lastHealAt": 1759840000000
                  },
                  "pagination": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceDisabled"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/scraper/parser/presets/pst_7Qk3/stats' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/scraper/parser/presets/pst_7Qk3/stats',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/parser/presets/pst_7Qk3/stats\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/parser/presets/pst_7Qk3/stats');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/scraper/usage": {
      "get": {
        "operationId": "getUsage",
        "tags": [
          "Account"
        ],
        "summary": "Per-day usage and cost",
        "description": "Request counts (total and per query type), proxy bandwidth, AI token cost and billed vs free-tier spend per UTC day for the calling key's account, read from the daily aggregation. Free; not subject to the Data API kill switch.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "parameters": [
          {
            "name": "days",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 90,
              "default": 30
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Usage report.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "days": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/UsageDay"
                              }
                            },
                            "totals": {
                              "type": "object",
                              "properties": {
                                "requests": {
                                  "type": "integer"
                                },
                                "by_type": {
                                  "type": "object"
                                },
                                "proxy_kb": {
                                  "type": "number"
                                },
                                "billed_usd": {
                                  "type": "number"
                                },
                                "free_usd": {
                                  "type": "number"
                                }
                              }
                            },
                            "period_days": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Scraper usage",
                  "payload": {
                    "days": [
                      {
                        "date": "2026-10-06",
                        "requests": 143,
                        "by_type": {
                          "extract": 120,
                          "google": 20,
                          "map": 3
                        },
                        "proxy_kb": 61230,
                        "ai_cost_usd": 0,
                        "billed_usd": 0,
                        "free_usd": 0.0375
                      }
                    ],
                    "totals": {
                      "requests": 143,
                      "by_type": {
                        "extract": 120,
                        "google": 20,
                        "map": 3
                      },
                      "proxy_kb": 61230,
                      "billed_usd": 0,
                      "free_usd": 0.0375
                    },
                    "period_days": 30
                  },
                  "pagination": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/scraper/usage' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/scraper/usage',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/usage\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/usage');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/scraper/billing": {
      "get": {
        "operationId": "getBilling",
        "tags": [
          "Account"
        ],
        "summary": "Billing status and your price list",
        "description": "Current price list with your tier's discount applied (keyed like pricing.json), monthly free allowance and what is left of it, wallet balance, active tier, billing mode and the per-minute limits each mode carries. Lets a client or an agent budget its calls without a dashboard round-trip. Free; not subject to the Data API kill switch.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "responses": {
          "200": {
            "description": "Billing status.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/BillingStatus"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Billing status",
                  "payload": {
                    "billing_enabled": true,
                    "billed": true,
                    "balance": 12.5,
                    "tier": {
                      "key": "payg",
                      "name": "Pay as you go",
                      "discount_pct": 0,
                      "rate_limit_per_min": 20
                    },
                    "billing_mode": {
                      "preference": "free_first",
                      "effective": "free_first",
                      "available": true,
                      "free_first_rate_limit_per_min": 20,
                      "balance_rate_limit_per_min": 300,
                      "effective_rate_limit_per_min": 20
                    },
                    "free_monthly_usd": 2,
                    "free_remaining_usd": 1.62,
                    "ai_token_markup": 2,
                    "prices_usd": {
                      "extract": 0.0015,
                      "extract_render": 0.0025,
                      "serp": 0.0009,
                      "serp_render": 0.002,
                      "map": 0.003,
                      "seo_audit": 0.003,
                      "crawl_page": 0.0003,
                      "batch_url": 0.0004,
                      "collector_result": 0.002
                    }
                  },
                  "pagination": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/scraper/billing' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/scraper/billing',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/billing\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/billing');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/public/proxies": {
      "get": {
        "operationId": "listProxies",
        "tags": [
          "Proxies"
        ],
        "summary": "List your proxy plans",
        "description": "Every proxy service on the account (residential basic/premium/private, ISP, premium ISP, datacenter, datacenter traffic, IPv6, mobile, mobile v2) with credentials, bandwidth left, expiry and the `orderId` the generate and whitelist endpoints take. Free; no Data API billing. Plans disabled by support are not listed. Premium ISP plans (`planType: isppremium`, bought in the dashboard or with `POST /public/premium-isp/orders`) are both the ready-made pool plans and the city plans (City and carrier, Fraud score 0). They have no plan-level login (`username` and `password` are empty strings): every dedicated IP has its own login, returned by `POST /public/proxies/generate`, and `ips` is the number of IPs. IP whitelisting and credential changes are not available on Premium ISP plans. City plans report `region` as `premium-isp-city`, or `premium-isp-city-fraud-score-0` for Fraud score 0 plans. Premium ISP IPs reach only ports 80 and 443. Pool plans also cannot open banking, payment or government sites; city plans (Fraud score 0 included) have no site blocks (see the Terms of Service).",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          },
          {
            "name": "planType",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "residentialbasic",
                "residentialpremium",
                "resiprivate",
                "isp",
                "isppremium",
                "datacenter",
                "datacentertraffic",
                "ipv6",
                "mobile",
                "mobile_v2"
              ]
            }
          },
          {
            "name": "active",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            },
            "description": "Filter by expiry; omit for all."
          }
        ],
        "responses": {
          "200": {
            "description": "Plans.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "proxies": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/ProxyPlan"
                              }
                            },
                            "pagination": {
                              "type": "object",
                              "properties": {
                                "total": {
                                  "type": "integer"
                                },
                                "limit": {
                                  "type": "integer"
                                },
                                "offset": {
                                  "type": "integer"
                                },
                                "hasMore": {
                                  "type": "boolean"
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Success",
                  "payload": {
                    "proxies": [
                      {
                        "id": "prx_1",
                        "orderId": "ord_8c21",
                        "planName": "Residential Premium 5 GB",
                        "planType": "residentialpremium",
                        "planTypeName": "Residential Premium",
                        "username": "user_8c21",
                        "password": "p4ssw0rd",
                        "bandwidth": 5,
                        "bandwidthGB": 5,
                        "bandwidthLeft": 3.2,
                        "bandwidthLeftGB": 3.2,
                        "bandwidthUsed": 1.8,
                        "bandwidthUsedGB": 1.8,
                        "bandwidthUsagePercent": 36,
                        "isUnlimited": false,
                        "expiry": "2026-11-06T00:00:00.000Z",
                        "expiresAt": "2026-11-06T00:00:00.000Z",
                        "isActive": true,
                        "isExpired": false,
                        "daysRemaining": 30,
                        "hoursRemaining": 720,
                        "ips": 0,
                        "whitelistSlots": 0,
                        "whitelistedIPs": [],
                        "region": "Global",
                        "speed": null,
                        "highConcurrency": false,
                        "highPriority": false,
                        "createdAt": "2026-10-06T10:00:00.000Z"
                      }
                    ],
                    "pagination": {
                      "total": 1,
                      "limit": 50,
                      "offset": 0,
                      "hasMore": false
                    }
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/public/proxies' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/public/proxies',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/proxies\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/proxies');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/public/proxies/generate": {
      "post": {
        "operationId": "generateProxies",
        "tags": [
          "Proxies"
        ],
        "summary": "Generate proxy strings for a plan",
        "description": "Ready-to-use endpoint strings (credentials included) for one order, in HTTP or SOCKS5 and several formats, with the targeting the plan supports: country/state/city for residential and mobile, ISP code for Residential Premium and Mobile V2, ASN for Residential Basic and traffic-based Datacenter, static gateways for Datacenter. `rotation: sticky` keeps one IP for `sessionTime` minutes; `static` (IPv6 only) is a fixed session with no TTL. Mobile V2 can alternatively return the IP-auth proxy list for a whitelisted `ip`. Premium ISP orders still being provisioned answer 202 with `pending: true`. Premium ISP plans (pool and city) return one line per dedicated IP, each with its own login, and ignore targeting and rotation; `quantity` caps the number of lines (default 10), so pass the plan's `ips` to get every IP. `ipAddresses` holds the exit IP of each line, in the same order as `proxies`. City plans use one port for both HTTP and SOCKS5, and the host of a city line is a connection server that can change: generate the lines again instead of storing the host. The username of each line carries its targeting and session: generate new lines to change them instead of editing the strings by hand. `superSticky: true` keeps one IP per string for up to 24 hours on Residential Premium and Mobile; `udp: true` makes Residential Basic SOCKS5 strings relay UDP too. On Residential Basic, `os` picks exit IPs from devices running Windows, Android, iOS or macOS, and `gateway` picks the entry host of the strings in Europe (default), the United States or Asia, for a shorter route from your servers: the exit country still follows `country`. Which parameters apply depends on the plan type: unsupported ones are ignored, not rejected, except `superSticky`, `udp` and `os`, which answer 400 on a plan (or protocol) that cannot honour them; an unknown `os` value, or an unknown `gateway` on Residential Basic, is a 400 too. Free; no Data API billing (the plan's own bandwidth is consumed when you use the proxies).",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "orderId"
                ],
                "properties": {
                  "orderId": {
                    "type": "string",
                    "description": "From GET /public/proxies."
                  },
                  "protocol": {
                    "type": "string",
                    "enum": [
                      "http",
                      "socks5"
                    ],
                    "default": "http"
                  },
                  "format": {
                    "type": "string",
                    "enum": [
                      "user:pass@host:port",
                      "host:port:user:pass",
                      "http://user:pass@host:port",
                      "socks5://user:pass@host:port"
                    ],
                    "default": "user:pass@host:port",
                    "description": "`ip:port:user:pass` and the `…@ip:port` spellings are accepted as aliases."
                  },
                  "quantity": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 10000,
                    "default": 10
                  },
                  "country": {
                    "type": "string",
                    "description": "Lowercase country code (e.g. `us`); `all` = none."
                  },
                  "state": {
                    "type": "string",
                    "description": "Region slug (Residential Premium / Mobile V2: from the location tree). Alias `region`."
                  },
                  "city": {
                    "type": "string",
                    "description": "City slug."
                  },
                  "rotation": {
                    "type": "string",
                    "enum": [
                      "rotating",
                      "sticky",
                      "static"
                    ],
                    "default": "rotating",
                    "description": "`static` is IPv6 only."
                  },
                  "sessionTime": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 1440,
                    "default": 10,
                    "description": "Sticky session minutes (Residential Basic / Datacenter traffic: min 3 enforced by the gateway)."
                  },
                  "superSticky": {
                    "type": "boolean",
                    "default": false,
                    "description": "Residential Premium and Mobile: each string keeps one exit IP for up to 24 hours. Same as `rotation: \"sticky\"` with `sessionTime: 1440`, the longest session these plans accept, and it overrides both. Other plans answer 400 (use `sessionTime` there). Not with the Mobile V2 `ip` flow: whitelist the IP with `sticky: true` and `ttl: 86400` instead."
                  },
                  "udp": {
                    "type": "boolean",
                    "default": false,
                    "description": "Residential Basic with `protocol: \"socks5\"`: the strings also relay UDP (SOCKS5 UDP ASSOCIATE), for DNS, QUIC, VoIP and games. Works with rotating and sticky strings on the usual SOCKS5 ports. Your client must support UDP ASSOCIATE and keep the TCP connection it opened for the association open while it sends UDP. Other plans, or `protocol: \"http\"`, answer 400."
                  },
                  "isp": {
                    "type": "string",
                    "description": "ISP code (Residential Premium / Mobile V2) or carrier ASN (Mobile)."
                  },
                  "asn": {
                    "type": "string",
                    "description": "ASN, e.g. `AS12345` (Residential Basic / Datacenter traffic)."
                  },
                  "strict": {
                    "type": "boolean",
                    "default": false,
                    "description": "Residential/Datacenter Basic: `true` allows location fallback."
                  },
                  "os": {
                    "type": "string",
                    "enum": [
                      "any",
                      "windows",
                      "android",
                      "ios",
                      "macos"
                    ],
                    "default": "any",
                    "description": "Residential Basic: exit IPs from devices running this operating system (`mac` is accepted for `macos`). `any`, or no `os`, gives the largest pool. Works with every targeting and with rotating and sticky strings. Other plans answer 400."
                  },
                  "filter": {
                    "type": "string",
                    "enum": [
                      "speed",
                      "speed-quality",
                      "quality"
                    ],
                    "description": "Residential Premium / Mobile V2 pool filter (default: max pool)."
                  },
                  "isExtension": {
                    "type": "boolean",
                    "default": false,
                    "description": "Rewrite hostnames with a unique prefix so a browser extension cannot cache the proxy (needs the wildcard DNS of the gateway)."
                  },
                  "ip": {
                    "type": "string",
                    "description": "Mobile V2: a whitelisted IP — returns the IP-auth proxy list instead of user:pass strings."
                  },
                  "gateway": {
                    "type": "string",
                    "enum": [
                      "ww",
                      "us",
                      "eu",
                      "as"
                    ],
                    "default": "ww",
                    "description": "Mobile V2: region gateway. Residential Basic: entry host of the user:pass strings, `eu` (default; `ww` means `eu`), `us` or `as`. Pick the one closest to where your traffic starts; the exit country still follows `country`, and the same credentials and ports work on all three. Other values answer 400 on Residential Basic."
                  }
                }
              },
              "example": {
                "orderId": "ord_8c21",
                "protocol": "http",
                "format": "user:pass@host:port",
                "quantity": 2,
                "country": "us",
                "rotation": "sticky",
                "sessionTime": 10
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Proxy strings. Example: two sticky US lines of a Residential Premium plan.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/GeneratedProxies"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "success",
                  "payload": {
                    "orderId": "ord_8c21",
                    "quantity": 2,
                    "protocol": "http",
                    "format": "user:pass@host:port",
                    "rotation": "sticky",
                    "sessionTime": 10,
                    "superSticky": false,
                    "udp": false,
                    "geoTargeting": {
                      "country": "us",
                      "state": null,
                      "city": null
                    },
                    "proxies": [
                      "user_8c21-country-us-sid-k3f9a1b2c3d4-ttl-10m:p4ssw0rd@residentialpremium.quanticdata.io:8080",
                      "user_8c21-country-us-sid-q7w2e5r8t1y4-ttl-10m:p4ssw0rd@residentialpremium.quanticdata.io:8080"
                    ],
                    "bandwidth": 5,
                    "bandwidthLeft": 3.2,
                    "whitelist": []
                  },
                  "pagination": {}
                }
              }
            }
          },
          "202": {
            "description": "Premium ISP order still being provisioned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                },
                "example": {
                  "type": "response",
                  "message": "Your dedicated IPs are being prepared. Please check again shortly.",
                  "payload": {
                    "orderId": "ord_8c21",
                    "pending": true,
                    "proxies": []
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "description": "Missing orderId, expired plan, inactive sub-user, a plan type that cannot generate, `superSticky` / `udp` / `os` on a plan or protocol that does not support them, or an unknown `os` or Residential Basic `gateway` value.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "Proxy has expired"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/PlanUnavailable"
          },
          "404": {
            "description": "Order (or its proxy) not found on this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "Order or proxy not found"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "502": {
            "description": "The plan's network did not answer; retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "Unable to generate proxies. Please try again."
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/public/proxies/generate' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"orderId\":\"ord_8c21\",\"protocol\":\"http\",\"format\":\"user:pass@host:port\",\"quantity\":2,\"country\":\"us\",\"rotation\":\"sticky\",\"sessionTime\":10}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/public/proxies/generate',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\n        \"orderId\": \"ord_8c21\",\n        \"protocol\": \"http\",\n        \"format\": \"user:pass@host:port\",\n        \"quantity\": 2,\n        \"country\": \"us\",\n        \"rotation\": \"sticky\",\n        \"sessionTime\": 10\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/proxies/generate\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"orderId\": \"ord_8c21\",\n    \"protocol\": \"http\",\n    \"format\": \"user:pass@host:port\",\n    \"quantity\": 2,\n    \"country\": \"us\",\n    \"rotation\": \"sticky\",\n    \"sessionTime\": 10\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/proxies/generate');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'orderId' => 'ord_8c21',\n    'protocol' => 'http',\n    'format' => 'user:pass@host:port',\n    'quantity' => 2,\n    'country' => 'us',\n    'rotation' => 'sticky',\n    'sessionTime' => 10\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/public/proxies/ip-info": {
      "get": {
        "operationId": "getIpInfo",
        "tags": [
          "Proxies"
        ],
        "summary": "Geolocate an IP",
        "description": "Country, region, city, coordinates, timezone and network (ASN and operator) of a public IP address, from ipinfo.io, the database our Terms use for IP location. Use it to check where a sticky session or an ISP IP exits. Answers are cached for 24 hours per IP. New lookups share a daily cap: when it is reached, or when the source does not answer, the call returns 503 with `Retry-After` and cached IPs keep answering. Private, reserved and malformed addresses return 400. Free.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "parameters": [
          {
            "name": "ip",
            "in": "query",
            "required": true,
            "description": "Public IPv4 or IPv6 address.",
            "schema": {
              "type": "string"
            },
            "example": "8.8.8.8"
          }
        ],
        "responses": {
          "200": {
            "description": "IP information.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/IpInfo"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Success",
                  "payload": {
                    "ip": "8.8.8.8",
                    "country": "United States",
                    "countryCode": "US",
                    "flag": "🇺🇸",
                    "region": "California",
                    "regionCode": "",
                    "city": "Mountain View",
                    "zip": "94043",
                    "lat": 38.0088,
                    "lon": -122.1175,
                    "timezone": "America/Los_Angeles",
                    "isp": "Google LLC",
                    "org": "Google LLC",
                    "as": "AS15169 Google LLC"
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "description": "Missing `ip`, or not a public IPv4/IPv6 address: private, reserved and malformed addresses are not looked up.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "IP address is required. Use ?ip=x.x.x.x"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "503": {
            "$ref": "#/components/responses/IpLookupUnavailable"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/public/proxies/ip-info?ip=8.8.8.8' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/public/proxies/ip-info?ip=8.8.8.8',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/proxies/ip-info?ip=8.8.8.8\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/proxies/ip-info?ip=8.8.8.8');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/public/ip-echo": {
      "get": {
        "operationId": "getIpEcho",
        "tags": [
          "Proxies"
        ],
        "summary": "Where your IP is, as Cloudflare sees it",
        "description": "Returns the IP the request comes from and where Cloudflare places it: the country, and when available the region, city, postal code, timezone and coordinates. Most sites sit behind Cloudflare and locate visitors the same way, so sending this request through one of your proxies shows the exit as those sites see it (for example `curl -x http://USER:PASS@HOST:PORT https://api.quanticdata.io/v1/public/ip-echo`). It does not look up another address and gives no network or ISP name: for those use Geolocate an IP. No API key, never cached. Free.",
        "security": [],
        "x-price-key": null,
        "x-rate-limit": "None of its own; the edge's limits apply.",
        "responses": {
          "200": {
            "description": "The caller's IP and Cloudflare's location for it.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/CloudflareLocation"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Success",
                  "payload": {
                    "ip": "203.0.113.10",
                    "countryCode": "US",
                    "country": "United States",
                    "region": "New York",
                    "regionCode": "NY",
                    "city": "New York",
                    "postalCode": "10001",
                    "timezone": "America/New_York",
                    "latitude": 40.7128,
                    "longitude": -74.006,
                    "continent": "NA",
                    "tor": false,
                    "precision": "city",
                    "viaCloudflare": true,
                    "source": "cloudflare"
                  },
                  "pagination": {}
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/public/ip-echo'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/public/ip-echo',\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/ip-echo\", {\n  method: \"GET\"\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/ip-echo');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/public/proxies/whitelist-ip": {
      "get": {
        "operationId": "listWhitelistIps",
        "tags": [
          "Proxies"
        ],
        "summary": "List whitelisted IPs of an order",
        "description": "The IPs allowed to use an IP-auth plan without credentials. Mobile V2 plans also return the detailed upstream entries (ports, geo, sticky) under `entries`. Free.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "parameters": [
          {
            "name": "orderId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Whitelist.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "orderId": {
                              "type": "string"
                            },
                            "whitelist_ip": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            },
                            "entries": {
                              "description": "Upstream entries (Residential Basic, Mobile V2) — shape depends on the plan's network."
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Success",
                  "payload": {
                    "orderId": "ord_8c21",
                    "whitelist_ip": [
                      "203.0.113.7"
                    ]
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/PlanUnavailable"
          },
          "404": {
            "description": "Order not found on this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/public/proxies/whitelist-ip?orderId=ORDERID' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/public/proxies/whitelist-ip?orderId=ORDERID',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/proxies/whitelist-ip?orderId=ORDERID\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/proxies/whitelist-ip?orderId=ORDERID');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      },
      "post": {
        "operationId": "addWhitelistIp",
        "tags": [
          "Proxies"
        ],
        "summary": "Whitelist an IP",
        "description": "Allows an IPv4 address to use the plan by IP authentication. Supported on Residential Basic, Datacenter (both kinds), ISP (`planType: isp`), IPv6 and Mobile V2; Residential Premium/Private and Premium ISP (`isppremium`, pool and city plans) authenticate by user:pass only and answer 200 with `whitelisted: false` and the message `Whitelist not required for this proxy type (use username:password auth).` Mobile V2 accepts extra port/targeting options and `action: update` to edit an existing entry. Free.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "orderId",
                  "ip"
                ],
                "properties": {
                  "orderId": {
                    "type": "string"
                  },
                  "ip": {
                    "type": "string",
                    "pattern": "^(\\d{1,3}\\.){3}\\d{1,3}$",
                    "description": "IPv4 address."
                  },
                  "action": {
                    "type": "string",
                    "enum": [
                      "add",
                      "update"
                    ],
                    "default": "add",
                    "description": "Mobile V2 only: `update` edits an existing entry's settings."
                  },
                  "ports_count": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 1000,
                    "description": "Mobile V2: ports to allocate."
                  },
                  "protocol": {
                    "type": "string",
                    "enum": [
                      "HTTP",
                      "SOCKS5"
                    ],
                    "description": "Mobile V2."
                  },
                  "country": {
                    "type": "string",
                    "description": "Mobile V2 geo targeting for the allocated ports."
                  },
                  "region": {
                    "type": "string",
                    "description": "Mobile V2."
                  },
                  "city": {
                    "type": "string",
                    "description": "Mobile V2."
                  },
                  "isp": {
                    "type": "string",
                    "description": "Mobile V2."
                  },
                  "sticky": {
                    "type": "boolean",
                    "description": "Mobile V2: keep the same IP per port."
                  },
                  "ttl": {
                    "type": "integer",
                    "description": "Mobile V2: sticky session TTL in seconds."
                  }
                }
              },
              "example": {
                "orderId": "ord_8c21",
                "ip": "203.0.113.7"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Whitelisted (or not applicable to this plan type).",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "ip": {
                              "type": "string"
                            },
                            "whitelisted": {
                              "type": "boolean"
                            },
                            "alreadyWhitelisted": {
                              "type": "boolean"
                            },
                            "whitelist_ip": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "IP whitelisted successfully",
                  "payload": {
                    "ip": "203.0.113.7",
                    "whitelisted": true,
                    "whitelist_ip": [
                      "203.0.113.7"
                    ]
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "description": "Missing fields, malformed IP, or the plan's network refused the entry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "Invalid IP address format"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/PlanUnavailable"
          },
          "404": {
            "description": "Order not found on this account (or its residential sub-user is missing).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/public/proxies/whitelist-ip' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"orderId\":\"ord_8c21\",\"ip\":\"203.0.113.7\"}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/public/proxies/whitelist-ip',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\n        \"orderId\": \"ord_8c21\",\n        \"ip\": \"203.0.113.7\"\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/proxies/whitelist-ip\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"orderId\": \"ord_8c21\",\n    \"ip\": \"203.0.113.7\"\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/proxies/whitelist-ip');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'orderId' => 'ord_8c21',\n    'ip' => '203.0.113.7'\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      },
      "delete": {
        "operationId": "removeWhitelistIp",
        "tags": [
          "Proxies"
        ],
        "summary": "Remove a whitelisted IP",
        "description": "Removes the IP from the plan's IP-auth list (Mobile V2 also accepts the entry `id`). Plans that authenticate by user:pass (Residential Premium/Private, Premium ISP) answer 200 with `removed: false`. Free.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "orderId",
                  "ip"
                ],
                "properties": {
                  "orderId": {
                    "type": "string"
                  },
                  "ip": {
                    "type": "string"
                  },
                  "id": {
                    "type": "string",
                    "description": "Mobile V2 entry id (alternative handle)."
                  }
                }
              },
              "example": {
                "orderId": "ord_8c21",
                "ip": "203.0.113.7"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Removed (or not applicable).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                },
                "example": {
                  "type": "response",
                  "message": "IP removed from whitelist",
                  "payload": {
                    "ip": "203.0.113.7",
                    "removed": true,
                    "whitelist_ip": []
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/PlanUnavailable"
          },
          "404": {
            "description": "Order not found on this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X DELETE 'https://api.quanticdata.io/v1/public/proxies/whitelist-ip' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"orderId\":\"ord_8c21\",\"ip\":\"203.0.113.7\"}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.delete(\n    'https://api.quanticdata.io/v1/public/proxies/whitelist-ip',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\n        \"orderId\": \"ord_8c21\",\n        \"ip\": \"203.0.113.7\"\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/proxies/whitelist-ip\", {\n  method: \"DELETE\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"orderId\": \"ord_8c21\",\n    \"ip\": \"203.0.113.7\"\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/proxies/whitelist-ip');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'DELETE',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'orderId' => 'ord_8c21',\n    'ip' => '203.0.113.7'\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/mcp/trial-config": {
      "get": {
        "operationId": "getMcpTrialConfig",
        "tags": [
          "Account"
        ],
        "summary": "No-key MCP trial settings",
        "description": "What the keyless trial of the hosted MCP endpoint allows right now for a brand: whether it is on, calls per client address per UTC day, calls across all addresses per day, and which tools it may run. Read by the hosted MCP servers once a minute; nothing secret in it, so it needs no API key and is cacheable for 60 s. The brand comes from `?brand=` or, failing that, from the request host.",
        "x-price-key": null,
        "x-rate-limit": "none",
        "security": [],
        "parameters": [
          {
            "name": "brand",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "QP",
                "QD"
              ]
            },
            "description": "QP = QuantumProxies, QD = QuanticData. Defaults to the brand of the host you call."
          }
        ],
        "responses": {
          "200": {
            "description": "Trial settings.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string"
                },
                "description": "`public, max-age=60`."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/TrialConfig"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "ok",
                  "payload": {
                    "brand": "QD",
                    "enabled": true,
                    "perIpPerDay": 5,
                    "perDay": 300,
                    "tools": [
                      "scrape",
                      "search",
                      "search_and_read",
                      "map",
                      "seo_audit",
                      "list_collectors",
                      "collector_run_status",
                      "proxy_locations"
                    ]
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/mcp/trial-config'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/mcp/trial-config',\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/mcp/trial-config\", {\n  method: \"GET\"\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/mcp/trial-config');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/public/premium-isp/pools": {
      "get": {
        "x-price-key": null,
        "x-pricing-note": "Prices come from the catalog (`GET /public/premium-isp/cities`, `GET /public/premium-isp/pools`) or from a quote, in USD, and are charged to the wallet balance. VAT on balance payments is 0%.",
        "x-rate-limit": "per-tier",
        "tags": [
          "Premium ISP"
        ],
        "operationId": "listPremiumIspPools",
        "summary": "List Premium ISP pools",
        "description": "Ready Premium ISP pools by country and site category: dedicated static IPs, unlimited bandwidth, 30-day plans. `available` tells whether a pool can be bought; `maxQuantity` caps one order (at most 200, lower when the pool is short of IPs, so read it again before a large order) and `stock` gives the IPs in stock when reported. Pools with `subnet: true` sell a whole /24 (256 IPs, one per order) and appear only while on sale. `fromPerIp` is the lowest price per IP. Free.",
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "required": false,
            "description": "ISO 3166-1 alpha-2 filter, e.g. `US`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Pools.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "enabled": {
                              "type": "boolean"
                            },
                            "days": {
                              "type": "integer"
                            },
                            "currency": {
                              "type": "string"
                            },
                            "fromPerIp": {
                              "type": [
                                "number",
                                "null"
                              ]
                            },
                            "pools": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/PremiumIspPool"
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Success",
                  "payload": {
                    "enabled": true,
                    "days": 30,
                    "currency": "USD",
                    "pools": [
                      {
                        "id": "premium-us-retail",
                        "country": "US",
                        "countryName": "United States",
                        "category": "retail",
                        "categoryName": "Retail",
                        "name": "Premium United States Retail ISP",
                        "description": "Dedicated static IPs optimized for retail websites, with unlimited bandwidth.",
                        "days": 30,
                        "minQuantity": 1,
                        "maxQuantity": 100,
                        "available": true,
                        "subnet": false,
                        "stock": 1591,
                        "features": {
                          "dedicated": true,
                          "unlimitedBandwidth": true,
                          "udp": true,
                          "maxSpeedGbps": 10,
                          "cityChoice": false,
                          "carrierChoice": false,
                          "replacementWithin24hOnRequest": true,
                          "subnetsOnRequest": true
                        }
                      }
                    ]
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/PremiumIspForbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/PremiumIspUnavailable"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/public/premium-isp/pools' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/public/premium-isp/pools',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/premium-isp/pools\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/premium-isp/pools');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/public/premium-isp/cities": {
      "get": {
        "x-price-key": null,
        "x-pricing-note": "Prices come from the catalog (`GET /public/premium-isp/cities`, `GET /public/premium-isp/pools`) or from a quote, in USD, and are charged to the wallet balance. VAT on balance payments is 0%.",
        "x-rate-limit": "per-tier",
        "tags": [
          "Premium ISP"
        ],
        "operationId": "listPremiumIspCities",
        "summary": "List Premium ISP cities with stock",
        "description": "City plans of one type (`city`: City and carrier; `fraud-score-0`: every IP checked for a fraud score of 0 before delivery): the plan lengths on sale with their price per IP and quantity ranges, the carrier fee, and every country and city with the IPs in stock. Cached up to 2 minutes; the purchase reads the stock again. Free.",
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "city",
                "fraud-score-0"
              ],
              "default": "city"
            }
          },
          {
            "name": "udp",
            "in": "query",
            "required": false,
            "description": "`1` for UDP-capable IPs.",
            "schema": {
              "type": "string",
              "enum": [
                "0",
                "1"
              ],
              "default": "0"
            }
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "description": "ISO 3166-1 alpha-2 filter.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Catalog.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/PremiumIspCityCatalog"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Success",
                  "payload": {
                    "enabled": true,
                    "type": "city",
                    "udp": false,
                    "maxAgeSeconds": 120,
                    "types": [
                      {
                        "id": "city",
                        "name": "City and carrier",
                        "available": true
                      },
                      {
                        "id": "fraud-score-0",
                        "name": "Fraud score 0",
                        "available": true
                      }
                    ],
                    "countries": [
                      {
                        "code": "US",
                        "name": "United States",
                        "stock": 1234,
                        "cities": [
                          {
                            "location": "United States - New York City",
                            "name": "New York City",
                            "stock": 8
                          }
                        ]
                      }
                    ]
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/PremiumIspForbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/PremiumIspUnavailable"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/public/premium-isp/cities' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/public/premium-isp/cities',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/premium-isp/cities\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/premium-isp/cities');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/public/premium-isp/cities/carriers": {
      "get": {
        "x-price-key": null,
        "x-pricing-note": "Prices come from the catalog (`GET /public/premium-isp/cities`, `GET /public/premium-isp/pools`) or from a quote, in USD, and are charged to the wallet balance. VAT on balance payments is 0%.",
        "x-rate-limit": "per-tier",
        "tags": [
          "Premium ISP"
        ],
        "operationId": "listPremiumIspCarriers",
        "summary": "List the carriers (ASN) of a city",
        "description": "Carriers with the IPs in stock in one city of the catalog. Pass one `asn` to the quote or the purchase to pin the carrier (a carrier fee per IP applies, at purchase and at every renewal). Each new city is a live read, so this call has its own hourly cap per account (60). Free.",
        "parameters": [
          {
            "name": "location",
            "in": "query",
            "required": true,
            "description": "`location` from `GET /public/premium-isp/cities`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "city",
                "fraud-score-0"
              ],
              "default": "city"
            }
          },
          {
            "name": "udp",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "0",
                "1"
              ],
              "default": "0"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Carriers.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "location": {
                              "type": "string"
                            },
                            "type": {
                              "type": "string"
                            },
                            "udp": {
                              "type": "boolean"
                            },
                            "maxAgeSeconds": {
                              "type": "integer"
                            },
                            "carriers": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/PremiumIspCarrier"
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Success",
                  "payload": {
                    "location": "United States - New York City",
                    "type": "city",
                    "udp": false,
                    "maxAgeSeconds": 120,
                    "carriers": [
                      {
                        "asn": 7922,
                        "name": "Comcast",
                        "stock": 5
                      }
                    ]
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/PremiumIspForbidden"
          },
          "409": {
            "$ref": "#/components/responses/PremiumIspConflict"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/PremiumIspUnavailable"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/public/premium-isp/cities/carriers?location=LOCATION' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/public/premium-isp/cities/carriers?location=LOCATION',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/premium-isp/cities/carriers?location=LOCATION\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/premium-isp/cities/carriers?location=LOCATION');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/public/premium-isp/quote": {
      "post": {
        "x-price-key": null,
        "x-pricing-note": "Prices come from the catalog (`GET /public/premium-isp/cities`, `GET /public/premium-isp/pools`) or from a quote, in USD, and are charged to the wallet balance. VAT on balance payments is 0%.",
        "x-rate-limit": "per-tier",
        "tags": [
          "Premium ISP"
        ],
        "operationId": "quotePremiumIsp",
        "summary": "Quote a Premium ISP selection",
        "description": "Server-side price of a pool or city selection paid from the balance, with VAT (0% on balance) and whether your balance covers it. Nothing is reserved: the purchase checks stock and price again before charging. Free (300 quotes an hour per account). `siteCheck` does not change the price.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PremiumIspSelection"
              },
              "examples": {
                "city": {
                  "value": {
                    "product": "city",
                    "type": "city",
                    "length": "1_month",
                    "location": "United States - New York City",
                    "asn": 7922,
                    "udp": false,
                    "replacements": 2,
                    "quantity": 10
                  }
                },
                "pool": {
                  "value": {
                    "product": "pool",
                    "poolId": "premium-us-retail",
                    "quantity": 5
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Quote.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/PremiumIspQuote"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Success",
                  "payload": {
                    "product": "city",
                    "type": "city",
                    "length": "1_month",
                    "days": 30,
                    "location": "United States - New York City",
                    "city": "New York City",
                    "country": "United States",
                    "asn": 7922,
                    "carrierName": "Comcast",
                    "udp": false,
                    "quantity": 10,
                    "replacements": 2,
                    "vatRate": 0,
                    "vat": 0,
                    "currency": "USD",
                    "paymentMethod": "BALANCE",
                    "sufficientBalance": true,
                    "reserved": false,
                    "quotedAt": "2026-10-19T10:00:00.000Z"
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/PremiumIspForbidden"
          },
          "409": {
            "$ref": "#/components/responses/PremiumIspConflict"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/PremiumIspUnavailable"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/public/premium-isp/quote' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/public/premium-isp/quote',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/premium-isp/quote\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/premium-isp/quote');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/public/premium-isp/orders": {
      "get": {
        "x-price-key": null,
        "x-pricing-note": "Prices come from the catalog (`GET /public/premium-isp/cities`, `GET /public/premium-isp/pools`) or from a quote, in USD, and are charged to the wallet balance. VAT on balance payments is 0%.",
        "x-rate-limit": "per-tier",
        "tags": [
          "Premium ISP"
        ],
        "operationId": "listPremiumIspOrders",
        "summary": "List Premium ISP orders",
        "description": "Your Premium ISP orders (pools and city plans), newest first, with their status. From our records only, no live reads. Renewals are not separate orders. Free.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Orders.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "orders": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/PremiumIspOrder"
                              }
                            },
                            "pagination": {
                              "type": "object"
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Success",
                  "payload": {
                    "orders": [
                      {
                        "id": "ord_5f2a",
                        "product": "city",
                        "status": "active",
                        "createdAt": "2026-10-19T10:00:00.000Z",
                        "selection": {
                          "type": "city",
                          "length": "1_month",
                          "location": "United States - New York City",
                          "city": "New York City",
                          "country": "United States",
                          "asn": 7922,
                          "carrierName": "Comcast",
                          "udp": false,
                          "replacements": 2
                        },
                        "quantity": 10,
                        "days": 30,
                        "region": "premium-isp-city",
                        "expiresAt": "2026-11-18T10:00:00.000Z",
                        "daysRemaining": 30,
                        "invoice": {
                          "id": "inv_77c1",
                          "vat": 0,
                          "vatRate": 0,
                          "paid": true,
                          "status": "PAID",
                          "refunded": false
                        },
                        "replacements": {
                          "bought": 2,
                          "used": 0,
                          "checking": 0,
                          "left": 2
                        }
                      }
                    ],
                    "pagination": {
                      "total": 1,
                      "limit": 50,
                      "offset": 0,
                      "hasMore": false
                    }
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/PremiumIspForbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/PremiumIspUnavailable"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/public/premium-isp/orders' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/public/premium-isp/orders',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/premium-isp/orders\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/premium-isp/orders');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      },
      "post": {
        "x-price-key": null,
        "x-pricing-note": "Prices come from the catalog (`GET /public/premium-isp/cities`, `GET /public/premium-isp/pools`) or from a quote, in USD, and are charged to the wallet balance. VAT on balance payments is 0%.",
        "x-rate-limit": "per-tier",
        "tags": [
          "Premium ISP"
        ],
        "operationId": "createPremiumIspOrder",
        "summary": "Buy Premium ISP IPs from the balance",
        "description": "Buys a pool or city selection and charges the wallet balance (VAT 0%). The `Idempotency-Key` header is required: a retry with the same key never charges twice and answers with the same order. `maxTotal` (optional) refuses the purchase if the price went above it. The balance is checked before anything is created. Answers: 201 delivered; 202 paid and being prepared (poll `GET /public/premium-isp/orders/{orderId}`, see `Location`); 200 `replayed: true` for a key already used; 422 not delivered and refunded to the balance. Coupons are not accepted through the API. Whole /24 subnets and the 24-hour replacement of pool IPs are arranged with support. 20 purchases an hour per account. A city selection may carry `siteCheck` (a URL and the status it must answer): only IPs that pass it are delivered; if none does, the order fails and the balance is refunded by itself.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/PremiumIspSelection"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "maxTotal": {
                        "type": "number",
                        "description": "Highest total you accept, in USD. Above it: 409 `PRICE_CHANGED`, nothing charged."
                      }
                    }
                  }
                ]
              },
              "examples": {
                "city": {
                  "value": {
                    "product": "city",
                    "type": "city",
                    "length": "1_month",
                    "location": "United States - New York City",
                    "asn": 7922,
                    "udp": false,
                    "replacements": 2,
                    "quantity": 10
                  }
                },
                "pool": {
                  "value": {
                    "product": "pool",
                    "poolId": "premium-us-retail",
                    "quantity": 5
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Replayed: this Idempotency-Key was already used for this selection. Nothing new was charged.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "replayed": {
                              "type": "boolean"
                            },
                            "order": {
                              "$ref": "#/components/schemas/PremiumIspOrder"
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "This purchase was already received.",
                  "payload": {
                    "replayed": true,
                    "order": {
                      "id": "ord_5f2a",
                      "product": "city",
                      "status": "active",
                      "createdAt": "2026-10-19T10:00:00.000Z",
                      "selection": {
                        "type": "city",
                        "length": "1_month",
                        "location": "United States - New York City",
                        "city": "New York City",
                        "country": "United States",
                        "asn": 7922,
                        "carrierName": "Comcast",
                        "udp": false,
                        "replacements": 2
                      },
                      "quantity": 10,
                      "days": 30,
                      "region": "premium-isp-city",
                      "expiresAt": "2026-11-18T10:00:00.000Z",
                      "daysRemaining": 30,
                      "invoice": {
                        "id": "inv_77c1",
                        "vat": 0,
                        "vatRate": 0,
                        "paid": true,
                        "status": "PAID",
                        "refunded": false
                      },
                      "replacements": {
                        "bought": 2,
                        "used": 0,
                        "checking": 0,
                        "left": 2
                      }
                    }
                  },
                  "pagination": {}
                }
              }
            }
          },
          "201": {
            "description": "Delivered.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "order": {
                              "$ref": "#/components/schemas/PremiumIspOrder"
                            },
                            "invoice": {
                              "type": "object"
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Success",
                  "payload": {
                    "order": {
                      "id": "ord_5f2a",
                      "product": "city",
                      "status": "active",
                      "createdAt": "2026-10-19T10:00:00.000Z",
                      "selection": {
                        "type": "city",
                        "length": "1_month",
                        "location": "United States - New York City",
                        "city": "New York City",
                        "country": "United States",
                        "asn": 7922,
                        "carrierName": "Comcast",
                        "udp": false,
                        "replacements": 2
                      },
                      "quantity": 10,
                      "days": 30,
                      "region": "premium-isp-city",
                      "expiresAt": "2026-11-18T10:00:00.000Z",
                      "daysRemaining": 30,
                      "invoice": {
                        "id": "inv_77c1",
                        "vat": 0,
                        "vatRate": 0,
                        "paid": true,
                        "status": "PAID",
                        "refunded": false
                      },
                      "replacements": {
                        "bought": 2,
                        "used": 0,
                        "checking": 0,
                        "left": 2
                      }
                    },
                    "invoice": {
                      "id": "inv_77c1",
                      "vat": 0,
                      "vatRate": 0,
                      "paid": true
                    }
                  },
                  "pagination": {}
                }
              }
            }
          },
          "202": {
            "description": "Paid, the IPs are being prepared. Poll the order; do not buy again. If a city order cannot be filled, it is closed and the amount paid goes back to your balance: the order then reads `refunded`.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "order": {
                              "$ref": "#/components/schemas/PremiumIspOrder"
                            },
                            "invoice": {
                              "type": "object"
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Payment received. Your IPs are being prepared: poll the order.",
                  "payload": {
                    "order": {
                      "id": "ord_5f2a",
                      "product": "city",
                      "status": "provisioning",
                      "createdAt": "2026-10-19T10:00:00.000Z",
                      "selection": {
                        "type": "city",
                        "length": "1_month",
                        "location": "United States - New York City",
                        "city": "New York City",
                        "country": "United States",
                        "asn": 7922,
                        "carrierName": "Comcast",
                        "udp": false,
                        "replacements": 2
                      },
                      "quantity": 10,
                      "days": 30,
                      "region": "premium-isp-city",
                      "expiresAt": null,
                      "daysRemaining": null,
                      "invoice": {
                        "id": "inv_77c1",
                        "vat": 0,
                        "vatRate": 0,
                        "paid": true,
                        "status": "PAID",
                        "refunded": false
                      },
                      "replacements": {
                        "bought": 2,
                        "used": 0,
                        "checking": 0,
                        "left": 2
                      }
                    },
                    "invoice": {
                      "id": "inv_77c1",
                      "vat": 0,
                      "vatRate": 0,
                      "paid": true
                    }
                  },
                  "pagination": {}
                }
              }
            },
            "headers": {
              "Location": {
                "description": "The order to poll.",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PremiumIspPaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/PremiumIspForbidden"
          },
          "409": {
            "$ref": "#/components/responses/PremiumIspConflict"
          },
          "422": {
            "$ref": "#/components/responses/PremiumIspNotDelivered"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/PremiumIspUnavailable"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/public/premium-isp/orders' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/public/premium-isp/orders',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/premium-isp/orders\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/premium-isp/orders');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/public/premium-isp/orders/{orderId}": {
      "get": {
        "x-price-key": null,
        "x-pricing-note": "Prices come from the catalog (`GET /public/premium-isp/cities`, `GET /public/premium-isp/pools`) or from a quote, in USD, and are charged to the wallet balance. VAT on balance payments is 0%.",
        "x-rate-limit": "per-tier",
        "tags": [
          "Premium ISP"
        ],
        "operationId": "getPremiumIspOrder",
        "summary": "Get a Premium ISP order and its proxy lines",
        "description": "Status of one order. With `include=lines` it also returns the proxy lines (one per dedicated IP, with its own login), read live: 120 reads an hour per account. While the IPs are being prepared it answers 202 `LINES_PENDING`. Premium ISP IPs reach only ports 80 and 443. Pool plans also cannot open banking, payment or government sites. City plans open banks and government sites, but payment-processor domains (Stripe and similar) are blocked. The free auto-replace state of a city plan is read from `GET .../auto-replace`. Free.",
        "parameters": [
          {
            "$ref": "#/components/parameters/PremiumIspOrderId"
          },
          {
            "name": "include",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "lines"
              ]
            }
          },
          {
            "name": "protocol",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "http",
                "socks5"
              ],
              "default": "http"
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "host:port:user:pass",
                "ip:port:user:pass",
                "user:pass@host:port",
                "http://user:pass@host:port",
                "socks5://user:pass@host:port"
              ],
              "default": "host:port:user:pass"
            }
          },
          {
            "name": "quantity",
            "in": "query",
            "required": false,
            "description": "Return only the first N lines.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "server",
            "in": "query",
            "required": false,
            "description": "City plans: a connection server id from `lines.servers`. Default `auto` (the closest server); an id the plan does not offer is served as `auto`. The host can change, so generate the lines again instead of storing it.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Order (and lines).",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "order": {
                              "$ref": "#/components/schemas/PremiumIspOrder"
                            },
                            "lines": {
                              "$ref": "#/components/schemas/PremiumIspLines"
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Success",
                  "payload": {
                    "order": {
                      "id": "ord_5f2a",
                      "product": "city",
                      "status": "active",
                      "createdAt": "2026-10-19T10:00:00.000Z",
                      "selection": {
                        "type": "city",
                        "length": "1_month",
                        "location": "United States - New York City",
                        "city": "New York City",
                        "country": "United States",
                        "asn": 7922,
                        "carrierName": "Comcast",
                        "udp": false,
                        "replacements": 2
                      },
                      "quantity": 10,
                      "days": 30,
                      "region": "premium-isp-city",
                      "expiresAt": "2026-11-18T10:00:00.000Z",
                      "daysRemaining": 30,
                      "invoice": {
                        "id": "inv_77c1",
                        "vat": 0,
                        "vatRate": 0,
                        "paid": true,
                        "status": "PAID",
                        "refunded": false
                      },
                      "replacements": {
                        "bought": 2,
                        "used": 0,
                        "checking": 0,
                        "left": 2,
                        "offline": []
                      }
                    },
                    "lines": {
                      "protocol": "http",
                      "format": "host:port:user:pass",
                      "proxies": [
                        "203.0.113.7:8000:u_1a2b:p_3c4d"
                      ],
                      "ipAddresses": [
                        "203.0.113.7"
                      ],
                      "expiresAt": "2026-11-18T10:00:00.000Z",
                      "servers": [
                        {
                          "id": "auto",
                          "label": "Auto (closest server)"
                        },
                        {
                          "id": "us-east",
                          "label": "US East (Virginia)"
                        },
                        {
                          "id": "de",
                          "label": "Frankfurt"
                        },
                        {
                          "id": "sg",
                          "label": "Singapore"
                        }
                      ],
                      "server": "auto"
                    }
                  },
                  "pagination": {}
                }
              }
            }
          },
          "202": {
            "description": "The IPs are being prepared: check again shortly.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "examples": {
                  "LINES_PENDING": {
                    "value": {
                      "type": "error",
                      "message": "Your IPs are being prepared. Check again shortly.",
                      "payload": {
                        "code": "LINES_PENDING"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/PremiumIspForbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/PremiumIspConflict"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/PremiumIspUnavailable"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/public/premium-isp/orders/{orderId}/renewal": {
      "get": {
        "x-price-key": null,
        "x-pricing-note": "Prices come from the catalog (`GET /public/premium-isp/cities`, `GET /public/premium-isp/pools`) or from a quote, in USD, and are charged to the wallet balance. VAT on balance payments is 0%.",
        "x-rate-limit": "per-tier",
        "tags": [
          "Premium ISP"
        ],
        "operationId": "quotePremiumIspRenewal",
        "summary": "Quote a Premium ISP renewal",
        "description": "Price of renewing the plan for its own term with the same IPs, paid from the balance (VAT 0%). Paid IP swaps are not renewed; the carrier fee is, when the plan has a carrier (`carrierFeePerIp` and `carrierTotal` in the quote, included in `subtotal`). A City and carrier plan that can also renew for a longer length lists every length it can take in `options` (its own term first, then the longer ones), each with its per-IP price and totals; renew for one of them by sending its `days` to the POST. Without `options` the plan renews for its own term only. Free.",
        "parameters": [
          {
            "$ref": "#/components/parameters/PremiumIspOrderId"
          }
        ],
        "responses": {
          "200": {
            "description": "Renewal quote.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "days": {
                              "type": "integer"
                            },
                            "quantity": {
                              "type": "integer"
                            },
                            "perIpPrice": {
                              "type": "number"
                            },
                            "carrierFeePerIp": {
                              "type": "number",
                              "description": "Fee per IP of the pinned carrier, USD; 0 when the plan has no carrier."
                            },
                            "carrierTotal": {
                              "type": "number",
                              "description": "Carrier fee for all the IPs of the plan, USD, included in `subtotal`; charged at every renewal."
                            },
                            "subtotal": {
                              "type": "number"
                            },
                            "vatRate": {
                              "type": "number"
                            },
                            "vat": {
                              "type": "number"
                            },
                            "total": {
                              "type": "number"
                            },
                            "currency": {
                              "type": "string"
                            },
                            "currentExpiry": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "balance": {
                              "type": "number"
                            },
                            "sufficientBalance": {
                              "type": "boolean"
                            },
                            "options": {
                              "type": "array",
                              "description": "Only on a plan that can renew for more than its own term: one entry per length, shortest first.",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "days": {
                                    "type": "integer",
                                    "description": "Length of this renewal in days (1, 7, 30, 60 or 90)."
                                  },
                                  "perIpPrice": {
                                    "type": "number"
                                  },
                                  "subtotal": {
                                    "type": "number"
                                  },
                                  "vatRate": {
                                    "type": "number"
                                  },
                                  "vat": {
                                    "type": "number"
                                  },
                                  "total": {
                                    "type": "number"
                                  },
                                  "sufficientBalance": {
                                    "type": "boolean"
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Success",
                  "payload": {
                    "days": 30,
                    "quantity": 10,
                    "vatRate": 0,
                    "vat": 0,
                    "currency": "USD",
                    "paymentMethod": "BALANCE",
                    "currentExpiry": "2026-11-18T10:00:00.000Z",
                    "sufficientBalance": true,
                    "carrierFeePerIp": 0,
                    "carrierTotal": 0
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/PremiumIspForbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/PremiumIspConflict"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/PremiumIspUnavailable"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/renewal' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/renewal',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/renewal\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/renewal');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      },
      "post": {
        "x-price-key": null,
        "x-pricing-note": "Prices come from the catalog (`GET /public/premium-isp/cities`, `GET /public/premium-isp/pools`) or from a quote, in USD, and are charged to the wallet balance. VAT on balance payments is 0%.",
        "x-rate-limit": "per-tier",
        "tags": [
          "Premium ISP"
        ],
        "operationId": "renewPremiumIspOrder",
        "summary": "Renew a Premium ISP plan from the balance",
        "description": "Extends the plan by its own term with the same IPs and charges the balance (the carrier fee again, when the plan has a pinned carrier), or by `days` when the renewal quote lists that length in `options`. `Idempotency-Key` is required. 202 means the renewal is being verified: do not send it again, it completes or is refunded automatically. A `days` the plan cannot take is refused with 400 VALIDATION_ERROR before any charge. 20 renewals an hour per account.",
        "parameters": [
          {
            "$ref": "#/components/parameters/PremiumIspOrderId"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "200": {
            "description": "Renewed.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "renewed": {
                              "type": "boolean"
                            },
                            "daysAdded": {
                              "type": "integer"
                            },
                            "newExpiry": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "charged": {
                              "type": "number"
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Success",
                  "payload": {
                    "renewed": true,
                    "daysAdded": 30,
                    "newExpiry": "2026-12-18T10:00:00.000Z"
                  },
                  "pagination": {}
                }
              }
            }
          },
          "202": {
            "description": "Being verified: do not send it again.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "pending": {
                              "type": "boolean"
                            },
                            "days": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Your renewal is being verified. Do not send it again.",
                  "payload": {
                    "pending": true,
                    "days": 30
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PremiumIspPaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/PremiumIspForbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/PremiumIspConflict"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/PremiumIspUnavailable"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/renewal' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"days\":30}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/renewal',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\n        \"days\": 30\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/renewal\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"days\": 30\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/renewal');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'days' => 30\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "days": {
                    "type": "integer",
                    "description": "Optional. One of the `days` in the quote's `options`; without it, the plan's own term."
                  }
                }
              },
              "example": {
                "days": 30
              }
            }
          }
        }
      }
    },
    "/public/premium-isp/orders/{orderId}/replacements": {
      "get": {
        "x-price-key": null,
        "x-pricing-note": "Prices come from the catalog (`GET /public/premium-isp/cities`, `GET /public/premium-isp/pools`) or from a quote, in USD, and are charged to the wallet balance. VAT on balance payments is 0%.",
        "x-rate-limit": "per-tier",
        "tags": [
          "Premium ISP"
        ],
        "operationId": "getPremiumIspReplacements",
        "summary": "IP swaps of a city plan",
        "description": "Replacements bought with a city plan: used, being confirmed and left; the swaps bought after the purchase (`paid`) and the price of one more (`paidSwapPrice`, from the balance, no limit on the number). `offline` lists the plan's IPs that the network marks offline right now: `POST .../replacements` replaces each of them for free, without using a swap. Pools have no API replacements (their 24-hour replacement goes through support). Free.",
        "parameters": [
          {
            "$ref": "#/components/parameters/PremiumIspOrderId"
          }
        ],
        "responses": {
          "200": {
            "description": "IP swaps.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "bought": {
                              "type": "integer"
                            },
                            "used": {
                              "type": "integer"
                            },
                            "checking": {
                              "type": "integer"
                            },
                            "left": {
                              "type": "integer"
                            },
                            "paid": {
                              "type": "integer",
                              "description": "Swaps bought after the purchase (done or being confirmed)."
                            },
                            "paidSwapPrice": {
                              "type": [
                                "number",
                                "null"
                              ],
                              "description": "USD for one more swap from the balance, flat for the plan's type; `null` when this plan cannot buy one (older plans, expired plans)."
                            },
                            "offline": {
                              "type": "array",
                              "description": "The plan's IPs that the network marks offline right now. `POST .../replacements` replaces each of them for free. Empty when none, and always empty when `paidSwapPrice` is `null`.",
                              "items": {
                                "$ref": "#/components/schemas/PremiumIspOfflineIp"
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Success",
                  "payload": {
                    "bought": 2,
                    "used": 0,
                    "checking": 0,
                    "left": 2,
                    "paid": 0,
                    "paidSwapPrice": 1.5,
                    "offline": []
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/PremiumIspForbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/PremiumIspConflict"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/PremiumIspUnavailable"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/replacements' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/replacements',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/replacements\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/replacements');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      },
      "post": {
        "x-price-key": null,
        "x-pricing-note": "Prices come from the catalog (`GET /public/premium-isp/cities`, `GET /public/premium-isp/pools`) or from a quote, in USD, and are charged to the wallet balance. VAT on balance payments is 0%.",
        "x-rate-limit": "per-tier",
        "tags": [
          "Premium ISP"
        ],
        "operationId": "replacePremiumIspIp",
        "summary": "Replace one IP of a city plan",
        "description": "Swaps one IP of the plan for a new one in the same city, using one of the replacements bought with the plan. With none left, `pay: true` buys the swap from the balance at `paidSwapPrice` (0% VAT); without it nothing is charged and the 409 tells the price. 202 means the new IP is being prepared: it counts as used, do not send it again; a paid swap that never shows a new IP within 24 hours is refunded by itself. A 502 means nothing was used or charged. Offline IPs are replaced for free by auto-replace unless it was switched off (`.../auto-replace`). This call also replaces an IP that the network marks offline (listed in `offline` by `GET .../replacements`) for free: no swap is used, nothing is charged, `pay` is not needed and the answer carries `free: true`. If the IP is no longer offline when the request arrives, it is not replaced for free: the answer is 409 `REPLACEMENT_NOT_AVAILABLE` with nothing replaced, or the request is handled as a swap of a working IP as described above. Read `offline` right before the request and check `free` in the answer. A free replacement answered 202 that shows no new IP after about 10 minutes is released (nothing was used or charged) and can be sent again. When the city has no free IP to swap in, the answer is 409 `NO_STOCK_IN_CITY`: nothing was sent, used or charged (a paid swap is not charged), and the same request can be tried again later. 30 replacements an hour per account.",
        "parameters": [
          {
            "$ref": "#/components/parameters/PremiumIspOrderId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "ip"
                ],
                "properties": {
                  "ip": {
                    "type": "string",
                    "description": "One of the plan's exit IPs (`lines.ipAddresses`)."
                  },
                  "pay": {
                    "type": "boolean",
                    "default": false,
                    "description": "With no prepaid swap left: `true` buys this swap from the wallet balance at `paidSwapPrice` (plans that offer it). Left out or `false`, the answer is 409 `NO_REPLACEMENTS_LEFT` with the price and nothing is charged."
                  }
                }
              },
              "example": {
                "ip": "203.0.113.7",
                "pay": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Replaced. `free: true` when an offline IP was replaced for free.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "pending": {
                              "type": "boolean"
                            },
                            "free": {
                              "type": "boolean",
                              "description": "Present and `true` only when an offline IP was replaced for free: no swap was used and nothing was charged."
                            },
                            "oldIp": {
                              "type": "string"
                            },
                            "newIp": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "bought": {
                              "type": "integer"
                            },
                            "used": {
                              "type": "integer"
                            },
                            "checking": {
                              "type": "integer"
                            },
                            "left": {
                              "type": "integer"
                            },
                            "purchased": {
                              "type": "boolean",
                              "description": "`true` when this swap was bought now from the balance."
                            },
                            "paid": {
                              "type": "integer",
                              "description": "Swaps bought after the purchase (done or being confirmed)."
                            },
                            "charged": {
                              "type": "number",
                              "description": "USD taken from the balance for this swap (paid swaps only)."
                            },
                            "paidSwapPrice": {
                              "type": [
                                "number",
                                "null"
                              ]
                            },
                            "offline": {
                              "type": "array",
                              "description": "The plan's IPs that the network marks offline, as in `GET .../replacements`.",
                              "items": {
                                "$ref": "#/components/schemas/PremiumIspOfflineIp"
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "examples": {
                  "swap": {
                    "summary": "Prepaid swap used",
                    "value": {
                      "type": "response",
                      "message": "IP replaced.",
                      "payload": {
                        "pending": false,
                        "oldIp": "203.0.113.7",
                        "newIp": "203.0.113.42",
                        "bought": 2,
                        "used": 1,
                        "checking": 0,
                        "left": 1
                      },
                      "pagination": {}
                    }
                  },
                  "free": {
                    "summary": "Offline IP replaced for free",
                    "value": {
                      "type": "response",
                      "message": "IP replaced for free.",
                      "payload": {
                        "pending": false,
                        "free": true,
                        "oldIp": "203.0.113.7",
                        "newIp": "203.0.113.42",
                        "bought": 2,
                        "used": 0,
                        "checking": 0,
                        "left": 2
                      },
                      "pagination": {}
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "Being prepared: counts as used, do not send it again. A free replacement of an offline IP (`free: true`) uses no swap; if no new IP shows after about 10 minutes it is released and can be sent again.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Your new IP is being prepared. Do not replace this IP again.",
                  "payload": {
                    "pending": true,
                    "oldIp": "203.0.113.7",
                    "newIp": null,
                    "bought": 2,
                    "used": 0,
                    "checking": 1,
                    "left": 1
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PremiumIspPaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/PremiumIspForbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/PremiumIspConflict"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "502": {
            "description": "The IP could not be swapped right now. No swap was used.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "examples": {
                  "REPLACEMENT_REFUSED": {
                    "value": {
                      "type": "error",
                      "message": "The IP could not be swapped right now. No swap was used.",
                      "payload": {
                        "code": "REPLACEMENT_REFUSED"
                      }
                    }
                  }
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/PremiumIspUnavailable"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/replacements' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"ip\":\"203.0.113.7\",\"pay\":false}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/replacements',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\n        \"ip\": \"203.0.113.7\",\n        \"pay\": false\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/replacements\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"ip\": \"203.0.113.7\",\n    \"pay\": false\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/replacements');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'ip' => '203.0.113.7',\n    'pay' => false\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/public/premium-isp/orders/{orderId}/auto-replace": {
      "get": {
        "x-price-key": null,
        "x-pricing-note": "Prices come from the catalog (`GET /public/premium-isp/cities`, `GET /public/premium-isp/pools`) or from a quote, in USD, and are charged to the wallet balance. VAT on balance payments is 0%.",
        "x-rate-limit": "per-tier",
        "tags": [
          "Premium ISP"
        ],
        "operationId": "getPremiumIspAutoReplace",
        "summary": "Auto-replace setting of a city plan",
        "description": "Free auto-replace of a city plan: an IP that stays offline for more than 30 minutes is replaced by itself, same city, same login and password, and no paid swap is used. On by default; this reads its state for the plan's live IPs (`on`, `off`, or `mixed` while a change is half applied). Pools have no switch (`AUTO_REPLACE_NOT_AVAILABLE`): their carrier-removed IPs are replaced on their own. Free; 60 reads and changes an hour per account.",
        "parameters": [
          {
            "$ref": "#/components/parameters/PremiumIspOrderId"
          }
        ],
        "responses": {
          "200": {
            "description": "The setting.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "available": {
                              "type": "boolean",
                              "description": "`false` on a city plan delivered without the setting: nothing to switch."
                            },
                            "state": {
                              "type": "string",
                              "enum": [
                                "on",
                                "off",
                                "mixed",
                                "unknown"
                              ],
                              "description": "`mixed` while a change is half applied; read again in a minute."
                            },
                            "ips": {
                              "type": "integer",
                              "description": "Live IPs the setting applies to."
                            }
                          },
                          "required": [
                            "available"
                          ]
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Success",
                  "payload": {
                    "available": true,
                    "state": "on",
                    "ips": 5
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/PremiumIspForbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/PremiumIspConflict"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/PremiumIspUnavailable"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/auto-replace' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/auto-replace',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/auto-replace\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/auto-replace');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      },
      "post": {
        "x-price-key": null,
        "x-pricing-note": "Prices come from the catalog (`GET /public/premium-isp/cities`, `GET /public/premium-isp/pools`) or from a quote, in USD, and are charged to the wallet balance. VAT on balance payments is 0%.",
        "x-rate-limit": "per-tier",
        "tags": [
          "Premium ISP"
        ],
        "operationId": "setPremiumIspAutoReplace",
        "summary": "Switch auto-replace on or off",
        "description": "Switches free auto-replace on or off for every live IP of a city plan, the same switch as the plan page. Switch it off to keep an IP that goes offline and swap it yourself (`POST .../replacements`) or wait for it. The choice stays with the plan: an IP received through a paid swap follows it. The answer is the state after the change; `mixed` means the supplier applied it to some IPs only, read it again in a minute. Nothing is charged and no swap is used.",
        "parameters": [
          {
            "$ref": "#/components/parameters/PremiumIspOrderId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "enabled"
                ],
                "properties": {
                  "enabled": {
                    "type": "boolean",
                    "description": "`true` = replace offline IPs by itself; `false` = never replace an IP without a request."
                  }
                }
              },
              "example": {
                "enabled": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Changed.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "available": {
                              "type": "boolean",
                              "description": "`false` on a city plan delivered without the setting: nothing to switch."
                            },
                            "state": {
                              "type": "string",
                              "enum": [
                                "on",
                                "off",
                                "mixed",
                                "unknown"
                              ],
                              "description": "`mixed` while a change is half applied; read again in a minute."
                            },
                            "ips": {
                              "type": "integer",
                              "description": "Live IPs the setting applies to."
                            }
                          },
                          "required": [
                            "available"
                          ]
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Auto-replace switched off.",
                  "payload": {
                    "available": true,
                    "state": "off",
                    "ips": 5
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/PremiumIspForbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/PremiumIspConflict"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/PremiumIspUnavailable"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/auto-replace' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"enabled\":false}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/auto-replace',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\n        \"enabled\": false\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/auto-replace\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"enabled\": false\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/auto-replace');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'enabled' => false\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/public/ipv6/plans": {
      "get": {
        "x-price-key": null,
        "x-pricing-note": "Prices come from the grid (`GET /public/ipv6/plans`) or from a quote, in USD, and are charged to the wallet balance. VAT on balance payments is 0%. 1000 Mbps has no price: it is sold on request from the dashboard.",
        "x-rate-limit": "per-tier",
        "tags": [
          "IPv6"
        ],
        "operationId": "listIpv6SpeedPlans",
        "summary": "List IPv6 speed plans",
        "description": "The grid of IPv6 speed plans on sale: every speed (Mbps) with the terms (1, 7 or 30 days) sold for it and the price of each cell, in USD, paid from the balance with 0% VAT. Traffic is not metered for the whole term; the port speed is the cap. `from` is the cheapest cell; `onRequest` is the 1000 Mbps plan, sold without a listed price from the dashboard. Rotating or static sessions, HTTP and SOCKS5 and country selection work as on the per-GB IPv6 packs (those stay in `GET /public/plans`). Free (300 reads an hour per account).",
        "responses": {
          "200": {
            "description": "The grid.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/Ipv6SpeedPlanCatalog"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Success",
                  "payload": {
                    "currency": "USD",
                    "paymentMethod": "BALANCE",
                    "vatRate": 0,
                    "terms": [
                      1,
                      7,
                      30
                    ],
                    "speeds": [
                      {
                        "speedMbps": 30,
                        "terms": [
                          {
                            "days": 1,
                            "planName": "IPv6 Unlimited · 30 Mbps · 1 day"
                          },
                          {
                            "days": 7,
                            "planName": "IPv6 Unlimited · 30 Mbps · 7 days"
                          },
                          {
                            "days": 30,
                            "planName": "IPv6 Unlimited · 30 Mbps · 30 days"
                          }
                        ]
                      },
                      {
                        "speedMbps": 60,
                        "terms": [
                          {
                            "days": 1,
                            "planName": "IPv6 Unlimited · 60 Mbps · 1 day"
                          },
                          {
                            "days": 7,
                            "planName": "IPv6 Unlimited · 60 Mbps · 7 days"
                          },
                          {
                            "days": 30,
                            "planName": "IPv6 Unlimited · 60 Mbps · 30 days"
                          }
                        ]
                      },
                      {
                        "speedMbps": 120,
                        "terms": [
                          {
                            "days": 1,
                            "planName": "IPv6 Unlimited · 120 Mbps · 1 day"
                          },
                          {
                            "days": 7,
                            "planName": "IPv6 Unlimited · 120 Mbps · 7 days"
                          },
                          {
                            "days": 30,
                            "planName": "IPv6 Unlimited · 120 Mbps · 30 days"
                          }
                        ]
                      },
                      {
                        "speedMbps": 200,
                        "terms": [
                          {
                            "days": 1,
                            "planName": "IPv6 Unlimited · 200 Mbps · 1 day"
                          },
                          {
                            "days": 7,
                            "planName": "IPv6 Unlimited · 200 Mbps · 7 days"
                          },
                          {
                            "days": 30,
                            "planName": "IPv6 Unlimited · 200 Mbps · 30 days"
                          }
                        ]
                      }
                    ],
                    "from": {
                      "speedMbps": 30,
                      "days": 1
                    },
                    "onRequest": {
                      "speedMbps": 1000,
                      "price": null,
                      "availability": "contact",
                      "how": "Ask for it in the dashboard: Plans → IPv6 → 1000 Mbps → Contact us. We reply by e-mail with the price."
                    }
                  },
                  "pagination": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Ipv6Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/Ipv6Unavailable"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/public/ipv6/plans' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/public/ipv6/plans',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/ipv6/plans\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/ipv6/plans');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/public/ipv6/quote": {
      "post": {
        "x-price-key": null,
        "x-pricing-note": "Prices come from the grid (`GET /public/ipv6/plans`) or from a quote, in USD, and are charged to the wallet balance. VAT on balance payments is 0%. 1000 Mbps has no price: it is sold on request from the dashboard.",
        "x-rate-limit": "per-tier",
        "tags": [
          "IPv6"
        ],
        "operationId": "quoteIpv6SpeedPlan",
        "summary": "Quote an IPv6 speed plan",
        "description": "Server-side price of one speed × term cell paid from the balance, with VAT (0% on balance) and whether your balance covers it. Nothing is reserved: the purchase reads the grid again before charging. A speed or term that is not sold answers 409 with the cells that are; 1000 Mbps answers `CONTACT_REQUIRED`. Free (300 quotes an hour per account).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Ipv6Selection"
              },
              "example": {
                "speedMbps": 200,
                "days": 7
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Quote.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/Ipv6Quote"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Success",
                  "payload": {
                    "speedMbps": 200,
                    "days": 7,
                    "planName": "IPv6 Unlimited · 200 Mbps · 7 days",
                    "trafficMetered": false,
                    "vatRate": 0,
                    "vat": 0,
                    "currency": "USD",
                    "paymentMethod": "BALANCE",
                    "sufficientBalance": true,
                    "reserved": false,
                    "quotedAt": "2026-10-20T09:00:00.000Z"
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Ipv6Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Ipv6Conflict"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/Ipv6Unavailable"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/public/ipv6/quote' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"speedMbps\":200,\"days\":7}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/public/ipv6/quote',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\n        \"speedMbps\": 200,\n        \"days\": 7\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/ipv6/quote\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"speedMbps\": 200,\n    \"days\": 7\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/ipv6/quote');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'speedMbps' => 200,\n    'days' => 7\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/public/ipv6/orders": {
      "get": {
        "x-price-key": null,
        "x-pricing-note": "Prices come from the grid (`GET /public/ipv6/plans`) or from a quote, in USD, and are charged to the wallet balance. VAT on balance payments is 0%. 1000 Mbps has no price: it is sold on request from the dashboard.",
        "x-rate-limit": "per-tier",
        "tags": [
          "IPv6"
        ],
        "operationId": "listIpv6Orders",
        "summary": "List IPv6 speed orders",
        "description": "Status of the account's IPv6 speed orders, newest first, from our records only: dashboard and API purchases alike (`channel`). Per-GB IPv6 packs are not here: they are plans in `GET /public/proxies`. Free (120 reads an hour per account).",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Orders.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "orders": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/Ipv6Order"
                              }
                            },
                            "pagination": {
                              "type": "object",
                              "properties": {
                                "total": {
                                  "type": "integer"
                                },
                                "limit": {
                                  "type": "integer"
                                },
                                "offset": {
                                  "type": "integer"
                                },
                                "hasMore": {
                                  "type": "boolean"
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Success",
                  "payload": {
                    "orders": [
                      {
                        "id": "ord_7a1c",
                        "product": "ipv6-speed",
                        "status": "active",
                        "createdAt": "2026-10-20T09:00:00.000Z",
                        "speedMbps": 200,
                        "days": 7,
                        "planName": "IPv6 Unlimited · 200 Mbps · 7 days",
                        "trafficMetered": false,
                        "expiresAt": "2026-10-27T09:00:00.000Z",
                        "daysRemaining": 7,
                        "channel": "api",
                        "invoice": {
                          "id": "inv_3b9e",
                          "vat": 0,
                          "vatRate": 0,
                          "paid": true,
                          "status": "PAID",
                          "refunded": false
                        }
                      }
                    ],
                    "pagination": {
                      "total": 1,
                      "limit": 50,
                      "offset": 0,
                      "hasMore": false
                    }
                  },
                  "pagination": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Ipv6Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/Ipv6Unavailable"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/public/ipv6/orders' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/public/ipv6/orders',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/ipv6/orders\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/ipv6/orders');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      },
      "post": {
        "x-price-key": null,
        "x-pricing-note": "Prices come from the grid (`GET /public/ipv6/plans`) or from a quote, in USD, and are charged to the wallet balance. VAT on balance payments is 0%. 1000 Mbps has no price: it is sold on request from the dashboard.",
        "x-rate-limit": "per-tier",
        "tags": [
          "IPv6"
        ],
        "operationId": "createIpv6Order",
        "summary": "Buy an IPv6 speed plan",
        "description": "Buy one speed × term cell from the wallet balance. Send a unique `Idempotency-Key` with every purchase: the same key again answers with the order already created, never a second charge. The grid is read again at purchase time; `maxTotal` lets you refuse a price above what you quoted (409 `PRICE_CHANGED`, nothing charged). Answers: 201 delivered (the plan is active; generate the endpoint strings with `POST /public/proxies/generate` and the order id), 200 replayed for a key already paid, 422 not delivered and refunded to the balance. Keyless and pay-per-call access cannot buy; keys created by a connected app cannot spend. 20 purchases an hour per account.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Ipv6Selection"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "maxTotal": {
                        "type": "number",
                        "description": "Refuse the purchase if the total is above this amount (USD). Nothing is charged then."
                      },
                      "idempotencyKey": {
                        "type": "string",
                        "pattern": "^[a-zA-Z0-9-]{16,128}$",
                        "description": "Alternative to the header."
                      }
                    }
                  }
                ]
              },
              "example": {
                "speedMbps": 200,
                "days": 7,
                "maxTotal": 150
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Replayed: this Idempotency-Key was already paid. The order it created, no new charge.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "replayed": {
                              "type": "boolean",
                              "const": true
                            },
                            "order": {
                              "$ref": "#/components/schemas/Ipv6Order"
                            },
                            "invoice": {
                              "type": "object"
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "This purchase was already received.",
                  "payload": {
                    "replayed": true,
                    "order": {
                      "id": "ord_7a1c",
                      "product": "ipv6-speed",
                      "status": "active",
                      "createdAt": "2026-10-20T09:00:00.000Z",
                      "speedMbps": 200,
                      "days": 7,
                      "planName": "IPv6 Unlimited · 200 Mbps · 7 days",
                      "trafficMetered": false,
                      "expiresAt": "2026-10-27T09:00:00.000Z",
                      "daysRemaining": 7,
                      "channel": "api",
                      "invoice": {
                        "id": "inv_3b9e",
                        "vat": 0,
                        "vatRate": 0,
                        "paid": true,
                        "status": "PAID",
                        "refunded": false
                      }
                    }
                  },
                  "pagination": {}
                }
              }
            }
          },
          "201": {
            "description": "Delivered: the plan is active.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "order": {
                              "$ref": "#/components/schemas/Ipv6Order"
                            },
                            "invoice": {
                              "type": "object"
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Success",
                  "payload": {
                    "order": {
                      "id": "ord_7a1c",
                      "product": "ipv6-speed",
                      "status": "active",
                      "createdAt": "2026-10-20T09:00:00.000Z",
                      "speedMbps": 200,
                      "days": 7,
                      "planName": "IPv6 Unlimited · 200 Mbps · 7 days",
                      "trafficMetered": false,
                      "expiresAt": "2026-10-27T09:00:00.000Z",
                      "daysRemaining": 7,
                      "channel": "api",
                      "invoice": {
                        "id": "inv_3b9e",
                        "vat": 0,
                        "vatRate": 0,
                        "paid": true,
                        "status": "PAID",
                        "refunded": false
                      }
                    },
                    "invoice": {
                      "id": "inv_3b9e",
                      "vat": 0,
                      "vatRate": 0,
                      "paid": true
                    }
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/Ipv6PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Ipv6Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Ipv6Conflict"
          },
          "422": {
            "$ref": "#/components/responses/Ipv6NotDelivered"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/Ipv6Unavailable"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/public/ipv6/orders' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"speedMbps\":200,\"days\":7,\"maxTotal\":150}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/public/ipv6/orders',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\n        \"speedMbps\": 200,\n        \"days\": 7,\n        \"maxTotal\": 150\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/ipv6/orders\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"speedMbps\": 200,\n    \"days\": 7,\n    \"maxTotal\": 150\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/ipv6/orders');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'speedMbps' => 200,\n    'days' => 7,\n    'maxTotal' => 150\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/public/ipv6/orders/{orderId}": {
      "get": {
        "x-price-key": null,
        "x-pricing-note": "Prices come from the grid (`GET /public/ipv6/plans`) or from a quote, in USD, and are charged to the wallet balance. VAT on balance payments is 0%. 1000 Mbps has no price: it is sold on request from the dashboard.",
        "x-rate-limit": "per-tier",
        "tags": [
          "IPv6"
        ],
        "operationId": "getIpv6Order",
        "summary": "Get an IPv6 speed order",
        "description": "One IPv6 speed order of this account: status, speed, term, expiry and invoice, from our records. The endpoint strings come from `POST /public/proxies/generate` with this order id (rotating, sticky or static sessions, country selection). 404 for an order of another account or of another product. Free (120 reads an hour per account).",
        "parameters": [
          {
            "$ref": "#/components/parameters/Ipv6OrderId"
          }
        ],
        "responses": {
          "200": {
            "description": "The order.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "order": {
                              "$ref": "#/components/schemas/Ipv6Order"
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Success",
                  "payload": {
                    "order": {
                      "id": "ord_7a1c",
                      "product": "ipv6-speed",
                      "status": "active",
                      "createdAt": "2026-10-20T09:00:00.000Z",
                      "speedMbps": 200,
                      "days": 7,
                      "planName": "IPv6 Unlimited · 200 Mbps · 7 days",
                      "trafficMetered": false,
                      "expiresAt": "2026-10-27T09:00:00.000Z",
                      "daysRemaining": 7,
                      "channel": "api",
                      "invoice": {
                        "id": "inv_3b9e",
                        "vat": 0,
                        "vatRate": 0,
                        "paid": true,
                        "status": "PAID",
                        "refunded": false
                      }
                    }
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Ipv6Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/Ipv6Unavailable"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/public/ipv6/orders/ORDERID' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/public/ipv6/orders/ORDERID',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/ipv6/orders/ORDERID\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/ipv6/orders/ORDERID');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/public/plans": {
      "get": {
        "operationId": "listPlans",
        "tags": [
          "Plans & orders"
        ],
        "summary": "List the plans you can buy",
        "description": "Active plans with their size, duration and list price (`amount`, USD), cheapest first, also grouped by `planType` in `groupedPlans`. `planTypes` describes every plan type the API knows, including types that have no plan on sale. Use a plan's `id` as `planId` in `POST /public/purchase`. Products you configure at checkout (ISP proxies, unlimited-bandwidth plans) are not listed: they are bought in the dashboard, Premium ISP through its own endpoints. Free.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "parameters": [
          {
            "name": "planType",
            "in": "query",
            "description": "Only plans of this type. An unknown value returns an empty list.",
            "schema": {
              "type": "string",
              "enum": [
                "residentialbasic",
                "residentialpremium",
                "resiprivate",
                "isp",
                "isppremium",
                "datacenter",
                "datacentertraffic",
                "ipv6",
                "mobile",
                "mobile_v2"
              ]
            },
            "example": "residentialpremium"
          }
        ],
        "responses": {
          "200": {
            "description": "Plans on sale.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "plans": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/Plan"
                              }
                            },
                            "groupedPlans": {
                              "type": "object",
                              "description": "The same plans keyed by `planType`.",
                              "additionalProperties": {
                                "type": "array",
                                "items": {
                                  "$ref": "#/components/schemas/Plan"
                                }
                              }
                            },
                            "planTypes": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/PlanTypeInfo"
                              }
                            },
                            "total": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "success",
                  "payload": {
                    "plans": [
                      {
                        "id": "pln_3e7a",
                        "name": "Residential - Quark (5GB)",
                        "planType": "residentialpremium",
                        "planTypeName": "Residential Premium",
                        "bandwidth": 5,
                        "bandwidthGB": 5,
                        "isUnlimited": false,
                        "duration": 90,
                        "durationDays": 90,
                        "ips": 0,
                        "whitelistSlots": 0,
                        "region": "Global",
                        "speed": 0,
                        "highConcurrency": false,
                        "highPriority": false
                      }
                    ],
                    "groupedPlans": {
                      "residentialpremium": [
                        {
                          "id": "pln_3e7a",
                          "name": "Residential - Quark (5GB)",
                          "planType": "residentialpremium",
                          "planTypeName": "Residential Premium",
                          "bandwidth": 5,
                          "bandwidthGB": 5,
                          "isUnlimited": false,
                          "duration": 90,
                          "durationDays": 90,
                          "ips": 0,
                          "whitelistSlots": 0,
                          "region": "Global",
                          "speed": 0,
                          "highConcurrency": false,
                          "highPriority": false
                        }
                      ]
                    },
                    "planTypes": [
                      {
                        "key": "residentialpremium",
                        "name": "Residential Premium",
                        "description": "Residential premium proxies - Premium quality with high success rate",
                        "features": [
                          "Premium residential IPs",
                          "Higher success rate",
                          "Fast speeds",
                          "Geo-targeting available"
                        ]
                      }
                    ],
                    "total": 1
                  },
                  "pagination": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "description": "Unexpected error; retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "Internal server error"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/public/plans?planType=residentialpremium' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/public/plans?planType=residentialpremium',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/plans?planType=residentialpremium\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/plans?planType=residentialpremium');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/public/purchase": {
      "post": {
        "operationId": "purchasePlan",
        "tags": [
          "Plans & orders"
        ],
        "summary": "Buy a plan from the balance",
        "description": "Buys one plan from `GET /public/plans`, charges the wallet balance (0% VAT) and activates the plan in the same call. The answer carries the order, the invoice and the plan's credentials; pass `order.id` as `orderId` to `POST /public/proxies/generate`. The balance is checked before anything is created: a balance that does not cover the total answers 400 `Insufficient balance` and nothing is charged. If the plan cannot be activated after the charge, the amount goes back to the balance and the call answers 422 `NOT_DELIVERED_REFUNDED`: you have not been charged and can buy again. There is no idempotency key on this endpoint: do not resend a purchase that timed out, read `GET /public/orders` first. A coupon is valid once per account, on the brand that issued it. A payment that fails leaves an unpaid invoice; ten unpaid invoices in 24 hours block new purchases (429 `TOO_MANY_UNPAID_INVOICES`). Unknown body fields are refused. Requires your own API key.",
        "x-price-key": null,
        "x-pricing-note": "The call itself is free; the plan costs its `amount` from `GET /public/plans` (less the coupon, if any), charged to the wallet balance in USD with 0% VAT.",
        "x-rate-limit": "per-tier",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "planId"
                ],
                "additionalProperties": false,
                "properties": {
                  "planId": {
                    "type": "string",
                    "description": "`id` of a plan from `GET /public/plans`."
                  },
                  "coupon": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Coupon code (optional; empty string or null = none)."
                  }
                }
              },
              "example": {
                "planId": "pln_3e7a"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Paid and active. Credentials in `payload.proxy`.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "order": {
                              "type": "object",
                              "properties": {
                                "id": {
                                  "type": "string",
                                  "description": "The `orderId` for generate and whitelist."
                                },
                                "planId": {
                                  "type": "string"
                                },
                                "planName": {
                                  "type": "string"
                                },
                                "createdAt": {
                                  "type": "string",
                                  "format": "date-time"
                                }
                              }
                            },
                            "invoice": {
                              "type": "object",
                              "properties": {
                                "id": {
                                  "type": "string"
                                },
                                "subtotal": {
                                  "type": "number",
                                  "description": "Plan price, USD."
                                },
                                "discount": {
                                  "type": "number",
                                  "description": "Coupon discount, USD."
                                },
                                "vat": {
                                  "type": "number",
                                  "description": "0 on balance payments."
                                },
                                "total": {
                                  "type": "number",
                                  "description": "Amount charged to the balance, USD."
                                },
                                "status": {
                                  "type": "string",
                                  "const": "PAID"
                                },
                                "paid": {
                                  "type": "boolean",
                                  "const": true
                                }
                              }
                            },
                            "proxy": {
                              "$ref": "#/components/schemas/PurchasedProxy"
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "success",
                  "payload": {
                    "order": {
                      "id": "ord_8c21",
                      "planId": "pln_3e7a",
                      "planName": "Residential - Quark (5GB)",
                      "createdAt": "2026-10-19T10:00:00.000Z"
                    },
                    "invoice": {
                      "id": "inv_4b90",
                      "vat": 0,
                      "status": "PAID",
                      "paid": true
                    },
                    "proxy": {
                      "id": "prx_1",
                      "orderId": "ord_8c21",
                      "username": "user_8c21",
                      "password": "p4ssw0rd",
                      "proxyType": "RESIDENTIAL",
                      "region": "",
                      "bandwidth": 5,
                      "bandwidthLeft": 5,
                      "noOfIps": 0,
                      "noOfWhitelistedIps": 1,
                      "speed": 0,
                      "autoRenewDays": 90,
                      "highConcurrency": false,
                      "highPriority": false,
                      "autoRenew": false,
                      "expiry": "2027-01-17T10:00:00.000Z",
                      "autoRenewLastAt": null,
                      "gbReclaimedAt": null,
                      "createdAt": "2026-10-19T10:00:00.000Z",
                      "updatedAt": "2026-10-19T10:00:00.000Z",
                      "whitelist_ip": []
                    }
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "description": "Nothing was charged: invalid body (including a body that is not JSON), trial-only plan, invalid coupon, total below the minimum purchase, balance too low, balance payments switched off, or a payment that could not be confirmed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "examples": {
                  "validation": {
                    "value": {
                      "type": "error",
                      "message": "validation error",
                      "payload": [
                        {
                          "message": "\"planId\" is required",
                          "path": [
                            "planId"
                          ],
                          "type": "any.required",
                          "context": {
                            "label": "planId",
                            "key": "planId"
                          }
                        }
                      ]
                    }
                  },
                  "body_not_json": {
                    "value": {
                      "type": "error",
                      "message": "validation error",
                      "payload": [
                        {
                          "message": "\"value\" must be of type object",
                          "path": [],
                          "type": "object.base",
                          "context": {
                            "type": "object",
                            "label": "value",
                            "value": null
                          }
                        }
                      ]
                    }
                  },
                  "insufficient_balance": {
                    "value": {
                      "type": "error",
                      "message": "Insufficient balance"
                    }
                  },
                  "trial_only": {
                    "value": {
                      "type": "error",
                      "message": "This plan is only available for free trials"
                    }
                  },
                  "coupon": {
                    "value": {
                      "type": "error",
                      "message": "This coupon is no longer valid"
                    }
                  },
                  "minimum": {
                    "value": {
                      "type": "error",
                      "message": "Minimum purchase amount is $1.00. Your cart total is $0.50.",
                      "payload": {
                        "minAmount": 1,
                        "currentAmount": 0.5
                      }
                    }
                  },
                  "PAYMENT_METHOD_UNAVAILABLE": {
                    "value": {
                      "type": "error",
                      "message": "This payment method is not available right now. Please choose another one.",
                      "payload": {
                        "code": "PAYMENT_METHOD_UNAVAILABLE",
                        "method": "BALANCE"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Purchases need your own API key: keyless and pay-per-call access cannot spend a balance.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "examples": {
                  "KEY_REQUIRED": {
                    "value": {
                      "type": "error",
                      "message": "Purchases need your own API key. Create one in the dashboard under API keys.",
                      "payload": {
                        "code": "KEY_REQUIRED"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No active plan with this `planId`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "Plan not found or inactive"
                }
              }
            }
          },
          "409": {
            "description": "The plan was not activated and the automatic refund could not be confirmed. Do not buy again: contact support with the order and invoice ids.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "examples": {
                  "PAYMENT_UNDER_REVIEW": {
                    "value": {
                      "type": "error",
                      "message": "Proxy activation failed and the automatic refund could not be confirmed. Please contact support before purchasing again.",
                      "payload": {
                        "code": "PAYMENT_UNDER_REVIEW",
                        "orderId": "ord_8c21",
                        "invoiceId": "inv_4b90"
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "The plan could not be activated and the amount is back on your balance: you have not been charged. You can buy again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "examples": {
                  "NOT_DELIVERED_REFUNDED": {
                    "value": {
                      "type": "error",
                      "message": "Proxy activation failed. You have not been charged — please try again or contact support.",
                      "payload": {
                        "code": "NOT_DELIVERED_REFUNDED",
                        "refunded": true,
                        "orderId": "ord_8c21",
                        "invoiceId": "inv_4b90"
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Ten or more unpaid invoices in the last 24 hours (`TOO_MANY_UNPAID_INVOICES`: pay or cancel one, or contact support), or the key rate limit (see TooManyRequests).",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "examples": {
                  "TOO_MANY_UNPAID_INVOICES": {
                    "value": {
                      "type": "error",
                      "message": "You have too many unpaid invoices. Please pay at least one invoice or contact customer support to continue.",
                      "payload": {
                        "code": "TOO_MANY_UNPAID_INVOICES",
                        "count": 10
                      }
                    }
                  },
                  "key_window": {
                    "value": {
                      "type": "error",
                      "message": "Rate limit exceeded. Resets in 23 minutes.",
                      "payload": {
                        "rateLimit": 1200,
                        "requestCount": 1200,
                        "resetAt": "2026-10-19T11:00:00.000Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Unexpected error. Check `GET /public/orders` before buying again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "Internal server error"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/public/purchase' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"planId\":\"pln_3e7a\"}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/public/purchase',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\n        \"planId\": \"pln_3e7a\"\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/purchase\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"planId\": \"pln_3e7a\"\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/purchase');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'planId' => 'pln_3e7a'\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/public/orders": {
      "get": {
        "operationId": "listOrders",
        "tags": [
          "Plans & orders"
        ],
        "summary": "List your orders",
        "description": "Every order of the account, newest first, with the plan, the proxy credentials and the invoices: use it to find an order after a purchase that timed out, to check what was charged, or to get the `orderId` of an older plan. For the live state of a plan (bandwidth used, days left) use `GET /public/proxies`. Plans disabled by support are not listed. Free.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          },
          {
            "name": "type",
            "in": "query",
            "description": "Only proxy plans (`PROXY`) or balance top-ups (`TOPUP`); omit for every order.",
            "schema": {
              "type": "string",
              "enum": [
                "PROXY",
                "TOPUP"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Orders.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "orders": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/Order"
                              }
                            },
                            "pagination": {
                              "type": "object",
                              "properties": {
                                "total": {
                                  "type": "integer"
                                },
                                "limit": {
                                  "type": "integer"
                                },
                                "offset": {
                                  "type": "integer"
                                },
                                "hasMore": {
                                  "type": "boolean"
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "success",
                  "payload": {
                    "orders": [
                      {
                        "id": "ord_8c21",
                        "type": "PROXY",
                        "createdAt": "2026-10-19T10:00:00.000Z",
                        "plan": {
                          "id": "pln_3e7a",
                          "name": "Residential - Quark (5GB)",
                          "planType": "residentialpremium",
                          "planTypeName": "Residential Premium",
                          "bandwidth": 5,
                          "bandwidthGB": 5,
                          "duration": 90,
                          "ips": 0,
                          "region": "Global"
                        },
                        "proxy": {
                          "id": "prx_1",
                          "username": "user_8c21",
                          "password": "p4ssw0rd",
                          "planType": "residentialpremium",
                          "planTypeName": "Residential Premium",
                          "bandwidth": 5,
                          "bandwidthGB": 5,
                          "bandwidthLeft": 3.2,
                          "bandwidthLeftGB": 3.2,
                          "isUnlimited": false,
                          "expiry": "2027-01-17T10:00:00.000Z",
                          "isActive": true,
                          "ips": 0,
                          "whitelistedIPs": [],
                          "region": "Global"
                        },
                        "invoices": [
                          {
                            "id": "inv_4b90",
                            "status": "PAID",
                            "paid": true,
                            "paidAt": "2026-10-19T10:00:01.000Z",
                            "createdAt": "2026-10-19T10:00:00.000Z"
                          }
                        ]
                      }
                    ],
                    "pagination": {
                      "total": 1,
                      "limit": 50,
                      "offset": 0,
                      "hasMore": false
                    }
                  },
                  "pagination": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "description": "Unexpected error (also a non-numeric `limit` or `offset`); retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "Internal server error"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/public/orders' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/public/orders',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/orders\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/orders');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/public/balance": {
      "get": {
        "operationId": "getBalance",
        "tags": [
          "Plans & orders"
        ],
        "summary": "Get the wallet balance",
        "description": "The wallet balance in USD, the one `POST /public/purchase` and the Data API draw from, and the total spent on proxy plans. Read it before a purchase: a balance below the plan's `amount` answers 400 `Insufficient balance`. Top-ups are made in the dashboard. Free.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "responses": {
          "200": {
            "description": "Balance.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/Balance"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "success",
                  "payload": {
                    "balance": 42.5,
                    "balanceUSD": 42.5,
                    "totalSpent": 120,
                    "totalSpentUSD": 120
                  },
                  "pagination": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "description": "Unexpected error; retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "Internal server error"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/public/balance' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/public/balance',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/balance\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/balance');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/public/geo/countries": {
      "get": {
        "operationId": "listGeoCountries",
        "tags": [
          "Proxy locations"
        ],
        "summary": "List countries for a plan type",
        "description": "Countries you can target with a plan type; send `code` as `country` to `POST /public/proxies/generate`. Residential Basic and traffic-based Datacenter return the live list of the network when the account has one of these plans, otherwise the general country list. Residential Premium and Mobile read the live tree, which also lists countries we added after testing them on our gateways (for example Guam, Puerto Rico, Kosovo and Jersey on Residential Premium; Montenegro and New Caledonia on Mobile): they take country targeting, and a region, city or ISP only where `GET /public/geo/states` or the tree lists one. IPv6 returns its own list, including `mix` (any country). ISP, Premium ISP and static-gateway Datacenter plans have their location fixed at purchase: for them this is the general country list, not a targeting option. Free.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "parameters": [
          {
            "name": "planType",
            "in": "query",
            "required": true,
            "description": "Plan type whose countries you want.",
            "schema": {
              "type": "string",
              "enum": [
                "residentialbasic",
                "residentialpremium",
                "resiprivate",
                "isp",
                "isppremium",
                "datacenter",
                "datacentertraffic",
                "ipv6",
                "mobile",
                "mobile_v2"
              ]
            },
            "example": "residentialbasic"
          }
        ],
        "responses": {
          "200": {
            "description": "Countries.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "countries": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/GeoCountry"
                              }
                            },
                            "planType": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "success",
                  "payload": {
                    "countries": [
                      {
                        "code": "us",
                        "name": "United States"
                      },
                      {
                        "code": "de",
                        "name": "Germany"
                      }
                    ],
                    "planType": "residentialbasic"
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "description": "Missing or unknown query parameter.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "examples": {
                  "planType_missing": {
                    "value": {
                      "type": "error",
                      "message": "planType query parameter is required"
                    }
                  },
                  "planType_invalid": {
                    "value": {
                      "type": "error",
                      "message": "Invalid planType"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "description": "The countries could not be read right now; retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "Failed to fetch countries. Please try again later."
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/public/geo/countries?planType=residentialbasic' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/public/geo/countries?planType=residentialbasic',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/geo/countries?planType=residentialbasic\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/geo/countries?planType=residentialbasic');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/public/geo/states": {
      "get": {
        "operationId": "listGeoStates",
        "tags": [
          "Proxy locations"
        ],
        "summary": "List states or regions of a country",
        "description": "States or regions of one country for a plan type; send `code` as `state` (alias `region`) to `POST /public/proxies/generate`. Available for Residential Basic and traffic-based Datacenter (live list, needs one of these plans on the account), Residential Premium and Mobile. Other plan types answer an empty list. For Residential Premium and Mobile V2 the targeting options return every level in one call. Free.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "parameters": [
          {
            "name": "planType",
            "in": "query",
            "required": true,
            "description": "Plan type.",
            "schema": {
              "type": "string",
              "enum": [
                "residentialbasic",
                "residentialpremium",
                "resiprivate",
                "isp",
                "isppremium",
                "datacenter",
                "datacentertraffic",
                "ipv6",
                "mobile",
                "mobile_v2"
              ]
            },
            "example": "residentialpremium"
          },
          {
            "name": "country",
            "in": "query",
            "required": true,
            "description": "Country code, either case.",
            "schema": {
              "type": "string"
            },
            "example": "AL"
          }
        ],
        "responses": {
          "200": {
            "description": "States.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "states": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/GeoState"
                              }
                            },
                            "country": {
                              "type": "string",
                              "description": "Upper case."
                            },
                            "planType": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "success",
                  "payload": {
                    "states": [
                      {
                        "code": "durres",
                        "state_code": "durres",
                        "name": "Durres",
                        "state": "Durres"
                      }
                    ],
                    "country": "AL",
                    "planType": "residentialpremium"
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "description": "Missing or unknown query parameter.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "examples": {
                  "planType_missing": {
                    "value": {
                      "type": "error",
                      "message": "planType query parameter is required"
                    }
                  },
                  "planType_invalid": {
                    "value": {
                      "type": "error",
                      "message": "Invalid planType"
                    }
                  },
                  "country_missing": {
                    "value": {
                      "type": "error",
                      "message": "country query parameter is required"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Residential Basic / traffic-based Datacenter: the account has no plan of these types, so there is no location list to read.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "No active proxy plan found. Purchase a residential basic or datacenter traffic plan to use geo-targeting."
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "description": "The states could not be read right now; retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "Failed to fetch states. Please try again later."
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/public/geo/states?planType=residentialpremium&country=AL' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/public/geo/states?planType=residentialpremium&country=AL',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/geo/states?planType=residentialpremium&country=AL\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/geo/states?planType=residentialpremium&country=AL');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/public/geo/cities": {
      "get": {
        "operationId": "listGeoCities",
        "tags": [
          "Proxy locations"
        ],
        "summary": "List cities of a country or state",
        "description": "Cities of one country, optionally narrowed to a state, for a plan type; send the city as `city` to `POST /public/proxies/generate` (see `GeoCity` for which field). Residential Premium lists cities per state: pass `state`, or the list is empty. Residential Basic and traffic-based Datacenter need one of these plans on the account. Other plan types answer an empty list. Free.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "parameters": [
          {
            "name": "planType",
            "in": "query",
            "required": true,
            "description": "Plan type.",
            "schema": {
              "type": "string",
              "enum": [
                "residentialbasic",
                "residentialpremium",
                "resiprivate",
                "isp",
                "isppremium",
                "datacenter",
                "datacentertraffic",
                "ipv6",
                "mobile",
                "mobile_v2"
              ]
            },
            "example": "residentialpremium"
          },
          {
            "name": "country",
            "in": "query",
            "required": true,
            "description": "Country code, either case.",
            "schema": {
              "type": "string"
            },
            "example": "AL"
          },
          {
            "name": "state",
            "in": "query",
            "description": "State `code` from `GET /public/geo/states` (Residential Basic also accepts the name).",
            "schema": {
              "type": "string"
            },
            "example": "durres"
          }
        ],
        "responses": {
          "200": {
            "description": "Cities.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "cities": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/GeoCity"
                              }
                            },
                            "country": {
                              "type": "string",
                              "description": "Upper case."
                            },
                            "state": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "planType": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "success",
                  "payload": {
                    "cities": [
                      {
                        "code": "durres",
                        "name": "Durres"
                      }
                    ],
                    "country": "AL",
                    "state": "durres",
                    "planType": "residentialpremium"
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "description": "Missing or unknown query parameter.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "examples": {
                  "planType_missing": {
                    "value": {
                      "type": "error",
                      "message": "planType query parameter is required"
                    }
                  },
                  "planType_invalid": {
                    "value": {
                      "type": "error",
                      "message": "Invalid planType"
                    }
                  },
                  "country_missing": {
                    "value": {
                      "type": "error",
                      "message": "country query parameter is required"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Residential Basic / traffic-based Datacenter: the account has no plan of these types, so there is no location list to read.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "No active proxy plan found. Purchase a residential basic or datacenter traffic plan to use geo-targeting."
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "description": "The cities could not be read right now; retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "Failed to fetch cities. Please try again later."
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/public/geo/cities?planType=residentialpremium&country=AL&state=durres' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/public/geo/cities?planType=residentialpremium&country=AL&state=durres',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/geo/cities?planType=residentialpremium&country=AL&state=durres\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/geo/cities?planType=residentialpremium&country=AL&state=durres');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/public/geo/asns": {
      "get": {
        "operationId": "listGeoAsns",
        "tags": [
          "Proxy locations"
        ],
        "summary": "List ASNs for Residential Basic and Datacenter",
        "description": "Networks (autonomous systems) you can target with Residential Basic and traffic-based Datacenter plans, for one country or all of them; send `asn` as `asn` to `POST /public/proxies/generate` together with a `country` (ASN targeting needs a country). Needs one of these plans on the account. Other plan types answer 400. Free.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "parameters": [
          {
            "name": "planType",
            "in": "query",
            "required": true,
            "description": "`residentialbasic` or `datacentertraffic`.",
            "schema": {
              "type": "string",
              "enum": [
                "residentialbasic",
                "residentialpremium",
                "resiprivate",
                "isp",
                "isppremium",
                "datacenter",
                "datacentertraffic",
                "ipv6",
                "mobile",
                "mobile_v2"
              ]
            },
            "example": "residentialbasic"
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "description": "Country code; omit for every country.",
            "schema": {
              "type": "string"
            },
            "example": "US"
          }
        ],
        "responses": {
          "200": {
            "description": "ASNs.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "asns": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/GeoAsn"
                              }
                            },
                            "country": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "planType": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "success",
                  "payload": {
                    "asns": [
                      {
                        "asn": "7922",
                        "name": "Comcast Cable Communications, LLC"
                      }
                    ],
                    "country": "US",
                    "planType": "residentialbasic"
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "description": "Missing or unknown query parameter.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "examples": {
                  "planType_missing": {
                    "value": {
                      "type": "error",
                      "message": "planType query parameter is required"
                    }
                  },
                  "planType_invalid": {
                    "value": {
                      "type": "error",
                      "message": "Invalid planType"
                    }
                  },
                  "not_available": {
                    "value": {
                      "type": "error",
                      "message": "ASNs are not available for this plan type"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "The account has no Residential Basic or traffic-based Datacenter plan.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "No active plan found for this plan type. Purchase a residential basic or datacenter (traffic-based) plan."
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "description": "The ASNs could not be read right now; retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "Failed to fetch ASNs. Please try again later."
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/public/geo/asns?planType=residentialbasic&country=US' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/public/geo/asns?planType=residentialbasic&country=US',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/geo/asns?planType=residentialbasic&country=US\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/geo/asns?planType=residentialbasic&country=US');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/public/geo/locations": {
      "get": {
        "operationId": "getGeoLocations",
        "tags": [
          "Proxy locations"
        ],
        "summary": "Residential Premium location tree (geo)",
        "description": "The whole Residential Premium location tree in one call: countries, regions, cities and the ISPs available at each level. The tree keys are the `country`, `state` and `city` values and `isps[].code` the `isp` value of `POST /public/proxies/generate`; `countries` is the flat country list. The tree also carries countries we added after testing them on our gateways (Guam, Puerto Rico, Kosovo, Jersey and others): most of them have no regions, so they take country targeting only. When the tree cannot be read the call still answers 200, with `success: false` and an empty `data`: retry. Same answer as `GET /public/generator/residential-premium/targeting-options`. Free.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "parameters": [
          {
            "name": "planType",
            "in": "query",
            "description": "Optional; only `residentialpremium` is accepted.",
            "schema": {
              "type": "string",
              "enum": [
                "residentialpremium"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Location tree.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "success": {
                              "type": "boolean"
                            },
                            "message": {
                              "type": "string"
                            },
                            "data": {
                              "$ref": "#/components/schemas/LocationTree"
                            },
                            "countries": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "code": {
                                    "type": "string"
                                  },
                                  "name": {
                                    "type": "string"
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Location data retrieved successfully",
                  "payload": {
                    "success": true,
                    "message": "Location data retrieved successfully",
                    "data": {
                      "al": {
                        "country_name": "Albania",
                        "regions": {
                          "durres": {
                            "region_name": "Durres",
                            "cities": {
                              "durres": {
                                "city_name": "Durres",
                                "isps": [
                                  {
                                    "code": "abissnet_sh.a.",
                                    "name": "Abissnet Sh.A."
                                  }
                                ]
                              }
                            }
                          }
                        }
                      }
                    },
                    "countries": [
                      {
                        "code": "al",
                        "name": "Albania"
                      }
                    ]
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "description": "`planType` other than `residentialpremium`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "Only planType=residentialpremium is supported for locations"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/public/geo/locations' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/public/geo/locations',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/geo/locations\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/geo/locations');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/public/generator/residential-premium/targeting-options": {
      "get": {
        "operationId": "getResidentialPremiumTargetingOptions",
        "tags": [
          "Proxy locations"
        ],
        "summary": "Residential Premium targeting options",
        "description": "The whole Residential Premium location tree in one call: countries, regions, cities and the ISPs available at each level. The tree keys are the `country`, `state` and `city` values and `isps[].code` the `isp` value of `POST /public/proxies/generate`; `countries` is the flat country list. The tree also carries countries we added after testing them on our gateways (Guam, Puerto Rico, Kosovo, Jersey and others): most of them have no regions, so they take country targeting only. When the tree cannot be read the call still answers 200, with `success: false` and an empty `data`: retry. The MCP tool `proxy_locations` reads it. Free.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "responses": {
          "200": {
            "description": "Location tree.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "success": {
                              "type": "boolean"
                            },
                            "message": {
                              "type": "string"
                            },
                            "data": {
                              "$ref": "#/components/schemas/LocationTree"
                            },
                            "countries": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "code": {
                                    "type": "string"
                                  },
                                  "name": {
                                    "type": "string"
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Location data retrieved successfully",
                  "payload": {
                    "success": true,
                    "message": "Location data retrieved successfully",
                    "data": {
                      "al": {
                        "country_name": "Albania",
                        "regions": {
                          "durres": {
                            "region_name": "Durres",
                            "cities": {
                              "durres": {
                                "city_name": "Durres",
                                "isps": [
                                  {
                                    "code": "abissnet_sh.a.",
                                    "name": "Abissnet Sh.A."
                                  }
                                ]
                              }
                            }
                          }
                        }
                      }
                    },
                    "countries": [
                      {
                        "code": "al",
                        "name": "Albania"
                      }
                    ]
                  },
                  "pagination": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/public/generator/residential-premium/targeting-options' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/public/generator/residential-premium/targeting-options',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/generator/residential-premium/targeting-options\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/generator/residential-premium/targeting-options');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/public/generator/mobile/targeting-options": {
      "get": {
        "operationId": "getMobileTargetingOptions",
        "tags": [
          "Proxy locations"
        ],
        "summary": "Mobile targeting options",
        "description": "The whole Mobile location tree in one call: countries, regions, cities and the carriers available in each city. The tree keys are the `country`, `state` (alias `region`) and `city` values and `isps[].code` the `isp` value of `POST /public/proxies/generate` for Mobile V2 plans (`planType: mobile_v2`); the same values serve the Mobile V2 whitelist options. A country without carriers in the tree is targeted at country, region or city level. The MCP tool `proxy_locations` reads it. Free.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "responses": {
          "200": {
            "description": "Location tree.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "success": {
                              "type": "boolean"
                            },
                            "message": {
                              "type": "string"
                            },
                            "data": {
                              "$ref": "#/components/schemas/LocationTree"
                            },
                            "countries": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "code": {
                                    "type": "string"
                                  },
                                  "name": {
                                    "type": "string"
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Mobile targeting options retrieved successfully",
                  "payload": {
                    "success": true,
                    "message": "Use the tree keys as values for POST /api/v1/public/proxies/generate: country (top-level key), region (regions key), city (cities key), isp (isps[].code).",
                    "data": {
                      "us": {
                        "country_name": "United States",
                        "regions": {
                          "ohio": {
                            "region_name": "Ohio",
                            "cities": {
                              "cincinnati": {
                                "city_name": "Cincinnati",
                                "zipcodes": [],
                                "isps": [
                                  {
                                    "code": "t_mobile_usa",
                                    "name": "T-Mobile Usa"
                                  },
                                  {
                                    "code": "verizon_wireless",
                                    "name": "Verizon Wireless"
                                  }
                                ]
                              }
                            }
                          }
                        }
                      }
                    },
                    "countries": [
                      {
                        "code": "us",
                        "name": "United States"
                      }
                    ]
                  },
                  "pagination": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "502": {
            "description": "The tree could not be read right now; retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "Could not retrieve mobile targeting options. Please try again later."
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/public/generator/mobile/targeting-options' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/public/generator/mobile/targeting-options',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/generator/mobile/targeting-options\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/generator/mobile/targeting-options');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/public/generator/datacenter/targeting-options": {
      "get": {
        "operationId": "getDatacenterTargetingOptions",
        "tags": [
          "Proxy locations"
        ],
        "summary": "Datacenter gateway locations",
        "description": "The gateways of the static-gateway Datacenter plans (`planType: datacenter`): one host per country with its HTTP and SOCKS5 port. `POST /public/proxies/generate` returns one line per gateway for these plans; with the plan's username and password you can also build the lines yourself (`username:password@host:port`). Traffic-based Datacenter plans (`datacentertraffic`) are targeted by country, state, city and ASN instead: see `GET /public/geo/countries`. The MCP tool `proxy_locations` reads it. Free.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "responses": {
          "200": {
            "description": "Gateways.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "success": {
                              "type": "boolean"
                            },
                            "message": {
                              "type": "string"
                            },
                            "locations": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/DatacenterGateway"
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Datacenter (static gateways) targeting options retrieved successfully",
                  "payload": {
                    "success": true,
                    "message": "Available locations for Datacenter (static gateways) plans. Use host + portHttp (9999) or portSocks5 (10000) with your proxy credentials.",
                    "locations": [
                      {
                        "code": "us",
                        "name": "United States",
                        "host": "datacenter-us.quanticdata.io",
                        "portHttp": 9999,
                        "portSocks5": 10000
                      },
                      {
                        "code": "ca",
                        "name": "Canada",
                        "host": "datacenter-ca.quanticdata.io",
                        "portHttp": 9999,
                        "portSocks5": 10000
                      },
                      {
                        "code": "de",
                        "name": "Germany",
                        "host": "datacenter-de.quanticdata.io",
                        "portHttp": 9999,
                        "portSocks5": 10000
                      },
                      {
                        "code": "gb",
                        "name": "United Kingdom",
                        "host": "datacenter-gb.quanticdata.io",
                        "portHttp": 9999,
                        "portSocks5": 10000
                      },
                      {
                        "code": "nl",
                        "name": "Netherlands",
                        "host": "datacenter-nl.quanticdata.io",
                        "portHttp": 9999,
                        "portSocks5": 10000
                      }
                    ]
                  },
                  "pagination": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/public/generator/datacenter/targeting-options' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/public/generator/datacenter/targeting-options',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/generator/datacenter/targeting-options\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/generator/datacenter/targeting-options');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/scraper/video": {
      "post": {
        "operationId": "readVideo",
        "tags": [
          "Video"
        ],
        "summary": "Read a YouTube video for a model",
        "description": "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.",
        "x-price-key": "video",
        "x-pricing-note": "`video` per successful read, whatever the length; a window (`start`/`end`) or a transcript-only read (`max_frames: 0`) costs the same.",
        "x-rate-limit": "per-tier",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "maxLength": 2048,
                    "description": "YouTube URL: watch, youtu.be, shorts, embed or live."
                  },
                  "languages": {
                    "type": "array",
                    "maxItems": 5,
                    "items": {
                      "type": "string",
                      "minLength": 2,
                      "maxLength": 12
                    },
                    "description": "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": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 30,
                    "default": 12,
                    "description": "Frames to include; 0 = transcript only."
                  },
                  "frames": {
                    "type": "boolean",
                    "default": true,
                    "description": "false = the frame list without image data (positions, reasons and quotes only)."
                  },
                  "start": {
                    "oneOf": [
                      {
                        "type": "number",
                        "minimum": 0
                      },
                      {
                        "type": "string"
                      }
                    ],
                    "description": "Read from this point: seconds or `m:ss` / `h:mm:ss`."
                  },
                  "end": {
                    "oneOf": [
                      {
                        "type": "number",
                        "minimum": 0
                      },
                      {
                        "type": "string"
                      }
                    ],
                    "description": "Read up to this point: seconds or `m:ss` / `h:mm:ss`, after `start`."
                  },
                  "max_tokens": {
                    "type": "integer",
                    "minimum": 200,
                    "maximum": 100000,
                    "description": "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": {
                    "type": "boolean",
                    "default": false,
                    "description": "true = also return the raw timed cues under `transcript.segments`."
                  }
                }
              },
              "example": {
                "url": "https://www.youtube.com/watch?v=aircAruvnKk",
                "max_frames": 6,
                "max_tokens": 4000
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The video, read.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/VideoReadResult"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "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": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "description": "The video needs a signed-in viewer (age or membership gated) and cannot be read. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "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"
                  }
                }
              }
            }
          },
          "404": {
            "description": "The video was removed, is private, or the id is wrong. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "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"
                  }
                }
              }
            }
          },
          "422": {
            "description": "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.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "This live stream has not started yet.",
                  "payload": {
                    "url": "https://www.youtube.com/watch?v=xxxxxxxxxxx",
                    "code": "video_live_offline"
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "502": {
            "description": "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.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "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"
                  }
                }
              }
            }
          },
          "503": {
            "description": "The Video API is switched off for this key (`PRODUCT_DISABLED`), or the Data API group is switched off for non-admin keys.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "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"
                  }
                }
              }
            }
          },
          "504": {
            "description": "The read timed out. Pass `start`/`end` to read a shorter window. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/scraper/video' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"url\":\"https://www.youtube.com/watch?v=aircAruvnKk\",\"max_frames\":6,\"max_tokens\":4000}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/scraper/video',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\n        \"url\": \"https://www.youtube.com/watch?v=aircAruvnKk\",\n        \"max_frames\": 6,\n        \"max_tokens\": 4000\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/scraper/video\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"url\": \"https://www.youtube.com/watch?v=aircAruvnKk\",\n    \"max_frames\": 6,\n    \"max_tokens\": 4000\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/scraper/video');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'url' => 'https://www.youtube.com/watch?v=aircAruvnKk',\n    'max_frames' => 6,\n    'max_tokens' => 4000\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/public/proxies/{orderId}/rotate": {
      "post": {
        "operationId": "rotateProxySession",
        "tags": [
          "Proxies"
        ],
        "summary": "Rotate a sticky session (new IP, same string)",
        "description": "Restarts one sticky session of a Residential Basic or Datacenter traffic plan: the same proxy string leaves from a new IP on its next request. Send the sticky string as `generate` returned it (`proxy`), or its `sessionId` with `protocol`. Wait for the 200 before the next request. One rotation every 10 seconds per session and 1,200 rotations an hour per account (shared with rotation links), on top of the key's hourly window. Other plan types answer 409 `ROTATION_NOT_SUPPORTED` with a `reason` that says what to do instead. Errors carry a stable `payload.code`. Free; no Data API billing.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "parameters": [
          {
            "$ref": "#/components/parameters/orderId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RotateRequest"
              },
              "example": {
                "proxy": "user_8c21-country-us-session-a1b2c3-time-10:p4ssw0rd@residential-ww.quanticdata.io:9999"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session restarted.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/RotationResult"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Session rotated. The next request on this proxy string gets a new IP.",
                  "payload": {
                    "rotated": true,
                    "orderId": "ord_8c21",
                    "sessionId": "a1b2c3",
                    "port": 9999,
                    "protocol": "http",
                    "rotatedAt": "2026-10-19T14:05:00.000Z",
                    "nextAllowedAt": "2026-10-19T14:05:10.000Z"
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "description": "`VALIDATION_ERROR` (missing or malformed input), `SESSION_REQUIRED` (a rotating string: it already changes IP on every request) or `SESSION_NOT_IN_PLAN` (the string belongs to another plan).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "examples": {
                  "session_required": {
                    "value": {
                      "type": "error",
                      "message": "This is a rotating proxy string: it already gets a new IP on every request. Rotation works on sticky strings (rotation: \"sticky\" in generate).",
                      "payload": {
                        "code": "SESSION_REQUIRED"
                      }
                    }
                  },
                  "not_in_plan": {
                    "value": {
                      "type": "error",
                      "message": "This proxy string does not belong to this plan.",
                      "payload": {
                        "code": "SESSION_NOT_IN_PLAN"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`KEY_REQUIRED`: call with your own API key (keyless and pay-per-call access cannot rotate). `PLAN_UNAVAILABLE`: the plan was disabled; contact support.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "examples": {
                  "key_required": {
                    "value": {
                      "type": "error",
                      "message": "Rotation needs your own API key. Create one in the dashboard under API keys.",
                      "payload": {
                        "code": "KEY_REQUIRED"
                      }
                    }
                  },
                  "plan_unavailable": {
                    "value": {
                      "type": "error",
                      "message": "This plan is not available. Contact support.",
                      "payload": {
                        "code": "PLAN_UNAVAILABLE",
                        "planType": "residentialbasic"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`ORDER_NOT_FOUND`: no such order on this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "Order not found.",
                  "payload": {
                    "code": "ORDER_NOT_FOUND"
                  }
                }
              }
            }
          },
          "409": {
            "$ref": "#/components/responses/RotationNotSupported"
          },
          "410": {
            "description": "`PLAN_EXPIRED`: the plan has expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "This plan has expired.",
                  "payload": {
                    "code": "PLAN_EXPIRED",
                    "planType": "residentialbasic"
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RotationRateLimited"
          },
          "502": {
            "$ref": "#/components/responses/RotationFailed"
          },
          "503": {
            "$ref": "#/components/responses/RotationUnavailable"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/public/proxies/ord_8c21/rotate' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"proxy\":\"user_8c21-country-us-session-a1b2c3-time-10:p4ssw0rd@residential-ww.quanticdata.io:9999\"}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/public/proxies/ord_8c21/rotate',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\n        \"proxy\": \"user_8c21-country-us-session-a1b2c3-time-10:p4ssw0rd@residential-ww.quanticdata.io:9999\"\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/proxies/ord_8c21/rotate\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"proxy\": \"user_8c21-country-us-session-a1b2c3-time-10:p4ssw0rd@residential-ww.quanticdata.io:9999\"\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/proxies/ord_8c21/rotate');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'proxy' => 'user_8c21-country-us-session-a1b2c3-time-10:p4ssw0rd@residential-ww.quanticdata.io:9999'\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/public/proxies/{orderId}/rotation-links": {
      "get": {
        "operationId": "listRotationLinks",
        "tags": [
          "Proxies"
        ],
        "summary": "List rotation links of a plan",
        "description": "The plan's rotation links, newest first, without their tokens (only the last 4 characters, `tokenHint`): a link URL is shown once, when it is created. Revoked links are left out unless `includeRevoked=true`. Works on expired plans too, so you can revoke their links. Free.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "parameters": [
          {
            "$ref": "#/components/parameters/orderId"
          },
          {
            "name": "includeRevoked",
            "in": "query",
            "required": false,
            "description": "Include revoked links.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Rotation links.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "orderId": {
                              "type": "string"
                            },
                            "planType": {
                              "type": "string"
                            },
                            "links": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/RotationLink"
                              }
                            },
                            "limits": {
                              "type": "object",
                              "properties": {
                                "activeLinksPerPlan": {
                                  "type": "integer"
                                },
                                "cooldownSeconds": {
                                  "type": "integer"
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Success",
                  "payload": {
                    "orderId": "ord_8c21",
                    "planType": "residentialbasic",
                    "links": [
                      {
                        "id": "rlk_3f9a1c7e5b2d4a6c8e0f1a2b",
                        "sessionId": "a1b2c3",
                        "port": 9999,
                        "protocol": "http",
                        "label": "Profile 12",
                        "tokenHint": "1d0e",
                        "useCount": 14,
                        "lastUsedAt": "2026-10-19T14:05:00.000Z",
                        "createdAt": "2026-10-19T14:05:00.000Z",
                        "revoked": false,
                        "revokedAt": null
                      }
                    ],
                    "limits": {
                      "activeLinksPerPlan": 1000,
                      "cooldownSeconds": 10
                    }
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "description": "`VALIDATION_ERROR`: malformed orderId.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "A valid orderId is required.",
                  "payload": {
                    "code": "VALIDATION_ERROR"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`KEY_REQUIRED`: call with your own API key (keyless and pay-per-call access cannot rotate). `PLAN_UNAVAILABLE`: the plan was disabled; contact support.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "examples": {
                  "key_required": {
                    "value": {
                      "type": "error",
                      "message": "Rotation needs your own API key. Create one in the dashboard under API keys.",
                      "payload": {
                        "code": "KEY_REQUIRED"
                      }
                    }
                  },
                  "plan_unavailable": {
                    "value": {
                      "type": "error",
                      "message": "This plan is not available. Contact support.",
                      "payload": {
                        "code": "PLAN_UNAVAILABLE",
                        "planType": "residentialbasic"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`ORDER_NOT_FOUND`: no such order on this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "Order not found.",
                  "payload": {
                    "code": "ORDER_NOT_FOUND"
                  }
                }
              }
            }
          },
          "409": {
            "$ref": "#/components/responses/RotationNotSupported"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/RotationUnavailable"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/public/proxies/ord_8c21/rotation-links' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/public/proxies/ord_8c21/rotation-links',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/proxies/ord_8c21/rotation-links\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/proxies/ord_8c21/rotation-links');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      },
      "post": {
        "operationId": "createRotationLinks",
        "tags": [
          "Proxies"
        ],
        "summary": "Create rotation links",
        "description": "Creates one rotation link per sticky session of a Residential Basic or Datacenter traffic plan: a URL that restarts the session when called, with no API key and no header, for anti-detect browsers and scripts. Send one sticky string (`proxy`), up to 100 (`proxies`), or a `sessionId` with `protocol`. The `url` and `token` appear in this answer only: store them now. Only a hash of the token is kept. Up to 1,000 active links per plan; creating another link for the same session leaves the earlier ones working until you revoke them. Free.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "parameters": [
          {
            "$ref": "#/components/parameters/orderId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateRotationLinksRequest"
              },
              "example": {
                "proxy": "user_8c21-country-us-session-a1b2c3-time-10:p4ssw0rd@residential-ww.quanticdata.io:9999",
                "label": "Profile 12"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Links created. Each `url` is shown once.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "orderId": {
                              "type": "string"
                            },
                            "links": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/RotationLinkCreated"
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Rotation links created. Save each url now: it is not shown again.",
                  "payload": {
                    "orderId": "ord_8c21",
                    "links": [
                      {
                        "id": "rlk_3f9a1c7e5b2d4a6c8e0f1a2b",
                        "sessionId": "a1b2c3",
                        "port": 9999,
                        "protocol": "http",
                        "label": "Profile 12",
                        "tokenHint": "1d0e",
                        "useCount": 0,
                        "lastUsedAt": null,
                        "createdAt": "2026-10-19T14:05:00.000Z",
                        "revoked": false,
                        "revokedAt": null,
                        "url": "https://api.quanticdata.io/v1/public/rotate/rl_6f1c0e2b9a7d4c3e8f5a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e",
                        "token": "rl_6f1c0e2b9a7d4c3e8f5a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e"
                      }
                    ]
                  },
                  "pagination": {}
                }
              }
            }
          },
          "400": {
            "description": "`VALIDATION_ERROR` (missing or malformed input), `SESSION_REQUIRED` (a rotating string: it already changes IP on every request) or `SESSION_NOT_IN_PLAN` (the string belongs to another plan).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "examples": {
                  "session_required": {
                    "value": {
                      "type": "error",
                      "message": "This is a rotating proxy string: it already gets a new IP on every request. Rotation works on sticky strings (rotation: \"sticky\" in generate).",
                      "payload": {
                        "code": "SESSION_REQUIRED"
                      }
                    }
                  },
                  "not_in_plan": {
                    "value": {
                      "type": "error",
                      "message": "This proxy string does not belong to this plan.",
                      "payload": {
                        "code": "SESSION_NOT_IN_PLAN"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`KEY_REQUIRED`: call with your own API key (keyless and pay-per-call access cannot rotate). `PLAN_UNAVAILABLE`: the plan was disabled; contact support.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "examples": {
                  "key_required": {
                    "value": {
                      "type": "error",
                      "message": "Rotation needs your own API key. Create one in the dashboard under API keys.",
                      "payload": {
                        "code": "KEY_REQUIRED"
                      }
                    }
                  },
                  "plan_unavailable": {
                    "value": {
                      "type": "error",
                      "message": "This plan is not available. Contact support.",
                      "payload": {
                        "code": "PLAN_UNAVAILABLE",
                        "planType": "residentialbasic"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`ORDER_NOT_FOUND`: no such order on this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "Order not found.",
                  "payload": {
                    "code": "ORDER_NOT_FOUND"
                  }
                }
              }
            }
          },
          "409": {
            "$ref": "#/components/responses/RotationNotSupported"
          },
          "410": {
            "description": "`PLAN_EXPIRED`: the plan has expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "This plan has expired.",
                  "payload": {
                    "code": "PLAN_EXPIRED",
                    "planType": "residentialbasic"
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/RotationUnavailable"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/public/proxies/ord_8c21/rotation-links' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"proxy\":\"user_8c21-country-us-session-a1b2c3-time-10:p4ssw0rd@residential-ww.quanticdata.io:9999\",\"label\":\"Profile 12\"}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/public/proxies/ord_8c21/rotation-links',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\n        \"proxy\": \"user_8c21-country-us-session-a1b2c3-time-10:p4ssw0rd@residential-ww.quanticdata.io:9999\",\n        \"label\": \"Profile 12\"\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/proxies/ord_8c21/rotation-links\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"proxy\": \"user_8c21-country-us-session-a1b2c3-time-10:p4ssw0rd@residential-ww.quanticdata.io:9999\",\n    \"label\": \"Profile 12\"\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/proxies/ord_8c21/rotation-links');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'proxy' => 'user_8c21-country-us-session-a1b2c3-time-10:p4ssw0rd@residential-ww.quanticdata.io:9999',\n    'label' => 'Profile 12'\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/public/proxies/{orderId}/rotation-links/{linkId}": {
      "delete": {
        "operationId": "revokeRotationLink",
        "tags": [
          "Proxies"
        ],
        "summary": "Revoke a rotation link",
        "description": "Revokes the link at once: its URL answers 410 `LINK_REVOKED` from then on. The proxy string and the plan's other links keep working. Revoking a link twice answers the same revoked link. Free.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "parameters": [
          {
            "$ref": "#/components/parameters/orderId"
          },
          {
            "name": "linkId",
            "in": "path",
            "required": true,
            "description": "Link id (`id` in the link list).",
            "schema": {
              "type": "string"
            },
            "example": "rlk_3f9a1c7e5b2d4a6c8e0f1a2b"
          }
        ],
        "responses": {
          "200": {
            "description": "Link revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "type": "object",
                          "properties": {
                            "link": {
                              "$ref": "#/components/schemas/RotationLink"
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Rotation link revoked.",
                  "payload": {
                    "link": {
                      "id": "rlk_3f9a1c7e5b2d4a6c8e0f1a2b",
                      "sessionId": "a1b2c3",
                      "port": 9999,
                      "protocol": "http",
                      "label": "Profile 12",
                      "tokenHint": "1d0e",
                      "useCount": 14,
                      "lastUsedAt": "2026-10-19T14:05:00.000Z",
                      "createdAt": "2026-10-19T14:05:00.000Z",
                      "revoked": true,
                      "revokedAt": "2026-10-19T14:05:10.000Z"
                    }
                  },
                  "pagination": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`KEY_REQUIRED`: call with your own API key (keyless and pay-per-call access cannot rotate). `PLAN_UNAVAILABLE`: the plan was disabled; contact support.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "examples": {
                  "key_required": {
                    "value": {
                      "type": "error",
                      "message": "Rotation needs your own API key. Create one in the dashboard under API keys.",
                      "payload": {
                        "code": "KEY_REQUIRED"
                      }
                    }
                  },
                  "plan_unavailable": {
                    "value": {
                      "type": "error",
                      "message": "This plan is not available. Contact support.",
                      "payload": {
                        "code": "PLAN_UNAVAILABLE",
                        "planType": "residentialbasic"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`LINK_NOT_FOUND`: no such link on this plan, or `ORDER_NOT_FOUND`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "Rotation link not found on this plan.",
                  "payload": {
                    "code": "LINK_NOT_FOUND"
                  }
                }
              }
            }
          },
          "409": {
            "$ref": "#/components/responses/RotationNotSupported"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/RotationUnavailable"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X DELETE 'https://api.quanticdata.io/v1/public/proxies/ord_8c21/rotation-links/rlk_3f9a1c7e5b2d4a6c8e0f1a2b' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.delete(\n    'https://api.quanticdata.io/v1/public/proxies/ord_8c21/rotation-links/rlk_3f9a1c7e5b2d4a6c8e0f1a2b',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/proxies/ord_8c21/rotation-links/rlk_3f9a1c7e5b2d4a6c8e0f1a2b\", {\n  method: \"DELETE\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/proxies/ord_8c21/rotation-links/rlk_3f9a1c7e5b2d4a6c8e0f1a2b');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'DELETE',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/public/rotate/{token}": {
      "get": {
        "operationId": "useRotationLink",
        "tags": [
          "Proxies"
        ],
        "summary": "Call a rotation link",
        "description": "The rotation link itself, as returned in `url` by `POST /public/proxies/{orderId}/rotation-links`: no API key, no header, no body. Restarts the link's sticky session, so the same proxy string leaves from a new IP on its next request. GET and POST behave the same; HEAD answers 405 without rotating, so link previews do not trigger it. Treat the URL like a password: it can rotate that one session, nothing else (no credentials, no balance). Revoke it with `DELETE /public/proxies/{orderId}/rotation-links/{linkId}`. Errors carry a stable `payload.code`. Free.",
        "security": [],
        "x-price-key": null,
        "x-rate-limit": "One rotation every 10 seconds per session and 1,200 rotations an hour per account, shared with the rotate endpoint. An address that sends 30 unknown links in 10 minutes is blocked for 10 minutes.",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "description": "The token at the end of the link URL.",
            "schema": {
              "type": "string",
              "pattern": "^rl_[a-f0-9]{64}$"
            },
            "example": "rl_6f1c0e2b9a7d4c3e8f5a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e"
          }
        ],
        "responses": {
          "200": {
            "description": "Session restarted.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "allOf": [
                            {
                              "$ref": "#/components/schemas/RotationResult"
                            },
                            {
                              "type": "object",
                              "properties": {
                                "linkId": {
                                  "type": "string"
                                },
                                "label": {
                                  "type": [
                                    "string",
                                    "null"
                                  ]
                                }
                              }
                            }
                          ]
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Session rotated. The next request on this proxy string gets a new IP.",
                  "payload": {
                    "rotated": true,
                    "orderId": "ord_8c21",
                    "sessionId": "a1b2c3",
                    "port": 9999,
                    "protocol": "http",
                    "rotatedAt": "2026-10-19T14:05:00.000Z",
                    "nextAllowedAt": "2026-10-19T14:05:10.000Z",
                    "linkId": "rlk_3f9a1c7e5b2d4a6c8e0f1a2b",
                    "label": "Profile 12"
                  },
                  "pagination": {}
                }
              }
            }
          },
          "403": {
            "description": "`ACCOUNT_DISABLED`: the account that owns the link is disabled. `PLAN_UNAVAILABLE`: the plan was disabled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "This account is disabled. Contact support.",
                  "payload": {
                    "code": "ACCOUNT_DISABLED"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`LINK_NOT_FOUND`: unknown link, or `ORDER_NOT_FOUND` when the plan is no longer on the account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "Rotation link not found. Check the URL, or create a new link.",
                  "payload": {
                    "code": "LINK_NOT_FOUND"
                  }
                }
              }
            }
          },
          "409": {
            "$ref": "#/components/responses/RotationNotSupported"
          },
          "410": {
            "description": "`LINK_REVOKED`: the link was revoked; create a new one. `PLAN_EXPIRED`: the plan has expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "examples": {
                  "revoked": {
                    "value": {
                      "type": "error",
                      "message": "This rotation link was revoked. Create a new one for this session.",
                      "payload": {
                        "code": "LINK_REVOKED"
                      }
                    }
                  },
                  "expired": {
                    "value": {
                      "type": "error",
                      "message": "This plan has expired.",
                      "payload": {
                        "code": "PLAN_EXPIRED",
                        "planType": "residentialbasic"
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RotationRateLimited"
          },
          "502": {
            "$ref": "#/components/responses/RotationFailed"
          },
          "503": {
            "$ref": "#/components/responses/RotationUnavailable"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/public/rotate/rl_6f1c0e2b9a7d4c3e8f5a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/public/rotate/rl_6f1c0e2b9a7d4c3e8f5a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e',\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/rotate/rl_6f1c0e2b9a7d4c3e8f5a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e\", {\n  method: \"GET\"\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/rotate/rl_6f1c0e2b9a7d4c3e8f5a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      },
      "post": {
        "operationId": "useRotationLinkPost",
        "tags": [
          "Proxies"
        ],
        "summary": "Call a rotation link (POST)",
        "description": "Same as `GET /public/rotate/{token}`, for tools that can only send POST. No API key, no header, no body.",
        "security": [],
        "x-price-key": null,
        "x-rate-limit": "One rotation every 10 seconds per session and 1,200 rotations an hour per account, shared with the rotate endpoint. An address that sends 30 unknown links in 10 minutes is blocked for 10 minutes.",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "description": "The token at the end of the link URL.",
            "schema": {
              "type": "string",
              "pattern": "^rl_[a-f0-9]{64}$"
            },
            "example": "rl_6f1c0e2b9a7d4c3e8f5a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e"
          }
        ],
        "responses": {
          "200": {
            "description": "Session restarted.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "allOf": [
                            {
                              "$ref": "#/components/schemas/RotationResult"
                            },
                            {
                              "type": "object",
                              "properties": {
                                "linkId": {
                                  "type": "string"
                                },
                                "label": {
                                  "type": [
                                    "string",
                                    "null"
                                  ]
                                }
                              }
                            }
                          ]
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "type": "response",
                  "message": "Session rotated. The next request on this proxy string gets a new IP.",
                  "payload": {
                    "rotated": true,
                    "orderId": "ord_8c21",
                    "sessionId": "a1b2c3",
                    "port": 9999,
                    "protocol": "http",
                    "rotatedAt": "2026-10-19T14:05:00.000Z",
                    "nextAllowedAt": "2026-10-19T14:05:10.000Z",
                    "linkId": "rlk_3f9a1c7e5b2d4a6c8e0f1a2b",
                    "label": "Profile 12"
                  },
                  "pagination": {}
                }
              }
            }
          },
          "403": {
            "description": "`ACCOUNT_DISABLED`: the account that owns the link is disabled. `PLAN_UNAVAILABLE`: the plan was disabled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "This account is disabled. Contact support.",
                  "payload": {
                    "code": "ACCOUNT_DISABLED"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`LINK_NOT_FOUND`: unknown link, or `ORDER_NOT_FOUND` when the plan is no longer on the account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "Rotation link not found. Check the URL, or create a new link.",
                  "payload": {
                    "code": "LINK_NOT_FOUND"
                  }
                }
              }
            }
          },
          "409": {
            "$ref": "#/components/responses/RotationNotSupported"
          },
          "410": {
            "description": "`LINK_REVOKED`: the link was revoked; create a new one. `PLAN_EXPIRED`: the plan has expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "examples": {
                  "revoked": {
                    "value": {
                      "type": "error",
                      "message": "This rotation link was revoked. Create a new one for this session.",
                      "payload": {
                        "code": "LINK_REVOKED"
                      }
                    }
                  },
                  "expired": {
                    "value": {
                      "type": "error",
                      "message": "This plan has expired.",
                      "payload": {
                        "code": "PLAN_EXPIRED",
                        "planType": "residentialbasic"
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RotationRateLimited"
          },
          "502": {
            "$ref": "#/components/responses/RotationFailed"
          },
          "503": {
            "$ref": "#/components/responses/RotationUnavailable"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/public/rotate/rl_6f1c0e2b9a7d4c3e8f5a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/public/rotate/rl_6f1c0e2b9a7d4c3e8f5a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e',\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/public/rotate/rl_6f1c0e2b9a7d4c3e8f5a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e\", {\n  method: \"POST\"\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/public/rotate/rl_6f1c0e2b9a7d4c3e8f5a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/agent/auth": {
      "post": {
        "operationId": "agentRegister",
        "tags": [
          "Agents"
        ],
        "summary": "Register an agent with a verified email (step 1 of 2)",
        "description": "Starts the registration of an account for the person the agent works for (the `register_uri` of the `agent_auth` block in the OAuth metadata). The agent sends that person's email address; QuanticData emails them a 6-digit code (subject \"… is your QuanticData verification code — an AI agent asked to register\"); the person reads it to the agent; the agent exchanges it at `POST /agent/auth/claim` for an API key. No password, no browser, no captcha. Tell the user which service you are registering with before calling. The answer is the same `pending` document whether or not an account already exists for that email: the code goes to the mailbox owner, and a confirmed claim adds a key to the existing account instead of opening a new one. The code lives 10 minutes; 5 wrong codes cancel the registration; at most 3 codes per email per hour. Not offered: anonymous registration (400 `anonymous_not_enabled`) and identity assertions (ID-JAG, 400). Temporary or unreachable mailboxes answer 422 `invalid_email`. A registration that the risk checks want a person to finish answers 428 `human_verification_required` with `register_human`: ask the user to register in the browser and hand you a key from the API keys page. When the switch is off the endpoint answers 503 `agent_registration_disabled`. Also served at `https://app.quanticdata.io/api/v1/agent/auth`. Errors are OAuth-style JSON (`error`, `error_description`), not the Data API envelope. No API key: this call creates one.",
        "security": [],
        "x-price-key": null,
        "x-rate-limit": "Per IP: 5 registrations an hour, 20 a day. Per email: 3 codes an hour. Per registrable email domain: 10 a day. A global daily cap across both brands. Exceeded limits answer 429 `rate_limited` with `Retry-After`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email"
                ],
                "additionalProperties": true,
                "properties": {
                  "method": {
                    "type": "string",
                    "enum": [
                      "verified_email"
                    ],
                    "default": "verified_email",
                    "description": "The only method offered. `{\"type\": \"service_auth\", \"login_hint\": \"…\"}` is accepted as an alias of `{\"method\": \"verified_email\", \"email\": \"…\"}`."
                  },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "The person's permanent email address: it receives the code, and later invoices and API alerts."
                  },
                  "agent": {
                    "type": "object",
                    "description": "Who is registering (optional). Shown in the verification email and in the key's name on the dashboard.",
                    "properties": {
                      "name": {
                        "type": "string",
                        "description": "Printable characters only; trimmed to a short label."
                      },
                      "url": {
                        "type": "string",
                        "format": "uri",
                        "description": "http(s) URL of the agent or its operator."
                      }
                    }
                  }
                }
              },
              "example": {
                "method": "verified_email",
                "email": "user@example.com",
                "agent": {
                  "name": "Research agent",
                  "url": "https://example.com/agent"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Code sent. Ask the user for the 6 digits, then call `claim_uri`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentAuthPending"
                },
                "example": {
                  "status": "pending",
                  "registration_type": "verified_email",
                  "claim_uri": "https://app.quanticdata.io/api/v1/agent/auth/claim",
                  "expires_in": 600,
                  "interval": 0,
                  "message": "A 6-digit verification code was emailed to user@example.com. Ask your user for it, then POST {\"email\": \"user@example.com\", \"code\": \"<6 digits>\"} to claim_uri. The API key is returned once, in that response."
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid field, or a method that is not offered (`anonymous_not_enabled`, identity assertions).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentAuthError"
                },
                "example": {
                  "error": "anonymous_not_enabled",
                  "error_description": "Anonymous registration is not offered: register with a verified email (method \"verified_email\").",
                  "auth_md": "https://quanticdata.io/auth.md"
                }
              }
            }
          },
          "422": {
            "description": "Temporary or unreachable mailbox.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentAuthError"
                },
                "example": {
                  "error": "invalid_email",
                  "error_description": "Temporary or unreachable mailboxes are not accepted. Register with a permanent email address that can receive invoices and API alerts.",
                  "register_human": "https://app.quanticdata.io/register"
                }
              }
            }
          },
          "428": {
            "description": "A person has to finish this registration in the browser.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentAuthError"
                },
                "example": {
                  "error": "human_verification_required",
                  "error_description": "This registration needs a person to complete it. Ask your user to open register_human, create the account and an API key in the dashboard, then give you the key.",
                  "register_human": "https://app.quanticdata.io/register",
                  "auth_md": "https://quanticdata.io/auth.md"
                }
              }
            }
          },
          "429": {
            "description": "A cap was reached; wait `retry_after` seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentAuthError"
                },
                "example": {
                  "error": "rate_limited",
                  "error_description": "Too many agent registrations from this address. Retry after 3600 seconds.",
                  "retry_after": 3600
                }
              }
            }
          },
          "503": {
            "description": "Agent registration is switched off (`agent_registration_disabled`), or the code email could not be sent right now (`temporarily_unavailable`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentAuthError"
                },
                "example": {
                  "error": "agent_registration_disabled",
                  "error_description": "Automated agent registration is switched off right now. A person can register at register_human and create an API key in the dashboard.",
                  "register_human": "https://app.quanticdata.io/register",
                  "auth_md": "https://quanticdata.io/auth.md"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/agent/auth' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"method\":\"verified_email\",\"email\":\"user@example.com\",\"agent\":{\"name\":\"Research agent\",\"url\":\"https://example.com/agent\"}}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/agent/auth',\n    json={\n        \"method\": \"verified_email\",\n        \"email\": \"user@example.com\",\n        \"agent\": {\n            \"name\": \"Research agent\",\n            \"url\": \"https://example.com/agent\"\n        }\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/agent/auth\", {\n  method: \"POST\",\n  headers: {\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"method\": \"verified_email\",\n    \"email\": \"user@example.com\",\n    \"agent\": {\n      \"name\": \"Research agent\",\n      \"url\": \"https://example.com/agent\"\n    }\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/agent/auth');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'method' => 'verified_email',\n    'email' => 'user@example.com',\n    'agent' => [\n      'name' => 'Research agent',\n      'url' => 'https://example.com/agent'\n    ]\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/agent/auth/claim": {
      "post": {
        "operationId": "agentClaim",
        "tags": [
          "Agents"
        ],
        "summary": "Exchange the emailed code for an API key (step 2 of 2)",
        "description": "The `claim_uri` of the `agent_auth` block. With the right code the pending registration is consumed before anything is created, so two concurrent claims yield one key. A new account is born verified, on the standard pay-as-you-go tier, with a random password nobody knows: the person signs in to the dashboard through the password reset link. An existing account simply gets a new key. The key is returned once in this response and is never emailed; the person can see, rotate or revoke it on the API keys page. Codes: 6 digits, spaces and dashes ignored (`user_code` accepted as an alias of `code`). A wrong code answers 400 `invalid_code` with `attempts_remaining`; the fifth wrong code cancels the registration (429 `too_many_attempts`); no pending registration, an expired code or a second claim answers 410 `claim_expired`: start again at `POST /agent/auth`. Also served at `https://app.quanticdata.io/api/v1/agent/auth/claim`. OAuth-style error bodies.",
        "security": [],
        "x-price-key": null,
        "x-rate-limit": "30 claim attempts per IP an hour (429 `rate_limited` with `Retry-After`); 5 wrong codes per registration.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "code"
                ],
                "additionalProperties": true,
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "The same address as in step 1."
                  },
                  "code": {
                    "type": "string",
                    "pattern": "^[0-9 -]{6,8}$",
                    "description": "The 6 digits from the email."
                  }
                }
              },
              "example": {
                "email": "user@example.com",
                "code": "482913"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The API key, once.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentAuthCredential"
                },
                "example": {
                  "credential_type": "api_key",
                  "api_key": "qd_live_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
                  "key_prefix": "qd_live_0123",
                  "account_status": "created",
                  "email": "user@example.com",
                  "usage": {
                    "header": "Authorization: Bearer <api_key>",
                    "api_base": "https://api.quanticdata.io/v1"
                  },
                  "docs": "https://quanticdata.io/docs/",
                  "auth_md": "https://quanticdata.io/auth.md",
                  "note": "This key is shown once and is not sent by email. Store it in an environment variable. Your user can see, rotate or revoke it from the dashboard (API keys page)."
                }
              }
            }
          },
          "400": {
            "description": "Wrong code (`invalid_code`, with the attempts left) or a malformed body (`invalid_request`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentAuthError"
                },
                "example": {
                  "error": "invalid_code",
                  "error_description": "Wrong verification code.",
                  "attempts_remaining": 4
                }
              }
            }
          },
          "410": {
            "description": "No pending registration for this email, the code expired, or the registration was already claimed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentAuthError"
                },
                "example": {
                  "error": "claim_expired",
                  "error_description": "No pending registration for this email, or the code expired. Start again at register_uri.",
                  "register_uri": "https://app.quanticdata.io/api/v1/agent/auth"
                }
              }
            }
          },
          "429": {
            "description": "Fifth wrong code (`too_many_attempts`, the registration is cancelled) or too many claims from this IP (`rate_limited`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentAuthError"
                },
                "example": {
                  "error": "too_many_attempts",
                  "error_description": "Too many wrong codes: this registration was cancelled. Start again at register_uri.",
                  "register_uri": "https://app.quanticdata.io/api/v1/agent/auth"
                }
              }
            }
          },
          "503": {
            "description": "Agent registration is switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentAuthError"
                },
                "example": {
                  "error": "agent_registration_disabled",
                  "error_description": "Automated agent registration is switched off right now. A person can register at register_human and create an API key in the dashboard.",
                  "register_human": "https://app.quanticdata.io/register",
                  "auth_md": "https://quanticdata.io/auth.md"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/agent/auth/claim' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"email\":\"user@example.com\",\"code\":\"482913\"}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/agent/auth/claim',\n    json={\n        \"email\": \"user@example.com\",\n        \"code\": \"482913\"\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/agent/auth/claim\", {\n  method: \"POST\",\n  headers: {\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"email\": \"user@example.com\",\n    \"code\": \"482913\"\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/agent/auth/claim');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'email' => 'user@example.com',\n    'code' => '482913'\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/agent/ucp": {
      "get": {
        "operationId": "ucpProfile",
        "tags": [
          "Agents"
        ],
        "summary": "UCP discovery profile",
        "description": "The Universal Commerce Protocol profile of QuanticData (ucp.dev, version 2026-08-25): the `dev.ucp.shopping` service with its REST endpoint, the `dev.ucp.shopping.checkout` capability, and the one payment handler an agent can use by itself, the prepaid account balance (`balance`). The same document is served at `https://api.quanticdata.io/.well-known/ucp`, `https://app.quanticdata.io/.well-known/ucp` and `https://quanticdata.io/.well-known/ucp`, with `Cache-Control: public`. The flat aliases at the root (`protocol_version`, `services`, `capabilities`, `endpoints`) repeat the `ucp` block for scanners that read them there. No key needed.",
        "security": [],
        "x-price-key": null,
        "x-rate-limit": "none",
        "responses": {
          "200": {
            "description": "The profile.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true,
                  "properties": {
                    "ucp": {
                      "type": "object",
                      "properties": {
                        "version": {
                          "type": "string"
                        },
                        "services": {
                          "type": "object"
                        },
                        "capabilities": {
                          "type": "object"
                        },
                        "payment_handlers": {
                          "type": "object"
                        }
                      }
                    },
                    "keys": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "endpoints": {
                      "type": "object",
                      "properties": {
                        "checkout_sessions": {
                          "type": "string",
                          "format": "uri"
                        },
                        "openapi": {
                          "type": "string",
                          "format": "uri"
                        },
                        "catalog": {
                          "type": "string",
                          "format": "uri"
                        },
                        "docs": {
                          "type": "string",
                          "format": "uri"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "ucp": {
                    "version": "2026-08-25",
                    "services": {
                      "dev.ucp.shopping": [
                        {
                          "version": "2026-08-25",
                          "spec": "https://ucp.dev/2026-08-25/specification/overview/",
                          "schema": "https://ucp.dev/2026-08-25/services/shopping/rest.openapi.json",
                          "transport": "rest",
                          "endpoint": "https://api.quanticdata.io/v1/agent/ucp"
                        }
                      ]
                    },
                    "capabilities": {
                      "dev.ucp.shopping.checkout": [
                        {
                          "version": "2026-08-25",
                          "spec": "https://ucp.dev/2026-08-25/specification/shopping/checkout/",
                          "schema": "https://ucp.dev/2026-08-25/schemas/shopping/checkout.json"
                        }
                      ]
                    },
                    "payment_handlers": {
                      "io.quanticdata.io.balance": [
                        {
                          "id": "balance",
                          "version": "2026-10-08",
                          "schema": "https://api.quanticdata.io/v1/agent/ucp/handlers/balance.json",
                          "available_instruments": [
                            {
                              "type": "account_balance",
                              "currency": "USD"
                            }
                          ]
                        }
                      ]
                    }
                  },
                  "keys": [],
                  "endpoints": {
                    "checkout_sessions": "https://api.quanticdata.io/v1/agent/ucp/checkout-sessions",
                    "openapi": "https://api.quanticdata.io/openapi.json",
                    "catalog": "https://api.quanticdata.io/v1/public/plans",
                    "docs": "https://quanticdata.io/docs/"
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/agent/ucp'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/agent/ucp',\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/agent/ucp\", {\n  method: \"GET\"\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/agent/ucp');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/agent/ucp/handlers/balance.json": {
      "get": {
        "operationId": "ucpBalanceHandlerSchema",
        "tags": [
          "Agents"
        ],
        "summary": "JSON Schema of the balance payment instrument",
        "description": "The instrument an agent passes to complete a checkout from the account balance: `{\"handler_id\": \"balance\", \"type\": \"account_balance\"}`. No credential travels with it, the API key of the request is the authorization. Linked from the UCP profile. No key needed.",
        "security": [],
        "x-price-key": null,
        "x-rate-limit": "none",
        "responses": {
          "200": {
            "description": "JSON Schema (draft 2020-12).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "example": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "$id": "https://api.quanticdata.io/v1/agent/ucp/handlers/balance.json",
                  "title": "QuanticData account balance payment instrument",
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "handler_id": {
                      "type": "string",
                      "const": "balance"
                    },
                    "type": {
                      "type": "string",
                      "const": "account_balance"
                    },
                    "selected": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "handler_id",
                    "type"
                  ]
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/agent/ucp/handlers/balance.json'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/agent/ucp/handlers/balance.json',\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/agent/ucp/handlers/balance.json\", {\n  method: \"GET\"\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/agent/ucp/handlers/balance.json');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/agent/ucp/checkout-sessions": {
      "post": {
        "operationId": "ucpCreateCheckout",
        "tags": [
          "Agents"
        ],
        "summary": "Create a checkout session for one plan",
        "description": "Create Checkout of the UCP REST binding. The agent names one public plan (`line_items[0].item.id` from `GET /public/plans`, quantity 1) and gets back the real price: list price from the catalog, VAT by the same rule as the human checkout (0% for `BALANCE` and `NOWPAYMENTS`, 22% for `PAYPAL` and `PAYPAL_CARD`). The declared `payment_method` only decides the VAT in the quote. Status on creation: `ready_for_complete` when the method is `BALANCE` and the balance covers the total (complete it with `POST /agent/ucp/checkout-sessions/{id}/complete`), otherwise `requires_escalation` with a `continue_url` where the person pays on the dashboard; poll `GET /agent/ucp/checkout-sessions/{id}` until `completed`. A session expires after 6 hours. ISP plans are configured per order and are not sold here (400 `plan_not_sellable_here`: use the dashboard or the Premium ISP and IPv6 endpoints); trial-only and custom plans are not public (404 `plan_not_found`). Send an `Idempotency-Key` header (8–128 letters, digits, `_ . : -`) to make retries safe: the same key answers 200 with the session already created. The plainer alternative without the UCP shape is `POST /public/purchase`. Authentication: the API key of the buying account, as `Authorization: Bearer` or `X-API-Key`. Errors are UCP documents.",
        "x-price-key": null,
        "x-pricing-note": "Creating a session is free; the plan costs its `amount` from `GET /public/plans`, charged only when the session is completed.",
        "x-rate-limit": "per-tier",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Optional. 8–128 characters among letters, digits, `_`, `.`, `:` and `-`. The same key from the same account answers 200 with the existing session instead of creating another.",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_.:-]{8,128}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "line_items"
                ],
                "additionalProperties": true,
                "properties": {
                  "line_items": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 1,
                    "items": {
                      "type": "object",
                      "required": [
                        "item"
                      ],
                      "properties": {
                        "item": {
                          "type": "object",
                          "required": [
                            "id"
                          ],
                          "properties": {
                            "id": {
                              "type": "string",
                              "description": "Plan id from `GET /public/plans`."
                            }
                          }
                        },
                        "quantity": {
                          "type": "integer",
                          "const": 1,
                          "default": 1
                        }
                      }
                    }
                  },
                  "buyer": {
                    "type": "object",
                    "properties": {
                      "email": {
                        "type": "string",
                        "format": "email",
                        "description": "Optional, echoed in the document."
                      }
                    }
                  },
                  "payment_method": {
                    "type": "string",
                    "enum": [
                      "BALANCE",
                      "NOWPAYMENTS",
                      "PAYPAL",
                      "PAYPAL_CARD"
                    ],
                    "default": "BALANCE",
                    "description": "What the quote assumes. `BALANCE` is the only one the agent can complete; the others are paid by a person at `continue_url`."
                  }
                }
              },
              "example": {
                "line_items": [
                  {
                    "item": {
                      "id": "pln_3e7a"
                    },
                    "quantity": 1
                  }
                ],
                "buyer": {
                  "email": "user@example.com"
                },
                "payment_method": "BALANCE"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Replay of an `Idempotency-Key` already used: the existing session.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UcpCheckoutSession"
                },
                "example": {
                  "ucp": {
                    "version": "2026-08-25",
                    "status": "success",
                    "capabilities": {
                      "dev.ucp.shopping.checkout": [
                        {
                          "version": "2026-08-25",
                          "spec": "https://ucp.dev/2026-08-25/specification/shopping/checkout/",
                          "schema": "https://ucp.dev/2026-08-25/schemas/shopping/checkout.json"
                        }
                      ]
                    },
                    "payment_handlers": {
                      "io.quanticdata.io.balance": [
                        {
                          "id": "balance",
                          "version": "2026-10-08",
                          "spec": "https://quanticdata.io/docs/#section/Agent-checkout-(UCP)",
                          "schema": "https://api.quanticdata.io/v1/agent/ucp/handlers/balance.json",
                          "available_instruments": [
                            {
                              "type": "account_balance",
                              "currency": "USD"
                            }
                          ]
                        }
                      ]
                    }
                  },
                  "id": "chk_7d3f0a9b2c4e1f6a8b9c0d1e",
                  "status": "ready_for_complete",
                  "currency": "USD",
                  "expires_at": "2026-10-26T18:00:00.000Z",
                  "line_items": [
                    {
                      "id": "li_pln_3e7a",
                      "item": {
                        "id": "pln_3e7a",
                        "title": "Residential - Quark (5GB)",
                        "price": 1200
                      },
                      "quantity": 1,
                      "totals": [
                        {
                          "type": "subtotal",
                          "amount": 1200
                        },
                        {
                          "type": "total",
                          "amount": 1200
                        }
                      ]
                    }
                  ],
                  "totals": [
                    {
                      "type": "subtotal",
                      "amount": 1200
                    },
                    {
                      "type": "total",
                      "amount": 1200
                    }
                  ],
                  "payment": {
                    "instruments": [
                      {
                        "id": "balance",
                        "handler_id": "balance",
                        "type": "account_balance",
                        "selected": true
                      }
                    ],
                    "declared_method": "BALANCE"
                  },
                  "continue_url": "https://app.quanticdata.io/plans?network=RESIDENTIAL&utm_source=agent&utm_medium=ucp&utm_campaign=checkout-session&agent_checkout=chk_7d3f0a9b2c4e1f6a8b9c0d1e",
                  "links": [
                    {
                      "type": "privacy_policy",
                      "url": "https://quanticdata.io/privacy"
                    },
                    {
                      "type": "terms_of_service",
                      "url": "https://quanticdata.io/terms"
                    }
                  ],
                  "messages": [
                    {
                      "type": "info",
                      "code": "balance_available",
                      "content": "The account balance covers this checkout. Complete it with POST /checkout-sessions/chk_7d3f0a9b2c4e1f6a8b9c0d1e/complete and payment.instruments[0].handler_id = \"balance\" (0% VAT)."
                    },
                    {
                      "type": "info",
                      "code": "vat_rule",
                      "content": "Totals carry 0% VAT (balance or crypto). Paying by card or PayPal on the dashboard adds 22% VAT."
                    }
                  ],
                  "created_at": "2026-10-26T12:00:00.000Z",
                  "updated_at": "2026-10-26T12:00:00.000Z"
                }
              }
            }
          },
          "201": {
            "description": "Session created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UcpCheckoutSession"
                },
                "example": {
                  "ucp": {
                    "version": "2026-08-25",
                    "status": "success",
                    "capabilities": {
                      "dev.ucp.shopping.checkout": [
                        {
                          "version": "2026-08-25",
                          "spec": "https://ucp.dev/2026-08-25/specification/shopping/checkout/",
                          "schema": "https://ucp.dev/2026-08-25/schemas/shopping/checkout.json"
                        }
                      ]
                    },
                    "payment_handlers": {
                      "io.quanticdata.io.balance": [
                        {
                          "id": "balance",
                          "version": "2026-10-08",
                          "spec": "https://quanticdata.io/docs/#section/Agent-checkout-(UCP)",
                          "schema": "https://api.quanticdata.io/v1/agent/ucp/handlers/balance.json",
                          "available_instruments": [
                            {
                              "type": "account_balance",
                              "currency": "USD"
                            }
                          ]
                        }
                      ]
                    }
                  },
                  "id": "chk_7d3f0a9b2c4e1f6a8b9c0d1e",
                  "status": "ready_for_complete",
                  "currency": "USD",
                  "expires_at": "2026-10-26T18:00:00.000Z",
                  "line_items": [
                    {
                      "id": "li_pln_3e7a",
                      "item": {
                        "id": "pln_3e7a",
                        "title": "Residential - Quark (5GB)",
                        "price": 1200
                      },
                      "quantity": 1,
                      "totals": [
                        {
                          "type": "subtotal",
                          "amount": 1200
                        },
                        {
                          "type": "total",
                          "amount": 1200
                        }
                      ]
                    }
                  ],
                  "totals": [
                    {
                      "type": "subtotal",
                      "amount": 1200
                    },
                    {
                      "type": "total",
                      "amount": 1200
                    }
                  ],
                  "payment": {
                    "instruments": [
                      {
                        "id": "balance",
                        "handler_id": "balance",
                        "type": "account_balance",
                        "selected": true
                      }
                    ],
                    "declared_method": "BALANCE"
                  },
                  "continue_url": "https://app.quanticdata.io/plans?network=RESIDENTIAL&utm_source=agent&utm_medium=ucp&utm_campaign=checkout-session&agent_checkout=chk_7d3f0a9b2c4e1f6a8b9c0d1e",
                  "links": [
                    {
                      "type": "privacy_policy",
                      "url": "https://quanticdata.io/privacy"
                    },
                    {
                      "type": "terms_of_service",
                      "url": "https://quanticdata.io/terms"
                    }
                  ],
                  "messages": [
                    {
                      "type": "info",
                      "code": "balance_available",
                      "content": "The account balance covers this checkout. Complete it with POST /checkout-sessions/chk_7d3f0a9b2c4e1f6a8b9c0d1e/complete and payment.instruments[0].handler_id = \"balance\" (0% VAT)."
                    },
                    {
                      "type": "info",
                      "code": "vat_rule",
                      "content": "Totals carry 0% VAT (balance or crypto). Paying by card or PayPal on the dashboard adds 22% VAT."
                    }
                  ],
                  "created_at": "2026-10-26T12:00:00.000Z",
                  "updated_at": "2026-10-26T12:00:00.000Z"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request: `invalid_json`, `one_item_only`, `invalid_item`, `quantity_not_supported`, `invalid_payment_method`, `plan_not_sellable_here` (ISP plans).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UcpErrorDocument"
                },
                "example": {
                  "ucp": {
                    "version": "2026-08-25",
                    "status": "error"
                  },
                  "messages": [
                    {
                      "type": "error",
                      "code": "plan_not_sellable_here",
                      "content": "ISP plans are configured per order (IPs, region, days): buy them on the dashboard.",
                      "severity": "fatal",
                      "path": "$.line_items[0].item.id"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No public plan with that id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UcpErrorDocument"
                },
                "example": {
                  "ucp": {
                    "version": "2026-08-25",
                    "status": "error"
                  },
                  "messages": [
                    {
                      "type": "error",
                      "code": "plan_not_found",
                      "content": "No public plan with that id.",
                      "severity": "fatal",
                      "path": "$.line_items[0].item.id"
                    }
                  ]
                }
              }
            }
          },
          "503": {
            "description": "The checkout store is not available on this host (`not_provisioned`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UcpErrorDocument"
                },
                "example": {
                  "ucp": {
                    "version": "2026-08-25",
                    "status": "error"
                  },
                  "messages": [
                    {
                      "type": "error",
                      "code": "not_provisioned",
                      "content": "Agent checkout sessions are not provisioned on this host yet.",
                      "severity": "fatal"
                    }
                  ]
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/agent/ucp/checkout-sessions' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"line_items\":[{\"item\":{\"id\":\"pln_3e7a\"},\"quantity\":1}],\"buyer\":{\"email\":\"user@example.com\"},\"payment_method\":\"BALANCE\"}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/agent/ucp/checkout-sessions',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\n        \"line_items\": [\n            {\n                \"item\": {\n                    \"id\": \"pln_3e7a\"\n                },\n                \"quantity\": 1\n            }\n        ],\n        \"buyer\": {\n            \"email\": \"user@example.com\"\n        },\n        \"payment_method\": \"BALANCE\"\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/agent/ucp/checkout-sessions\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"line_items\": [\n      {\n        \"item\": {\n          \"id\": \"pln_3e7a\"\n        },\n        \"quantity\": 1\n      }\n    ],\n    \"buyer\": {\n      \"email\": \"user@example.com\"\n    },\n    \"payment_method\": \"BALANCE\"\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/agent/ucp/checkout-sessions');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'line_items' => [[\n      'item' => [\n        'id' => 'pln_3e7a'\n      ],\n      'quantity' => 1\n    ]],\n    'buyer' => [\n      'email' => 'user@example.com'\n    ],\n    'payment_method' => 'BALANCE'\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/agent/ucp/checkout-sessions/{id}": {
      "get": {
        "operationId": "ucpGetCheckout",
        "tags": [
          "Agents"
        ],
        "summary": "Read a checkout session",
        "description": "Get Checkout. Reading refreshes the state: if the person has paid that plan on the dashboard since the session was created, the session becomes `completed` with the `order`; if the 6 hours have passed, it becomes `canceled`. Poll this after handing `continue_url` to the person. Authentication: the API key of the buying account, as `Authorization: Bearer` or `X-API-Key`.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Session id (`chk_` + 24 hex). A session of another account answers 404.",
            "schema": {
              "type": "string",
              "pattern": "^chk_[0-9a-f]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The session document.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UcpCheckoutSession"
                },
                "example": {
                  "ucp": {
                    "version": "2026-08-25",
                    "status": "success",
                    "capabilities": {
                      "dev.ucp.shopping.checkout": [
                        {
                          "version": "2026-08-25",
                          "spec": "https://ucp.dev/2026-08-25/specification/shopping/checkout/",
                          "schema": "https://ucp.dev/2026-08-25/schemas/shopping/checkout.json"
                        }
                      ]
                    },
                    "payment_handlers": {
                      "io.quanticdata.io.balance": [
                        {
                          "id": "balance",
                          "version": "2026-10-08",
                          "spec": "https://quanticdata.io/docs/#section/Agent-checkout-(UCP)",
                          "schema": "https://api.quanticdata.io/v1/agent/ucp/handlers/balance.json",
                          "available_instruments": [
                            {
                              "type": "account_balance",
                              "currency": "USD"
                            }
                          ]
                        }
                      ]
                    }
                  },
                  "id": "chk_7d3f0a9b2c4e1f6a8b9c0d1e",
                  "status": "ready_for_complete",
                  "currency": "USD",
                  "expires_at": "2026-10-26T18:00:00.000Z",
                  "line_items": [
                    {
                      "id": "li_pln_3e7a",
                      "item": {
                        "id": "pln_3e7a",
                        "title": "Residential - Quark (5GB)",
                        "price": 1200
                      },
                      "quantity": 1,
                      "totals": [
                        {
                          "type": "subtotal",
                          "amount": 1200
                        },
                        {
                          "type": "total",
                          "amount": 1200
                        }
                      ]
                    }
                  ],
                  "totals": [
                    {
                      "type": "subtotal",
                      "amount": 1200
                    },
                    {
                      "type": "total",
                      "amount": 1200
                    }
                  ],
                  "payment": {
                    "instruments": [
                      {
                        "id": "balance",
                        "handler_id": "balance",
                        "type": "account_balance",
                        "selected": true
                      }
                    ],
                    "declared_method": "BALANCE"
                  },
                  "continue_url": "https://app.quanticdata.io/plans?network=RESIDENTIAL&utm_source=agent&utm_medium=ucp&utm_campaign=checkout-session&agent_checkout=chk_7d3f0a9b2c4e1f6a8b9c0d1e",
                  "links": [
                    {
                      "type": "privacy_policy",
                      "url": "https://quanticdata.io/privacy"
                    },
                    {
                      "type": "terms_of_service",
                      "url": "https://quanticdata.io/terms"
                    }
                  ],
                  "messages": [
                    {
                      "type": "info",
                      "code": "balance_available",
                      "content": "The account balance covers this checkout. Complete it with POST /checkout-sessions/chk_7d3f0a9b2c4e1f6a8b9c0d1e/complete and payment.instruments[0].handler_id = \"balance\" (0% VAT)."
                    },
                    {
                      "type": "info",
                      "code": "vat_rule",
                      "content": "Totals carry 0% VAT (balance or crypto). Paying by card or PayPal on the dashboard adds 22% VAT."
                    }
                  ],
                  "created_at": "2026-10-26T12:00:00.000Z",
                  "updated_at": "2026-10-26T12:00:00.000Z"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Unknown session, or not this account's.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UcpErrorDocument"
                },
                "example": {
                  "ucp": {
                    "version": "2026-08-25",
                    "status": "error"
                  },
                  "messages": [
                    {
                      "type": "error",
                      "code": "not_found",
                      "content": "Unknown checkout session.",
                      "severity": "fatal"
                    }
                  ]
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X GET 'https://api.quanticdata.io/v1/agent/ucp/checkout-sessions/ID' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.get(\n    'https://api.quanticdata.io/v1/agent/ucp/checkout-sessions/ID',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/agent/ucp/checkout-sessions/ID\", {\n  method: \"GET\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/agent/ucp/checkout-sessions/ID');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'GET',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      },
      "put": {
        "operationId": "ucpUpdateCheckout",
        "tags": [
          "Agents"
        ],
        "summary": "Change the declared payment method or the buyer email",
        "description": "Update Checkout (whole-document replacement, as the REST binding). The only things that can change are `payment_method` (which recomputes VAT and the status) and `buyer.email`. The plan is locked: a different `line_items[0].item.id` answers 400 `plan_locked`, open another session instead. A `completed` or `canceled` session answers 409 `session_closed`. Authentication: the API key of the buying account, as `Authorization: Bearer` or `X-API-Key`.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Session id (`chk_` + 24 hex). A session of another account answers 404.",
            "schema": {
              "type": "string",
              "pattern": "^chk_[0-9a-f]{24}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true,
                "properties": {
                  "line_items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "item": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string",
                              "description": "Must equal the session's plan."
                            }
                          }
                        }
                      }
                    }
                  },
                  "buyer": {
                    "type": "object",
                    "properties": {
                      "email": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "format": "email"
                      }
                    }
                  },
                  "payment_method": {
                    "type": "string",
                    "enum": [
                      "BALANCE",
                      "NOWPAYMENTS",
                      "PAYPAL",
                      "PAYPAL_CARD"
                    ]
                  }
                }
              },
              "example": {
                "payment_method": "PAYPAL_CARD",
                "buyer": {
                  "email": "user@example.com"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated session.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UcpCheckoutSession"
                },
                "example": {
                  "ucp": {
                    "version": "2026-08-25",
                    "status": "success",
                    "capabilities": {
                      "dev.ucp.shopping.checkout": [
                        {
                          "version": "2026-08-25",
                          "spec": "https://ucp.dev/2026-08-25/specification/shopping/checkout/",
                          "schema": "https://ucp.dev/2026-08-25/schemas/shopping/checkout.json"
                        }
                      ]
                    },
                    "payment_handlers": {
                      "io.quanticdata.io.balance": [
                        {
                          "id": "balance",
                          "version": "2026-10-08",
                          "spec": "https://quanticdata.io/docs/#section/Agent-checkout-(UCP)",
                          "schema": "https://api.quanticdata.io/v1/agent/ucp/handlers/balance.json",
                          "available_instruments": [
                            {
                              "type": "account_balance",
                              "currency": "USD"
                            }
                          ]
                        }
                      ]
                    }
                  },
                  "id": "chk_7d3f0a9b2c4e1f6a8b9c0d1e",
                  "status": "ready_for_complete",
                  "currency": "USD",
                  "expires_at": "2026-10-26T18:00:00.000Z",
                  "line_items": [
                    {
                      "id": "li_pln_3e7a",
                      "item": {
                        "id": "pln_3e7a",
                        "title": "Residential - Quark (5GB)",
                        "price": 1200
                      },
                      "quantity": 1,
                      "totals": [
                        {
                          "type": "subtotal",
                          "amount": 1200
                        },
                        {
                          "type": "total",
                          "amount": 1200
                        }
                      ]
                    }
                  ],
                  "totals": [
                    {
                      "type": "subtotal",
                      "amount": 1200
                    },
                    {
                      "type": "total",
                      "amount": 1200
                    }
                  ],
                  "payment": {
                    "instruments": [
                      {
                        "id": "balance",
                        "handler_id": "balance",
                        "type": "account_balance",
                        "selected": true
                      }
                    ],
                    "declared_method": "BALANCE"
                  },
                  "continue_url": "https://app.quanticdata.io/plans?network=RESIDENTIAL&utm_source=agent&utm_medium=ucp&utm_campaign=checkout-session&agent_checkout=chk_7d3f0a9b2c4e1f6a8b9c0d1e",
                  "links": [
                    {
                      "type": "privacy_policy",
                      "url": "https://quanticdata.io/privacy"
                    },
                    {
                      "type": "terms_of_service",
                      "url": "https://quanticdata.io/terms"
                    }
                  ],
                  "messages": [
                    {
                      "type": "info",
                      "code": "balance_available",
                      "content": "The account balance covers this checkout. Complete it with POST /checkout-sessions/chk_7d3f0a9b2c4e1f6a8b9c0d1e/complete and payment.instruments[0].handler_id = \"balance\" (0% VAT)."
                    },
                    {
                      "type": "info",
                      "code": "vat_rule",
                      "content": "Totals carry 0% VAT (balance or crypto). Paying by card or PayPal on the dashboard adds 22% VAT."
                    }
                  ],
                  "created_at": "2026-10-26T12:00:00.000Z",
                  "updated_at": "2026-10-26T12:00:00.000Z"
                }
              }
            }
          },
          "400": {
            "description": "`plan_locked`, `invalid_payment_method` or `invalid_json`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UcpErrorDocument"
                },
                "example": {
                  "ucp": {
                    "version": "2026-08-25",
                    "status": "error"
                  },
                  "messages": [
                    {
                      "type": "error",
                      "code": "plan_locked",
                      "content": "The plan of a session cannot change: create a new session.",
                      "severity": "fatal",
                      "path": "$.line_items[0].item.id"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Unknown session.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UcpErrorDocument"
                },
                "example": {
                  "ucp": {
                    "version": "2026-08-25",
                    "status": "error"
                  },
                  "messages": [
                    {
                      "type": "error",
                      "code": "not_found",
                      "content": "Unknown checkout session.",
                      "severity": "fatal"
                    }
                  ]
                }
              }
            }
          },
          "409": {
            "description": "The session is completed or canceled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UcpErrorDocument"
                },
                "example": {
                  "ucp": {
                    "version": "2026-08-25",
                    "status": "error"
                  },
                  "messages": [
                    {
                      "type": "error",
                      "code": "session_closed",
                      "content": "Session is completed.",
                      "severity": "fatal"
                    }
                  ]
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X PUT 'https://api.quanticdata.io/v1/agent/ucp/checkout-sessions/ID' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"payment_method\":\"PAYPAL_CARD\",\"buyer\":{\"email\":\"user@example.com\"}}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.put(\n    'https://api.quanticdata.io/v1/agent/ucp/checkout-sessions/ID',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\n        \"payment_method\": \"PAYPAL_CARD\",\n        \"buyer\": {\n            \"email\": \"user@example.com\"\n        }\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/agent/ucp/checkout-sessions/ID\", {\n  method: \"PUT\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"payment_method\": \"PAYPAL_CARD\",\n    \"buyer\": {\n      \"email\": \"user@example.com\"\n    }\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/agent/ucp/checkout-sessions/ID');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'PUT',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'payment_method' => 'PAYPAL_CARD',\n    'buyer' => [\n      'email' => 'user@example.com'\n    ]\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/agent/ucp/checkout-sessions/{id}/complete": {
      "post": {
        "operationId": "ucpCompleteCheckout",
        "tags": [
          "Agents"
        ],
        "summary": "Pay the session from the account balance",
        "description": "Complete Checkout. The only instrument an agent holds is the prepaid balance of the account that owns the API key: pass `payment.instruments[0].handler_id = \"balance\"`. The session is then paid through the same path as `POST /public/purchase`: the balance is charged (0% VAT), the order and the paid invoice are created and the plan is activated in the same call; `order.id` is the `orderId` for `POST /public/proxies/generate`. Outcomes, all with HTTP 200 and the session document: `completed` with `order` and the message `order_created`; `ready_for_complete` again with an `error` message `payment_failed` (the balance no longer covers the total: top up at the dashboard or hand `continue_url` to the person) or `purchase_failed` (recoverable, `content` says why); unchanged with `payment_instrument_unavailable` when another handler was passed (card, PayPal and crypto are paid by a person at `continue_url`). A session that is already `completed` answers 200 with the same order, so retrying is safe; a `canceled` one answers 409 `session_closed`. Authentication: the API key of the buying account, as `Authorization: Bearer` or `X-API-Key`.",
        "x-price-key": null,
        "x-pricing-note": "Charges the plan's `amount` to the balance, 0% VAT. Nothing is charged on a failed outcome.",
        "x-rate-limit": "per-tier",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Session id (`chk_` + 24 hex). A session of another account answers 404.",
            "schema": {
              "type": "string",
              "pattern": "^chk_[0-9a-f]{24}$"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true,
                "properties": {
                  "payment": {
                    "type": "object",
                    "properties": {
                      "instruments": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "handler_id": {
                              "type": "string",
                              "const": "balance"
                            },
                            "type": {
                              "type": "string",
                              "const": "account_balance"
                            },
                            "selected": {
                              "type": "boolean"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              },
              "example": {
                "payment": {
                  "instruments": [
                    {
                      "handler_id": "balance",
                      "type": "account_balance",
                      "selected": true
                    }
                  ]
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The session after the attempt: `completed` with `order`, or back to `ready_for_complete` with an `error` message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UcpCheckoutSession"
                },
                "example": {
                  "ucp": {
                    "version": "2026-08-25",
                    "status": "success",
                    "capabilities": {
                      "dev.ucp.shopping.checkout": [
                        {
                          "version": "2026-08-25",
                          "spec": "https://ucp.dev/2026-08-25/specification/shopping/checkout/",
                          "schema": "https://ucp.dev/2026-08-25/schemas/shopping/checkout.json"
                        }
                      ]
                    },
                    "payment_handlers": {
                      "io.quanticdata.io.balance": [
                        {
                          "id": "balance",
                          "version": "2026-10-08",
                          "spec": "https://quanticdata.io/docs/#section/Agent-checkout-(UCP)",
                          "schema": "https://api.quanticdata.io/v1/agent/ucp/handlers/balance.json",
                          "available_instruments": [
                            {
                              "type": "account_balance",
                              "currency": "USD"
                            }
                          ]
                        }
                      ]
                    }
                  },
                  "id": "chk_7d3f0a9b2c4e1f6a8b9c0d1e",
                  "status": "completed",
                  "currency": "USD",
                  "expires_at": "2026-10-26T18:00:00.000Z",
                  "line_items": [
                    {
                      "id": "li_pln_3e7a",
                      "item": {
                        "id": "pln_3e7a",
                        "title": "Residential - Quark (5GB)",
                        "price": 1200
                      },
                      "quantity": 1,
                      "totals": [
                        {
                          "type": "subtotal",
                          "amount": 1200
                        },
                        {
                          "type": "total",
                          "amount": 1200
                        }
                      ]
                    }
                  ],
                  "totals": [
                    {
                      "type": "subtotal",
                      "amount": 1200
                    },
                    {
                      "type": "total",
                      "amount": 1200
                    }
                  ],
                  "payment": {
                    "instruments": [
                      {
                        "id": "balance",
                        "handler_id": "balance",
                        "type": "account_balance",
                        "selected": true
                      }
                    ],
                    "declared_method": "BALANCE"
                  },
                  "continue_url": "https://app.quanticdata.io/plans?network=RESIDENTIAL&utm_source=agent&utm_medium=ucp&utm_campaign=checkout-session&agent_checkout=chk_7d3f0a9b2c4e1f6a8b9c0d1e",
                  "links": [
                    {
                      "type": "privacy_policy",
                      "url": "https://quanticdata.io/privacy"
                    },
                    {
                      "type": "terms_of_service",
                      "url": "https://quanticdata.io/terms"
                    }
                  ],
                  "messages": [
                    {
                      "type": "info",
                      "code": "vat_rule",
                      "content": "Totals carry 0% VAT (balance or crypto). Paying by card or PayPal on the dashboard adds 22% VAT."
                    },
                    {
                      "type": "info",
                      "code": "order_created",
                      "content": "Paid from the account balance. The proxy plan is active: see the order permalink."
                    }
                  ],
                  "created_at": "2026-10-26T12:00:00.000Z",
                  "updated_at": "2026-10-26T12:01:00.000Z",
                  "order": {
                    "id": "ord_8c21",
                    "permalink_url": "https://app.quanticdata.io/proxies"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Unknown session.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UcpErrorDocument"
                },
                "example": {
                  "ucp": {
                    "version": "2026-08-25",
                    "status": "error"
                  },
                  "messages": [
                    {
                      "type": "error",
                      "code": "not_found",
                      "content": "Unknown checkout session.",
                      "severity": "fatal"
                    }
                  ]
                }
              }
            }
          },
          "409": {
            "description": "The session is canceled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UcpErrorDocument"
                },
                "example": {
                  "ucp": {
                    "version": "2026-08-25",
                    "status": "error"
                  },
                  "messages": [
                    {
                      "type": "error",
                      "code": "session_closed",
                      "content": "Session is canceled.",
                      "severity": "fatal"
                    }
                  ]
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/agent/ucp/checkout-sessions/ID/complete' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"payment\":{\"instruments\":[{\"handler_id\":\"balance\",\"type\":\"account_balance\",\"selected\":true}]}}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/agent/ucp/checkout-sessions/ID/complete',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\n        \"payment\": {\n            \"instruments\": [\n                {\n                    \"handler_id\": \"balance\",\n                    \"type\": \"account_balance\",\n                    \"selected\": true\n                }\n            ]\n        }\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/agent/ucp/checkout-sessions/ID/complete\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"payment\": {\n      \"instruments\": [\n        {\n          \"handler_id\": \"balance\",\n          \"type\": \"account_balance\",\n          \"selected\": true\n        }\n      ]\n    }\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/agent/ucp/checkout-sessions/ID/complete');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'payment' => [\n      'instruments' => [[\n        'handler_id' => 'balance',\n        'type' => 'account_balance',\n        'selected' => true\n      ]]\n    ]\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/agent/ucp/checkout-sessions/{id}/cancel": {
      "post": {
        "operationId": "ucpCancelCheckout",
        "tags": [
          "Agents"
        ],
        "summary": "Cancel a checkout session",
        "description": "Cancel Checkout. A `completed` session cannot be cancelled (409 `already_completed`); cancelling twice is harmless. Nothing is refunded here because nothing was charged. Authentication: the API key of the buying account, as `Authorization: Bearer` or `X-API-Key`.",
        "x-price-key": null,
        "x-rate-limit": "per-tier",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Session id (`chk_` + 24 hex). A session of another account answers 404.",
            "schema": {
              "type": "string",
              "pattern": "^chk_[0-9a-f]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The session, now `canceled`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UcpCheckoutSession"
                },
                "example": {
                  "ucp": {
                    "version": "2026-08-25",
                    "status": "success",
                    "capabilities": {
                      "dev.ucp.shopping.checkout": [
                        {
                          "version": "2026-08-25",
                          "spec": "https://ucp.dev/2026-08-25/specification/shopping/checkout/",
                          "schema": "https://ucp.dev/2026-08-25/schemas/shopping/checkout.json"
                        }
                      ]
                    },
                    "payment_handlers": {
                      "io.quanticdata.io.balance": [
                        {
                          "id": "balance",
                          "version": "2026-10-08",
                          "spec": "https://quanticdata.io/docs/#section/Agent-checkout-(UCP)",
                          "schema": "https://api.quanticdata.io/v1/agent/ucp/handlers/balance.json",
                          "available_instruments": [
                            {
                              "type": "account_balance",
                              "currency": "USD"
                            }
                          ]
                        }
                      ]
                    }
                  },
                  "id": "chk_7d3f0a9b2c4e1f6a8b9c0d1e",
                  "status": "canceled",
                  "currency": "USD",
                  "expires_at": "2026-10-26T18:00:00.000Z",
                  "line_items": [
                    {
                      "id": "li_pln_3e7a",
                      "item": {
                        "id": "pln_3e7a",
                        "title": "Residential - Quark (5GB)",
                        "price": 1200
                      },
                      "quantity": 1,
                      "totals": [
                        {
                          "type": "subtotal",
                          "amount": 1200
                        },
                        {
                          "type": "total",
                          "amount": 1200
                        }
                      ]
                    }
                  ],
                  "totals": [
                    {
                      "type": "subtotal",
                      "amount": 1200
                    },
                    {
                      "type": "total",
                      "amount": 1200
                    }
                  ],
                  "payment": {
                    "instruments": [
                      {
                        "id": "balance",
                        "handler_id": "balance",
                        "type": "account_balance",
                        "selected": true
                      }
                    ],
                    "declared_method": "BALANCE"
                  },
                  "continue_url": "https://app.quanticdata.io/plans?network=RESIDENTIAL&utm_source=agent&utm_medium=ucp&utm_campaign=checkout-session&agent_checkout=chk_7d3f0a9b2c4e1f6a8b9c0d1e",
                  "links": [
                    {
                      "type": "privacy_policy",
                      "url": "https://quanticdata.io/privacy"
                    },
                    {
                      "type": "terms_of_service",
                      "url": "https://quanticdata.io/terms"
                    }
                  ],
                  "messages": [],
                  "created_at": "2026-10-26T12:00:00.000Z",
                  "updated_at": "2026-10-26T12:00:00.000Z"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Unknown session.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UcpErrorDocument"
                },
                "example": {
                  "ucp": {
                    "version": "2026-08-25",
                    "status": "error"
                  },
                  "messages": [
                    {
                      "type": "error",
                      "code": "not_found",
                      "content": "Unknown checkout session.",
                      "severity": "fatal"
                    }
                  ]
                }
              }
            }
          },
          "409": {
            "description": "Already completed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UcpErrorDocument"
                },
                "example": {
                  "ucp": {
                    "version": "2026-08-25",
                    "status": "error"
                  },
                  "messages": [
                    {
                      "type": "error",
                      "code": "already_completed",
                      "content": "A completed checkout cannot be canceled.",
                      "severity": "fatal"
                    }
                  ]
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/agent/ucp/checkout-sessions/ID/cancel' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/agent/ucp/checkout-sessions/ID/cancel',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/agent/ucp/checkout-sessions/ID/cancel\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\"\n  }\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/agent/ucp/checkout-sessions/ID/cancel');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY'],\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    },
    "/agent/contact": {
      "post": {
        "operationId": "agentContact",
        "tags": [
          "Agents"
        ],
        "summary": "Contact the team as an agent (higher credit limit, enterprise, dataset)",
        "description": "The contact gate for agents. Call it when a 402 carries an `escalation` object (`reason` `amount_above_limit`: the call needs more credit than one card top-up may add, `limit_usd`; `budget_reached`: the account's monthly spend cap is reached), or when the person you work for wants an enterprise plan or a dataset. Send that person's email address: the team answers there by email with a scope and a limit; nothing is charged and nothing changes on the account until they agree. Same API key as every other call (the one created by the agent registration too); no captcha, no browser signals. The message reaches the same inbox as the contact form on the site, marked as coming from an AI agent together with the account and API key ids, so quote the `payload` of the 402 and the numbers you need. One request is enough: a second one with the same content is not answered faster, and the limits below are low on purpose. Errors use the Data API envelope; success is a small receipt document (`202`). Also served at `https://app.quanticdata.io/api/v1/agent/contact`. A person can make the same request at `https://quanticdata.io/enterprise/contact/`.",
        "x-price-key": null,
        "x-rate-limit": "Per API key: 3 requests an hour and 10 a day. Per IP address: 10 a day. Beyond that 429 with `Retry-After` and `payload.code` `rate_limited`; the earlier message is already with the team, do not resend it.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentContactRequest"
              },
              "example": {
                "email": "dana.rossi@example.com",
                "name": "Research agent (for Dana Rossi)",
                "subject": "Higher top-up limit for a weekly SERP job",
                "message": "Weekly job: about 40,000 Google searches in IT and DE, run on Mondays. The 402 estimated $1,812.50 against a balance of $12.50; one top-up is capped at $1,000. Expected monthly spend about $3,500. Please set a limit that lets the job run in one call.",
                "company": "Acme Ltd",
                "company_url": "https://acme.example",
                "expected_monthly_usd": 3500,
                "need": "credit_limit"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Received. The team answers the person by email; nothing is charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentContactReceived"
                },
                "example": {
                  "type": "response",
                  "reference": "cmhcontact0001x9k2agent001",
                  "message": "Request received by the QuanticData team (reference cmhcontact0001x9k2agent001).",
                  "what_happens_next": "The team answers by email to dana.rossi@example.com with a scope; nothing is charged."
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid field (`payload.code` `invalid_request`, `payload.field` names it), or a temporary mailbox (`invalid_email`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "examples": {
                  "invalid_request": {
                    "value": {
                      "type": "error",
                      "message": "\"subject\" must be at most 140 characters.",
                      "payload": {
                        "code": "invalid_request",
                        "field": "subject"
                      }
                    }
                  },
                  "invalid_email": {
                    "value": {
                      "type": "error",
                      "message": "Temporary mailboxes are not accepted: give the permanent email address of the person the team should answer to.",
                      "payload": {
                        "code": "invalid_email",
                        "field": "email"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "A contact cap was reached (per key or per IP). The earlier message is already with the team.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "type": "error",
                  "message": "Too many contact requests (3 per hour per API key). The team already has your earlier message and answers by email; do not resend it. Retry after 1800 seconds if you have something new to add.",
                  "payload": {
                    "code": "rate_limited",
                    "scope": "per hour per API key",
                    "limit": 3,
                    "reset_at": "2026-10-29T18:30:00.000Z",
                    "retry_after": 1800
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "curl",
            "source": "curl -X POST 'https://api.quanticdata.io/v1/agent/contact' \\\n  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"email\":\"dana.rossi@example.com\",\"name\":\"Research agent (for Dana Rossi)\",\"subject\":\"Higher top-up limit for a weekly SERP job\",\"message\":\"Weekly job: about 40,000 Google searches in IT and DE, run on Mondays. The 402 estimated $1,812.50 against a balance of $12.50; one top-up is capped at $1,000. Expected monthly spend about $3,500. Please set a limit that lets the job run in one call.\",\"company\":\"Acme Ltd\",\"company_url\":\"https://acme.example\",\"expected_monthly_usd\":3500,\"need\":\"credit_limit\"}'",
            "x-id": "curl"
          },
          {
            "lang": "python",
            "label": "Python (requests)",
            "source": "import requests\n\nr = requests.post(\n    'https://api.quanticdata.io/v1/agent/contact',\n    headers={\"Authorization\": \"Bearer qd_live_YOUR_API_KEY\"},\n    json={\n        \"email\": \"dana.rossi@example.com\",\n        \"name\": \"Research agent (for Dana Rossi)\",\n        \"subject\": \"Higher top-up limit for a weekly SERP job\",\n        \"message\": \"Weekly job: about 40,000 Google searches in IT and DE, run on Mondays. The 402 estimated $1,812.50 against a balance of $12.50; one top-up is capped at $1,000. Expected monthly spend about $3,500. Please set a limit that lets the job run in one call.\",\n        \"company\": \"Acme Ltd\",\n        \"company_url\": \"https://acme.example\",\n        \"expected_monthly_usd\": 3500,\n        \"need\": \"credit_limit\"\n    },\n    timeout=120,\n)\ndata = r.json()\nif data[\"type\"] != \"response\":\n    raise SystemExit(data[\"message\"])\nprint(data[\"payload\"])",
            "x-id": "python"
          },
          {
            "lang": "javascript",
            "label": "Node (fetch)",
            "source": "const res = await fetch(\"https://api.quanticdata.io/v1/agent/contact\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer qd_live_YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"email\": \"dana.rossi@example.com\",\n    \"name\": \"Research agent (for Dana Rossi)\",\n    \"subject\": \"Higher top-up limit for a weekly SERP job\",\n    \"message\": \"Weekly job: about 40,000 Google searches in IT and DE, run on Mondays. The 402 estimated $1,812.50 against a balance of $12.50; one top-up is capped at $1,000. Expected monthly spend about $3,500. Please set a limit that lets the job run in one call.\",\n    \"company\": \"Acme Ltd\",\n    \"company_url\": \"https://acme.example\",\n    \"expected_monthly_usd\": 3500,\n    \"need\": \"credit_limit\"\n  })\n});\nconst data = await res.json();\nif (data.type !== \"response\") throw new Error(data.message);\nconsole.log(data.payload);",
            "x-id": "node"
          },
          {
            "lang": "php",
            "label": "PHP (curl)",
            "source": "<?php\n$ch = curl_init('https://api.quanticdata.io/v1/agent/contact');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'POST',\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'email' => 'dana.rossi@example.com',\n    'name' => 'Research agent (for Dana Rossi)',\n    'subject' => 'Higher top-up limit for a weekly SERP job',\n    'message' => 'Weekly job: about 40,000 Google searches in IT and DE, run on Mondays. The 402 estimated $1,812.50 against a balance of $12.50; one top-up is capped at $1,000. Expected monthly spend about $3,500. Please set a limit that lets the job run in one call.',\n    'company' => 'Acme Ltd',\n    'company_url' => 'https://acme.example',\n    'expected_monthly_usd' => 3500,\n    'need' => 'credit_limit'\n  ]),\n]);\n$raw = curl_exec($ch);\ncurl_close($ch);\n$data = json_decode($raw, true);\nif ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }\nprint_r($data['payload']);",
            "x-id": "php"
          }
        ]
      }
    }
  },
  "x-guides": [
    {
      "id": "buy-proxies",
      "title": "Buy and use proxies via the API",
      "md": "Four calls take a script or an agent from an API key to working proxies, paid from the wallet balance. Top up the balance in the dashboard first: the API pays from the balance only (0% VAT).\n\n| Step | Call | What you keep |\n| --- | --- | --- |\n| 1. Pick a plan | `GET /public/plans?planType=residentialpremium` | `plans[].id`, `amount` (USD) |\n| 2. Check the balance | `GET /public/balance` | `balance` (USD) |\n| 3. Buy | `POST /public/purchase` with `{\"planId\": \"…\"}` | `order.id` |\n| 4. Get proxy lines | `POST /public/proxies/generate` with `{\"orderId\": \"…\"}` | `proxies[]` |\n| 5. Use them | any HTTP client | |\n\nThe purchase charges the balance and activates the plan in the same call. Responses to handle: 400 `Insufficient balance` (nothing charged, top up), 422 `NOT_DELIVERED_REFUNDED` (not delivered, the amount is back on the balance, buy again), 409 `PAYMENT_UNDER_REVIEW` (do not buy again, contact support). Do not resend a purchase that timed out: look for it in `GET /public/orders` first. Location values for step 4 (state, city, ISP slugs) come from the endpoints under Proxy locations.\n\n```bash\nAPI=https://api.quanticdata.io/v1\nKEY=qd_live_YOUR_API_KEY\n\n# 1. plans of one type, cheapest first\ncurl -s \"$API/public/plans?planType=residentialpremium\" -H \"Authorization: Bearer $KEY\"\n\n# 2. balance\ncurl -s \"$API/public/balance\" -H \"Authorization: Bearer $KEY\"\n\n# 3. buy: charges the balance, returns order.id\ncurl -s -X POST \"$API/public/purchase\" -H \"Authorization: Bearer $KEY\" \\\n  -H \"Content-Type: application/json\" -d '{\"planId\":\"PLAN_ID\"}'\n\n# 4. two sticky US lines, same IP for 10 minutes each\ncurl -s -X POST \"$API/public/proxies/generate\" -H \"Authorization: Bearer $KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"orderId\":\"ORDER_ID\",\"country\":\"us\",\"rotation\":\"sticky\",\"sessionTime\":10,\"quantity\":2,\"format\":\"http://user:pass@host:port\"}'\n\n# 5. use a line\ncurl -x \"PROXY_LINE\" https://ipinfo.io/json\n```\n\nThe same flow in Python, stopping before the purchase when the balance is too low:\n\n```python\nimport os\nimport requests\n\nAPI = \"https://api.quanticdata.io/v1\"\nHEADERS = {\"Authorization\": f\"Bearer {os.environ['API_KEY']}\"}\n\ndef call(method, path, **kwargs):\n    r = requests.request(method, API + path, headers=HEADERS, timeout=120, **kwargs)\n    body = r.json()\n    if body.get(\"type\") == \"error\":\n        raise RuntimeError(f\"{r.status_code} {body['message']} {body.get('payload')}\")\n    return body[\"payload\"]\n\nplans = call(\"GET\", \"/public/plans\", params={\"planType\": \"residentialpremium\"})[\"plans\"]\nplan = min(plans, key=lambda p: p[\"bandwidthGB\"])\nif call(\"GET\", \"/public/balance\")[\"balance\"] < plan[\"amount\"]:\n    raise SystemExit(\"Top up the balance in the dashboard first.\")\n\norder_id = call(\"POST\", \"/public/purchase\", json={\"planId\": plan[\"id\"]})[\"order\"][\"id\"]\n\nlines = call(\"POST\", \"/public/proxies/generate\", json={\n    \"orderId\": order_id, \"country\": \"us\", \"rotation\": \"sticky\",\n    \"sessionTime\": 10, \"quantity\": 2, \"format\": \"http://user:pass@host:port\",\n})[\"proxies\"]\n\nproxy = lines[0]\nprint(requests.get(\"https://ipinfo.io/json\", proxies={\"http\": proxy, \"https\": proxy}, timeout=30).json())\n```\n\nKeep `order_id`: it is the plan's id for later `generate` and whitelist calls (`GET /public/proxies` lists it with the bandwidth left). Buying again creates a new plan with new credentials; adding GB or renewing is done in the dashboard. Premium ISP dedicated IPs follow their own flow with an `Idempotency-Key` (see Premium ISP)."
    },
    {
      "id": "agent-registration",
      "title": "Agent registration (verified email)",
      "md": "An AI agent can open an account and get an API key by itself, with the person it works for only reading a 6-digit code from their mailbox. No password, no browser, no captcha. The machine-readable description is the `agent_auth` block of `https://app.quanticdata.io/.well-known/oauth-authorization-server`; the plain-text version is `https://quanticdata.io/auth.md`.\n\n| Step | Call | What you keep |\n| --- | --- | --- |\n| 1. Discover | `GET https://app.quanticdata.io/.well-known/oauth-authorization-server` | `agent_auth.register_uri`, `agent_auth.claim_uri` |\n| 2. Register | `POST /agent/auth` with `{\"method\":\"verified_email\",\"email\":\"…\",\"agent\":{\"name\":\"…\"}}` | `claim_uri`, `expires_in` (600 s) |\n| 3. Ask the user | The code is in their mailbox, subject \"… is your QuanticData verification code — an AI agent asked to register\" | the 6 digits |\n| 4. Claim | `POST /agent/auth/claim` with `{\"email\":\"…\",\"code\":\"……\"}` | `api_key` (shown once) |\n\nBefore step 2, tell the user which service you are registering with. The answer to step 2 is the same whether or not the email already has an account: the code goes to the mailbox owner, and the claim adds a key to the existing account instead of opening a new one (`account_status: \"existing\"`). A new account starts on the standard pay-as-you-go tier with the free monthly allowance; the person signs in to the dashboard through the password reset link.\n\n```bash\nAPP=https://app.quanticdata.io/api/v1\n\n# 2. register: sends the code\ncurl -s -X POST \"$APP/agent/auth\" -H \"Content-Type: application/json\" \\\n  -d '{\"method\":\"verified_email\",\"email\":\"user@example.com\",\"agent\":{\"name\":\"Research agent\",\"url\":\"https://example.com/agent\"}}'\n\n# 4. claim: returns the key once\ncurl -s -X POST \"$APP/agent/auth/claim\" -H \"Content-Type: application/json\" \\\n  -d '{\"email\":\"user@example.com\",\"code\":\"482913\"}'\n```\n\nResponses to handle: 400 `invalid_code` (ask again, `attempts_remaining` says how many tries are left), 410 `claim_expired` (start again at step 2), 422 `invalid_email` (temporary mailbox: ask for a permanent address), 428 `human_verification_required` and 503 `agent_registration_disabled` (ask the person to register at `register_human` and hand you a key from the API keys page), 429 `rate_limited` (wait `retry_after` seconds). Store the key in an environment variable and never print it; the person can rotate or revoke it on the dashboard at any time."
    },
    {
      "id": "agent-checkout",
      "title": "Agent checkout (UCP)",
      "md": "An agent can buy a proxy plan for its user in the Universal Commerce Protocol shape (ucp.dev, capability `dev.ucp.shopping.checkout`, REST binding): it opens a checkout session for one plan, reads the real total, and either pays it from the account balance or hands the person a link to pay by card, PayPal or crypto on the dashboard. Discovery: `https://api.quanticdata.io/.well-known/ucp` (also on the dashboard host and the site). The plainer, non-UCP way to do the same from the balance is `POST /public/purchase` (see \"Buy and use proxies via the API\").\n\n| Step | Call | What you keep |\n| --- | --- | --- |\n| 1. Pick a plan | `GET /public/plans?planType=residentialpremium` | `plans[].id`, `amount` (USD) |\n| 2. Open a session | `POST /agent/ucp/checkout-sessions` with `{\"line_items\":[{\"item\":{\"id\":\"…\"},\"quantity\":1}],\"payment_method\":\"BALANCE\"}` and an `Idempotency-Key` header | `id`, `status`, `totals`, `continue_url` |\n| 3a. Balance covers it (`ready_for_complete`) | `POST /agent/ucp/checkout-sessions/{id}/complete` with `{\"payment\":{\"instruments\":[{\"handler_id\":\"balance\",\"type\":\"account_balance\",\"selected\":true}]}}` | `order.id` |\n| 3b. It does not (`requires_escalation`) | Give the person `continue_url`; poll `GET /agent/ucp/checkout-sessions/{id}` until `completed` | `order.id` |\n| 4. Get proxy lines | `POST /public/proxies/generate` with `{\"orderId\":\"…\"}` | `proxies[]` |\n\nTotals are USD cents. VAT follows the same rule as the human checkout: 0% when the session is paid from the balance or in crypto, 22% when a person pays by card or PayPal (declare `payment_method` `PAYPAL` or `PAYPAL_CARD` to see that total in advance). One session holds one plan with quantity 1; ISP plans are configured per order and are sold through the Premium ISP endpoints or the dashboard. Sessions expire after 6 hours; a completed session keeps answering 200 with its order, so a retry never buys twice.\n\n```bash\nAPI=https://api.quanticdata.io/v1\nKEY=qd_live_YOUR_API_KEY\n\n# 2. open the session (idempotent on the key)\ncurl -s -X POST \"$API/agent/ucp/checkout-sessions\" -H \"Authorization: Bearer $KEY\" \\\n  -H \"Content-Type: application/json\" -H \"Idempotency-Key: order-2026-10-26-001\" \\\n  -d '{\"line_items\":[{\"item\":{\"id\":\"PLAN_ID\"},\"quantity\":1}],\"payment_method\":\"BALANCE\"}'\n\n# 3a. pay from the balance when status is ready_for_complete\ncurl -s -X POST \"$API/agent/ucp/checkout-sessions/SESSION_ID/complete\" -H \"Authorization: Bearer $KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"payment\":{\"instruments\":[{\"handler_id\":\"balance\",\"type\":\"account_balance\",\"selected\":true}]}}'\n\n# 3b. otherwise poll after the person has paid at continue_url\ncurl -s \"$API/agent/ucp/checkout-sessions/SESSION_ID\" -H \"Authorization: Bearer $KEY\"\n```\n\nRead `messages[]` on every document: `balance_available` means you can complete, `requires_buyer_review` means a person has to pay, `payment_failed` means the balance no longer covers the total (nothing was charged), `order_created` confirms the purchase. Never ask the person for card details: the agent never handles a card, the dashboard does."
    }
  ]
}