# Python API Examples

> QuanticData API reference with every example in Python: 101 endpoints, parameters, request and response samples, error codes, rate limits and prices as of…

- Authentication
- Buy and use proxies via the API
- Agent registration (verified email)
- Agent checkout (UCP)
- Errors and status codes
- Rate limits and tiers
- Pricing per endpoint
- MCP server
- Data API
  - Scrape
    - post · Scrape one URL
  - Search
    - post · Structured search results
    - post · Start a multi-page search job
    - get · Poll a multi-page search job
    - del · Cancel a multi-page search job
  - Map & Crawl
    - post · Discover a site's URLs
    - post · Start a site crawl
    - get · Poll a crawl job
    - del · Cancel a crawl job
  - Batch
    - post · Scrape many URLs asynchronously
    - get · Poll a batch job
    - del · Cancel a batch job
  - Video
    - post · Read a YouTube video for a model
  - Web Unlocker
    - Download a client
    - Forward proxy
    - Batch
    - Errors
    - Coming from another unlocker
    - post · Replay a request through the Web Unlocker
    - post · Unlock many URLs asynchronously
    - get · Poll an unlock batch
    - del · Cancel an unlock batch
    - get · Download the unlocker CA certificate
    - get · Price per GB, packs and options on sale
    - get · Health of the Web Unlocker from our canary
- AI
  - AI extraction
    - post · Natural-language scraping agent
    - post · AI Places Finder
    - post · AI Shopping Finder
  - AI visibility
    - post · AI visibility audit
  - SEO audit
    - post · No-JS vs rendered SEO audit
- Collectors & datasets
  - Collectors
    - get · Collector catalog
    - get · One collector
    - post · Run a collector
    - get · Your collector runs
    - get · One run with its rows
  - Datasets
    - get · Your recent dataset runs
    - post · Build a dataset from a prompt
    - get · Poll a dataset job
    - del · Cancel a dataset job
    - get · Download a dataset file
    - patch · Rename a dataset run
    - del · Delete a dataset run's stored record
  - Parser presets
    - post · Generate CSS selectors with an LLM, once
    - get · List your presets
    - post · Save a parser as a preset
    - get · Read a preset
    - put · Update a preset
    - del · Delete a preset
    - post · Regenerate a preset's parser now
    - get · How well a preset still works
- Proxies
  - Proxies
    - get · List your proxy plans
    - post · Generate proxy strings for a plan
    - get · Geolocate an IP
    - get · Where your IP is, as Cloudflare sees it
    - get · List whitelisted IPs of an order
    - post · Whitelist an IP
    - del · Remove a whitelisted IP
    - post · Rotate a sticky session (new IP, same string)
    - get · List rotation links of a plan
    - post · Create rotation links
    - del · Revoke a rotation link
    - get · Call a rotation link
    - post · Call a rotation link (POST)
  - Premium ISP
    - get · List Premium ISP pools
    - get · List Premium ISP cities with stock
    - get · List the carriers (ASN) of a city
    - post · Quote a Premium ISP selection
    - get · List Premium ISP orders
    - post · Buy Premium ISP IPs from the balance
    - get · Get a Premium ISP order and its proxy lines
    - get · Quote a Premium ISP renewal
    - post · Renew a Premium ISP plan from the balance
    - get · IP swaps of a city plan
    - post · Replace one IP of a city plan
    - get · Auto-replace setting of a city plan
    - post · Switch auto-replace on or off
  - IPv6
    - get · List IPv6 speed plans
    - post · Quote an IPv6 speed plan
    - get · List IPv6 speed orders
    - post · Buy an IPv6 speed plan
    - get · Get an IPv6 speed order
  - Plans & orders
    - get · List the plans you can buy
    - post · Buy a plan from the balance
    - get · List your orders
    - get · Get the wallet balance
  - Proxy locations
    - get · List countries for a plan type
    - get · List states or regions of a country
    - get · List cities of a country or state
    - get · List ASNs for Residential Basic and Datacenter
    - get · Residential Premium location tree (geo)
    - get · Residential Premium targeting options
    - get · Mobile targeting options
    - get · Datacenter gateway locations
- Account
  - Account
    - get · Per-day usage and cost
    - get · Billing status and your price list
    - get · No-key MCP trial settings
  - Agents
    - post · Register an agent with a verified email (step 1 of 2)
    - post · Exchange the emailed code for an API key (step 2 of 2)
    - get · UCP discovery profile
    - get · JSON Schema of the balance payment instrument
    - post · Create a checkout session for one plan
    - get · Read a checkout session
    - put · Change the declared payment method or the buyer email
    - post · Pay the session from the account balance
    - post · Cancel a checkout session
    - post · Contact the team as an agent (higher credit limit, enterprise, dataset)

[API docs by Redocly](https://redocly.com/redoc/)

# QuanticData API (2026-11-11)

URL: [https://quanticdata.io/](https://quanticdata.io/) [Terms of Service](https://quanticdata.io/terms/)

Scrape, search, crawl, unlock, run collectors and build datasets — one host, one Bearer key, one JSON envelope.

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

## [section/Authentication](https://quanticdata.io/docs/python/#section/Authentication) · Authentication

Every request carries an API key in the `Authorization` header:

```http
Authorization: Bearer qd_live_…
```

`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).

Keys are created on the [API keys page](https://app.quanticdata.io/api-keys) of the dashboard; [register](https://app.quanticdata.io/register) if you do not have an account. Keys are shown once; keep them in an environment variable, never in client-side code.

Base URL: `https://api.quanticdata.io/v1` (same API on the dashboard host: `https://app.quanticdata.io/api/v1`, without the short aliases).

Machine-readable formats: [openapi.json](https://quanticdata.io/docs/openapi.json) · [openapi.yaml](https://quanticdata.io/docs/openapi.yaml) · [index.md](https://quanticdata.io/docs/index.md) (this reference as Markdown) · [llms.txt](https://quanticdata.io/docs/llms.txt).

## [section/Buy-and-use-proxies-via-the-API](https://quanticdata.io/docs/python/#section/Buy-and-use-proxies-via-the-API)Buy and use proxies via the API

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

| Step | Call | What you keep |
| --- | --- | --- |
| 1. Pick a plan | `GET /public/plans?planType=residentialpremium` | `plans[].id`, `amount` (USD) |
| 2. Check the balance | `GET /public/balance` | `balance` (USD) |
| 3. Buy | `POST /public/purchase` with `{"planId": "…"}` | `order.id` |
| 4. Get proxy lines | `POST /public/proxies/generate` with `{"orderId": "…"}` | `proxies[]` |
| 5. Use them | any HTTP client |  |

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

```bash
API=https://api.quanticdata.io/v1
KEY=qd_live_YOUR_API_KEY

# 1. plans of one type, cheapest first
curl -s "$API/public/plans?planType=residentialpremium" -H "Authorization: Bearer $KEY"

# 2. balance
curl -s "$API/public/balance" -H "Authorization: Bearer $KEY"

# 3. buy: charges the balance, returns order.id
curl -s -X POST "$API/public/purchase" -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" -d '{"planId":"PLAN_ID"}'

# 4. two sticky US lines, same IP for 10 minutes each
curl -s -X POST "$API/public/proxies/generate" -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"orderId":"ORDER_ID","country":"us","rotation":"sticky","sessionTime":10,"quantity":2,"format":"http://user:pass@host:port"}'

# 5. use a line
curl -x "PROXY_LINE" https://ipinfo.io/json
```

The same flow in Python, stopping before the purchase when the balance is too low:

```python
import os
import requests

API = "https://api.quanticdata.io/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['API_KEY']}"}

def call(method, path, **kwargs):
    r = requests.request(method, API + path, headers=HEADERS, timeout=120, **kwargs)
    body = r.json()
    if body.get("type") == "error":
        raise RuntimeError(f"{r.status_code} {body['message']} {body.get('payload')}")
    return body["payload"]

plans = call("GET", "/public/plans", params={"planType": "residentialpremium"})["plans"]
plan = min(plans, key=lambda p: p["bandwidthGB"])
if call("GET", "/public/balance")["balance"] < plan["amount"]:
    raise SystemExit("Top up the balance in the dashboard first.")

order_id = call("POST", "/public/purchase", json={"planId": plan["id"]})["order"]["id"]

lines = call("POST", "/public/proxies/generate", json={
    "orderId": order_id, "country": "us", "rotation": "sticky",
    "sessionTime": 10, "quantity": 2, "format": "http://user:pass@host:port",
})["proxies"]

proxy = lines[0]
print(requests.get("https://ipinfo.io/json", proxies={"http": proxy, "https": proxy}, timeout=30).json())
```

Keep `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).

## [section/Agent-registration-(verified-email)](https://quanticdata.io/docs/python/#section/Agent-registration-%28verified-email%29) · Agent registration (verified email)

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

| Step | Call | What you keep |
| --- | --- | --- |
| 1. Discover | `GET https://app.quanticdata.io/.well-known/oauth-authorization-server` | `agent_auth.register_uri`, `agent_auth.claim_uri` |
| 2. Register | `POST /agent/auth` with `{"method":"verified_email","email":"…","agent":{"name":"…"}}` | `claim_uri`, `expires_in` (600 s) |
| 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 |
| 4. Claim | `POST /agent/auth/claim` with `{"email":"…","code":"……"}` | `api_key` (shown once) |

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

```bash
APP=https://app.quanticdata.io/api/v1

# 2. register: sends the code
curl -s -X POST "$APP/agent/auth" -H "Content-Type: application/json" \
  -d '{"method":"verified_email","email":"user@example.com","agent":{"name":"Research agent","url":"https://example.com/agent"}}'

# 4. claim: returns the key once
curl -s -X POST "$APP/agent/auth/claim" -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","code":"482913"}'
```

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

## [section/Agent-checkout-(UCP)](https://quanticdata.io/docs/python/#section/Agent-checkout-%28UCP%29) · Agent checkout (UCP)

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").

| Step | Call | What you keep |
| --- | --- | --- |
| 1. Pick a plan | `GET /public/plans?planType=residentialpremium` | `plans[].id`, `amount` (USD) |
| 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` |
| 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` |
| 3b. It does not (`requires_escalation`) | Give the person `continue_url`; poll `GET /agent/ucp/checkout-sessions/{id}` until `completed` | `order.id` |
| 4. Get proxy lines | `POST /public/proxies/generate` with `{"orderId":"…"}` | `proxies[]` |

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

```bash
API=https://api.quanticdata.io/v1
KEY=qd_live_YOUR_API_KEY

# 2. open the session (idempotent on the key)
curl -s -X POST "$API/agent/ucp/checkout-sessions" -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: order-2026-10-26-001" \
  -d '{"line_items":[{"item":{"id":"PLAN_ID"},"quantity":1}],"payment_method":"BALANCE"}'

# 3a. pay from the balance when status is ready_for_complete
curl -s -X POST "$API/agent/ucp/checkout-sessions/SESSION_ID/complete" -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"payment":{"instruments":[{"handler_id":"balance","type":"account_balance","selected":true}]}}'

# 3b. otherwise poll after the person has paid at continue_url
curl -s "$API/agent/ucp/checkout-sessions/SESSION_ID" -H "Authorization: Bearer $KEY"
```

Read `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.

## [section/Errors-and-status-codes](https://quanticdata.io/docs/python/#section/Errors-and-status-codes) · Errors and status codes

Status codes used by this API and what each one means (collected from every endpoint below). Error bodies are JSON with `type: "error"`; read `message` for the reason.

| Status | Meaning | Returned by |
| --- | --- | --- |
| `400` | Malformed input. `message` names the parameter and the rule it broke. | 60 endpoints |
| `401` | Missing, malformed, unknown, disabled or expired API key; or the account is not active. | 91 endpoints |
| `402` | The free tier plus wallet balance cannot cover the worst-case estimate of this call (`INSUFFICIENT_FUNDS`), or the account's monthly spend cap is reached (`BUDGET_REACHED`). Nothing was run or charged. When the missing credit is more than one top-up may add, or on `BUDGET_REACHED`, the envelope also carries `escalation` (`type` `contact`): an agent asks for a higher limit at `contact_api` (`POST /agent/contact`, same API key), a person uses `contact_url`. | 18 endpoints |
| `402` | The wallet balance cannot cover the total. Nothing was created or charged: top up in the dashboard and send the request again. | `POST /public/ipv6/orders` |
| `402` | The wallet balance cannot cover the total. Nothing was created or charged: top up in the dashboard and send the request again. | `POST /public/premium-isp/orders`, `POST /public/premium-isp/orders/{orderId}/renewal`, `POST /public/premium-isp/orders/{orderId}/replacements` |
| `403` | `target_forbidden` (private, reserved or internal address), `target_denied` (a destination the unlocker does not serve) or `no_exit_pool` (the account has no exit pool for the tier, e.g. `mobile` without a mobile sub-user): the request did not run, nothing billed. `max_bytes_exceeded`: the bytes moved went over `max_bytes`; `payload.usage` and `payload.cost` say how many, and they are debited. | 23 endpoints |
| `403` | No proxy pool is available to serve the call (no house plan and no residential/datacenter/IPv6 plan on the account). | 10 endpoints |
| `403` | 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. | `GET /public/ipv6/plans`, `POST /public/ipv6/quote`, `GET /public/ipv6/orders`, `POST /public/ipv6/orders`, `GET /public/ipv6/orders/{orderId}` |
| `403` | 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. | `POST /public/proxies/generate`, `GET /public/proxies/whitelist-ip`, `POST /public/proxies/whitelist-ip`, `DELETE /public/proxies/whitelist-ip` |
| `404` | `presetId` does not resolve to one of your presets. | 50 endpoints |
| `409` | The selection cannot be sold right now, or the request conflicts with an earlier one. Nothing was charged unless the code says so. | 14 endpoints |
| `409` | 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. | `POST /public/ipv6/quote`, `POST /public/ipv6/orders` |
| `409` | 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). | `POST /public/proxies/{orderId}/rotate`, `GET /public/proxies/{orderId}/rotation-links`, `POST /public/proxies/{orderId}/rotation-links`, `DELETE /public/proxies/{orderId}/rotation-links/{linkId}`, `GET /public/rotate/{token}`, `POST /public/rotate/{token}` |
| `410` | `PLAN_EXPIRED`: the plan has expired. | `POST /public/proxies/{orderId}/rotate`, `POST /public/proxies/{orderId}/rotation-links`, `GET /public/rotate/{token}`, `POST /public/rotate/{token}`, `POST /agent/auth/claim` |
| `422` | `action_failed`, only with `actions`: the page loaded but one of the actions could not run. `message` names the action by its position and shape and says why. Not retryable as it is, nothing billed. | `POST /scraper/unlock`, `POST /scraper/collectors/{slug}/run`, `POST /public/premium-isp/orders`, `POST /public/purchase`, `POST /scraper/video`, `POST /agent/auth` |
| `422` | 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. | `POST /public/ipv6/orders` |
| `424` | `target_blocked`, only with `fail_on_block: true`: every attempt came back blocked. Same diagnostics as the 200 form (`status` of the block page, `blockReason`, `blockClass`, `vendor`, `attempts`, `attempt_log`, `tier_served`); the GB moved are debited (`usage`, `cost`). Retryable: later, on the `mobile` tier, from another country or with `mode: "browser"`. | `POST /scraper/unlock`, `POST /scraper/collectors/{slug}/run` |
| `428` | A person has to finish this registration in the browser. | `POST /agent/auth` |
| `429` | Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After. | 87 endpoints |
| `429` | `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. | `POST /public/proxies/{orderId}/rotate`, `GET /public/rotate/{token}`, `POST /public/rotate/{token}` |
| `500` | Extraction failed on our side or timed out (70 s budget). Never billed. | 48 endpoints |
| `502` | The plan's network did not answer; retry. | 7 endpoints |
| `503` | The Data API group is switched off for non-admin keys (early-access kill switch). | 46 endpoints |
| `503` | 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. | `GET /public/ipv6/plans`, `POST /public/ipv6/quote`, `GET /public/ipv6/orders`, `POST /public/ipv6/orders`, `GET /public/ipv6/orders/{orderId}` |
| `503` | 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. | 13 endpoints |
| `503` | `SERVICE_UNAVAILABLE`: rotation is temporarily unavailable. Retry after Retry-After. | `POST /public/proxies/{orderId}/rotate`, `GET /public/proxies/{orderId}/rotation-links`, `POST /public/proxies/{orderId}/rotation-links`, `DELETE /public/proxies/{orderId}/rotation-links/{linkId}`, `GET /public/rotate/{token}`, `POST /public/rotate/{token}` |
| `504` | `timeout`: `timeout_ms` ran out before a response (every attempt and the browser render share that budget). Retryable; not billed. | `POST /scraper/unlock`, `POST /scraper/unlock/batch`, `POST /scraper/video` |

Response headers related to limits: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `Retry-After`, `X-RateLimit-Scope`, `X-RateLimit-Plan`.

## [section/Rate-limits-and-tiers](https://quanticdata.io/docs/python/#section/Rate-limits-and-tiers) · Rate limits and tiers

Limits per tier (live values as of 2026-10-19):

| Tier | Monthly | Free usage / month | Requests / minute | Batch concurrency | Unit price discount |
| --- | --- | --- | --- | --- | --- |
| Pay as you go | $0 | $2 | 20 | 5 | 0% |
| Starter | $19/month | $15 | 300 | 10 | 10% |
| Growth | $79/month | $50 | 600 | 20 | 20% |
| Scale | $299/month | $250 | 1200 | 20 | 30% |

- 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.
- rateLimitPerMin is enforced per API key; the key also has an hourly window = max(1000, rateLimitPerMin × 60) requests.
- A pay-as-you-go account in real-balance billing mode gets balance_mode_rate_limit_per_min (pricing.json) instead of its tier cap.
- 429 responses carry X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and Retry-After.
- Real-balance billing mode: 300 requests/minute instead of the tier cap.

## [section/Pricing-per-endpoint](https://quanticdata.io/docs/python/#section/Pricing-per-endpoint) · Pricing per endpoint

Every pay-as-you-go account includes $2 of free usage per month. Only successful calls are billed; a blocked page, a target `4xx`/`5xx`, a timeout or an error on our side costs nothing. Prices below are the list of 2026-10-19; `GET /scraper/billing` returns the live list applied to your key. LLM tokens used by the AI endpoints are billed at provider cost × 2.

| Endpoint | Price keys |
| --- | --- |
| `POST /scraper/extract` | `extract` $0.0015 per call + $3/GB, max $0.02 per call `extract_render` $0.0025 per call + $4/GB, max $0.05 per call `ai_extract` $0.005 per call, max $1.50 per call |
| `POST /scraper/serp` | `serp` $0.0009 per call `serp_render` $0.002 per call |
| `POST /scraper/serp/bulk` | `serp_render` $0.002 per call `serp` $0.0009 per call |
| `POST /scraper/map` | `map` $0.003 per call |
| `POST /scraper/crawl` | `crawl_page` $0.0003 per call `extract_render` $0.0025 per call + $4/GB, max $0.05 per call |
| `POST /scraper/batch` | `batch_url` $0.0004 per call `extract_render` $0.0025 per call + $4/GB, max $0.05 per call |
| `POST /scraper/unlock` | `unlock_request` per GB of transferred data; the price per GB of each tier is on the plans page of the dashboard and, when the offer is published, in `GET /public/unlock/offer` |
| `POST /scraper/unlock/batch` | `unlock_request` per GB of transferred data; the price per GB of each tier is on the plans page of the dashboard and, when the offer is published, in `GET /public/unlock/offer` |
| `POST /scraper/ai` | `ai_extract` $0.005 per call, max $1.50 per call `extract` $0.0015 per call + $3/GB, max $0.02 per call `serp` $0.0009 per call `map` $0.003 per call |
| `POST /scraper/places-ai` | `places_ai` $0.005 per call, max $3 per call `serp_render` $0.002 per call |
| `POST /scraper/shopping-ai` | `shopping_ai` $0.005 per call, max $3 per call `serp_render` $0.002 per call |
| `POST /scraper/ai-visibility` | `ai_visibility` $0.01 per call `ai_visibility_citation` $0.01 per call `serp` $0.0009 per call |
| `POST /scraper/seo-audit` | `seo_audit` $0.003 per call `extract` $0.0015 per call + $3/GB, max $0.02 per call |
| `POST /scraper/collectors/{slug}/run` | `collector_result` — by collector, table below |
| `POST /scraper/datasets` | `dataset_row` $0.03 per call `dataset_row_refresh` $0.01 per call |
| `POST /scraper/parser/generate` | `parser_generate` $0.02 per call |
| `POST /scraper/parser/presets/{id}/heal` | `parser_generate` $0.02 per call |
| `POST /scraper/video` | `video` $0.02 per call |
| **Collector results** (`POST /scraper/collectors/{slug}/run`, per delivered result): |  |

| Collector price key | Per delivered result |
| --- | --- |
| `collector_ai_readiness` | $0.003 |
| `collector_airbnb_stays` | $0.001 |
| `collector_aliexpress_search` | $0.001 |
| `collector_amazon_product` | $0.008 |
| `collector_amazon_reviews` | $0.002 |
| `collector_amazon_search` | $0.001 |
| `collector_app_store_apps` | $0.0008 |
| `collector_app_store_reviews` | $0.0005 |
| `collector_arxiv_papers` | $0.0004 |
| `collector_asos_search` | $0.001 |
| `collector_autotrader_search` | $0.001 |
| `collector_bbb_businesses` | $0.002 |
| `collector_bestbuy_product` | $0.002 |
| `collector_booking_stays` | $0.02 |
| `collector_business_directory` | $0.001 |
| `collector_capterra_products` | $0.01 |
| `collector_carvana_cars` | $0.001 |
| `collector_certificate_transparency` | $0.0004 |
| `collector_clinical_trials` | $0.0005 |
| `collector_coingecko_coins` | $0.0002 |
| `collector_company_profile` | $0.03 |
| `collector_coursera_courses` | $0.001 |
| `collector_crates_io` | $0.0003 |
| `collector_defillama` | $0.0003 |
| `collector_dns_records` | $0.001 |
| `collector_docker_hub` | $0.001 |
| `collector_doordash_restaurants` | $0.003 |
| `collector_ebay_catalog` | $0.006 |
| `collector_ebay_product` | $0.006 |
| `collector_ebay_search` | $0.003 |
| `collector_exchange_rates` | $0.0002 |
| `collector_flipkart_search` | $0.001 |
| `collector_g2_products` | $0.001 |
| `collector_github_repos` | $0.0005 |
| `collector_gleif_lei` | $0.0004 |
| `collector_google_autocomplete` | $0.0002 |
| `collector_google_events` | $0.002 |
| `collector_google_flights` | $0.003 |
| `collector_google_jobs` | $0.001 |
| `collector_google_lens` | $0.004 |
| `collector_google_maps_places` | $0.001 |
| `collector_google_news` | $0.0005 |
| `collector_google_play_apps` | $0.006 |
| `collector_google_shopping` | $0.001 |
| `collector_google_trends` | $0.0005 |
| `collector_hacker_news` | $0.0003 |
| `collector_healthgrades_doctors` | $0.001 |
| `collector_hotels` | $0.02 |
| `collector_idealista_search` | $0.001 |
| `collector_indeed_jobs` | $0.001 |
| `collector_instagram_profile` | $0.006 |
| `collector_itunes_search` | $0.0004 |
| `collector_keyword_ideas` | $0.0002 |
| `collector_kleinanzeigen_search` | $0.001 |
| `collector_linkedin_company` | $0.005 |
| `collector_linkedin_company_posts` | $0.001 |
| `collector_linkedin_jobs` | $0.001 |
| `collector_linkedin_profile` | $0.005 |
| `collector_local_business_leads` | $0.01 |
| `collector_marketwatch_quote` | $0.003 |
| `collector_miodottore_doctors` | $0.001 |
| `collector_nike_products` | $0.001 |
| `collector_npm_packages` | $0.0003 |
| `collector_nvd_cve` | $0.0004 |
| `collector_openalex` | $0.0004 |
| `collector_openfda` | $0.0004 |
| `collector_openlibrary_books` | $0.0004 |
| `collector_paginegialle_profiles` | $0.002 |
| `collector_place_reviews` | $0.001 |
| `collector_product_offers` | $0.002 |
| `collector_producthunt_posts` | $0.001 |
| `collector_pypi_packages` | $0.0003 |
| `collector_reddit_comments` | $0.002 |
| `collector_reddit_posts` | $0.0005 |
| `collector_redfin_search` | $0.0008 |
| `collector_rottentomatoes_movies` | $0.001 |
| `collector_search_images` | $0.0003 |
| `collector_search_videos` | $0.0004 |
| `collector_sec_filings` | $0.0005 |
| `collector_site_contacts` | $0.02 |
| `collector_site_documents` | $0.005 |
| `collector_stackoverflow` | $0.0003 |
| `collector_steam` | $0.0008 |
| `collector_subito_search` | $0.001 |
| `collector_target_product` | $0.0006 |
| `collector_tech_stack` | $0.005 |
| `collector_tiktok_profile` | $0.004 |
| `collector_tiktok_video` | $0.004 |
| `collector_tripadvisor_search` | $0.001 |
| `collector_trustpilot_reviews` | $0.06 |
| `collector_udemy_courses` | $0.001 |
| `collector_walmart_product` | $0.0015 |
| `collector_walmart_search` | $0.002 |
| `collector_wayback_machine` | $0.0003 |
| `collector_weather_forecast` | $0.0002 |
| `collector_web_search` | $0.0005 |
| `collector_wellfound_jobs` | $0.001 |
| `collector_whois_domain` | $0.005 |
| `collector_wikidata` | $0.0003 |
| `collector_wikipedia_articles` | $0.0005 |
| `collector_world_bank` | $0.0002 |
| `collector_x_user_tweets` | $0.0003 |
| `collector_yahoo_finance` | $0.001 |
| `collector_youtube_autocomplete` | $0.0002 |
| `collector_youtube_channel` | $0.0008 |
| `collector_youtube_comments` | $0.0003 |
| `collector_youtube_search` | $0.0008 |
| `collector_youtube_transcript` | $0.002 |
| `collector_youtube_video` | $0.005 |
| `collector_zalando_search` | $0.001 |
| `collector_zillow_property` | $0.005 |
| `collector_zillow_search` | $0.001 |

## [section/MCP-server](https://quanticdata.io/docs/python/#section/MCP-server) · MCP server

The same API is available as an MCP server for Claude, Cursor, ChatGPT and any MCP client. Product page: [quanticdata.io/mcp-server/](https://quanticdata.io/mcp-server/).

**Remote server (OAuth 2.1, no key to paste):** `https://api.quanticdata.io/mcp`

OAuth metadata: [authorization server](https://app.quanticdata.io/.well-known/oauth-authorization-server) · [protected resource](https://api.quanticdata.io/.well-known/oauth-protected-resource/mcp)

Claude Code (remote, OAuth):

```bash
claude mcp add --transport http quanticdata https://api.quanticdata.io/mcp
```

**Local server (npx, API key in the environment):**

```bash
QUANTICDATA_API_KEY=qd_live_… npx -y quanticdata-mcp
```

Claude Code (local):

```bash
claude mcp add quanticdata -e QUANTICDATA_API_KEY=qd_live_… -- npx -y quanticdata-mcp
```

Clients without native remote MCP support can bridge through `npx -y quanticdata-mcp-remote`.

Trial limits for keyless use are published by `GET /mcp/trial-config` (see Account).

Tools exposed by the remote server (as of 2026-10-19) and the REST endpoint behind each one:

| MCP tool | Endpoint |
| --- | --- |
| `scrape` | `POST /scraper/extract` |
| `search` | `POST /scraper/serp` |
| `search_and_read` | `POST /scraper/serp + POST /scraper/extract` |
| `search_bulk` | `POST /scraper/serp/bulk` |
| `search_bulk_status` | `GET /scraper/serp/bulk/{jobId}` |
| `map` | `POST /scraper/map` |
| `crawl` | `POST /scraper/crawl` |
| `crawl_status` | `GET /scraper/crawl/{jobId}` |
| `batch` | `POST /scraper/batch` |
| `batch_status` | `GET /scraper/batch/{jobId}` |
| `unlock` | `POST /scraper/unlock` |
| `ai_visibility` | `POST /scraper/ai-visibility` |
| `seo_audit` | `POST /scraper/seo-audit` |
| `list_collectors` | `GET /scraper/collectors` |
| `run_collector` | `POST /scraper/collectors/{slug}/run` |
| `collector_run_status` | `GET /scraper/collectors/runs/{runId}` |
| `create_dataset` | `POST /scraper/datasets` |
| `dataset_status` | `GET /scraper/datasets/{jobId}` |
| `generate_parser` | `POST /scraper/parser/generate` |
| `list_parser_presets` | `GET /scraper/parser/presets` |
| `save_parser_preset` | `POST /scraper/parser/presets` |
| `heal_parser_preset` | `POST /scraper/parser/presets/{id}/heal` |
| `parser_preset_stats` | `GET /scraper/parser/presets/{id}/stats` |
| `list_proxies` | `GET /public/proxies` |
| `generate_proxies` | `POST /public/proxies/generate` |
| `proxy_locations` | `GET /public/generator/{residential-premium |
| `whitelist_ip` | `POST /public/proxies/whitelist-ip` |
| `report` | `(MCP only: usage report of the session)` |

### Skills for AI agents

5 Agent Skills (`SKILL.md`, the open [Agent Skills](https://agentskills.io/specification) format) teach Claude Code, Claude.ai, Codex, Cursor, Gemini CLI and any agent that reads `SKILL.md` how to use this API and the MCP server: the agent loads the one it needs when the task calls for it. They are published at [quanticdata.io/.well-known/agent-skills/index.json](https://quanticdata.io/.well-known/agent-skills/index.json) and installed in one command with the [`skills` CLI](https://github.com/vercel-labs/skills):

```bash
npx skills add https://quanticdata.io
```

Source and Claude Code plugin: [github.com/quantumproxies/quanticdata-skills](https://github.com/quantumproxies/quanticdata-skills) (`npx skills add quantumproxies/quanticdata-skills`, or copy `skills/<name>` into `~/.claude/skills/`).

- [`use-data-api`](https://quanticdata.io/.well-known/agent-skills/use-data-api/SKILL.md): Call the REST Data API: authentication, response envelope, async jobs, references
- [`use-mcp-server`](https://quanticdata.io/.well-known/agent-skills/use-mcp-server/SKILL.md): Connect any MCP client: hosted OAuth endpoint or local npm package, tool presets
- [`scrape-to-markdown`](https://quanticdata.io/.well-known/agent-skills/scrape-to-markdown/SKILL.md): One URL to clean Markdown or structured fields; batch, map and crawl for many
- [`generate-proxies`](https://quanticdata.io/.well-known/agent-skills/generate-proxies/SKILL.md): Proxy strings from your plans: geo-targeting, sticky sessions, IP whitelists
- [`find-business-leads`](https://quanticdata.io/.well-known/agent-skills/find-business-leads/SKILL.md): Business lists and datasets: Collectors, AI Places Finder, dataset builder

## [tag/Scrape](https://quanticdata.io/docs/python/#tag/Scrape) · Scrape

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

## [tag/Scrape/operation/scrapeUrl](https://quanticdata.io/docs/python/#tag/Scrape/operation/scrapeUrl) · Scrape one URL

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

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

##### Authorizations:

*bearerAuth*

##### Request Body schema: application/json · required

| url | string <= 2048 characters http/https URL to scrape. Required unless `html` is given. |
| --- | --- |
| html | string Markup to convert instead of fetching (max 5 MB). |
| format | string Default: "markdown" Enum: "markdown" · "html" · "text" · "raw" `raw` is an alias of `html`. Defaults to markdown (also when AI extraction is requested). |
| formats | Array of strings <= 3 items Items Enum: "markdown" · "html" · "text" Extra formats returned together under `payload.formats`. |
| data_format | string Enum: "markdown" · "screenshot" Compatibility alias: `markdown` sets format, `screenshot` sets `screenshot: fullPage`. |
| engine | string Default: "auto" Enum: "auto" · "tls" · "fetch" · "render" `auto` starts on the TLS tier and escalates to the browser on a block; `tls`/`fetch` never escalate; `render` forces the browser. |
| autoEscalate | boolean Allow/forbid the auto engine's escalation to the browser (ignored once the plan's render budget is spent). |
| tlsProfile | string <= 64 characters TLS fingerprint profile for the TLS tier (opaque to the API; see /scraper/unlock for the known names). |
| render | boolean Default: false Force the stealth headless browser (JS execution). Bills the render rate. |
| mobile | boolean Default: false Mobile viewport and user agent. |
| waitMs | number Extra wait after load before capture, render tier (clamped by the service, max 15000). |
| waitForSelector | string <= 512 characters Wait until this CSS selector appears (render tier). |
| scrollToBottom | boolean Default: false Auto-scroll to trigger lazy-loaded content (render tier). |
| actions | Array of objects (PageAction) <= 20 items |
| screenshot | boolean or string `true` = viewport PNG, `fullPage` = whole page; forces render. Returned base64 under `screenshot`. |
| xhr | boolean Record the page's XHR/fetch traffic under `xhr` (forces render). Use it to discover which API to target with a `fetchResource` action. |
| expect | object 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. |
| extract | object (ExtractSchema) Examples: {"title":"h1","price":".price","image":{"selector":"img.hero","attr":"src"},"features":{"selector":"li.feature","all":true}} Structured-extraction schema: field name → CSS selector, or an object with `selector`, optional `attr` (attribute to read instead of text) and `all` (true = every match as an array). |
| presetId | string Run a stored parser preset instead of an inline `extract` schema; the run is scored per field for self-healing. 404 if the preset is not yours. |
| contentMode | string Default: "smart" Enum: "smart" · "article" · "full" `smart` = whole page minus nav/footer/cookie chrome; `article` = Readability main article; `full` = entire body. Alias `content_mode`. |
| content_modes | Array of strings <= 3 items Items Enum: "smart" · "article" · "full" Return several content modes at once under `contents`. Alias `contentModes`. |
| fullPage | boolean Legacy: `true` = contentMode full. |
| mode | string Default: "full" Enum: "full" · "summary" `summary` drops the content and returns only metadata (title, description, canonical, contentLength, engine, bytes) — the light view for audits over many pages. |
| include_links | boolean Default: false Also return de-duplicated absolute links under `links`. Alias `includeLinks`. |
| app_state | boolean or string Mine the page's own hydration state (Next/Nuxt/JSON islands) into `metadata.appState`. `true`/`auto` = pruned to the informative parts; `raw` = full blobs. Alias `appState`. |
| parser | object 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. |
| reveal_hidden | boolean Render tier: open `<details>`/accordions and click through tabs, capturing every panel. Alias `revealHidden`. |
| output | object Markdown shaping; every key also accepted flat (snake_case) at the top level, flat wins. |
| frontmatter | boolean |
| links_mode | string Enum: "inline" · "footnote" · "strip" |
| toc | boolean |
| max_tokens | number [ 200 .. 2000000 ] |
| images_mode | string Enum: "inline" · "alt" · "strip" |
| query | string <= 512 characters |
| highlights | integer [ 1 .. 20 ] |
| chunk | object |
| summary_sections | boolean |
| ai_prompt | string Natural-language instruction: the LLM turns the page into structured JSON under `payload.ai.data`. |
| ai_schema | object JSON Schema the AI output must follow (deterministic shape). Either `ai_prompt` or `ai_schema` (or both) enables AI extraction. |
| headers | object or string (ForwardHeaders) |
| cookies | object <= 50 properties name → value cookies sent to the target. |
| country | string (GeoValue) ^([a-zA-Z0-9 ._-]{1,56}\|all)$ Examples: "us" · "it" · "all" Country code or place name: letters, digits, spaces, dots, hyphens, underscores; max 56 characters. `all` means no targeting. |
| state | string (GeoValue) ^([a-zA-Z0-9 ._-]{1,56}\|all)$ Examples: "us" · "it" · "all" Requires `country`. |
| city | string (GeoValue) ^([a-zA-Z0-9 ._-]{1,56}\|all)$ Examples: "us" · "it" · "all" Requires `country`. |
| rotation | string Default: "rotating" Enum: "rotating" · "sticky" New exit IP per request, or keep one IP for the session. Any other value is treated as `rotating`. |
| sessionId | string <= 64 characters Sticky session id (generated if omitted). |
| sessionDuration | number Sticky session lifetime in minutes (clamped by the proxy layer, 3–1440, default 10). |

### Responses

**200**

Page fetched. `engine` says which tier served it and therefore which price applied.

Response Headers

| X-RateLimit-Limit | integer Requests allowed in the current hourly window for this key. |
| --- | --- |
| X-RateLimit-Remaining | integer Requests left in the window. |
| X-RateLimit-Reset | string · \<date-time> ISO-8601 instant when the window resets. |

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object Payload of a scrape. Optional fields appear only when requested (`data`, `links`, `screenshot`, `xhr`, `formats`, `contents`, `chunks`, `highlights`, `ai`). |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "url": "[https://example.com/pricing](https://example.com/pricing)",
- "format": "markdown",
- "country": "us",
- "extract": {
  - "title": "h1",
  - "price": ".price"

  }

}

### Response samples

- 200
- 400
- 401
- 402
- 403
- 404
- 429
- 500
- 503

Content type

application/json

{

- "type": "response",
- "message": "Extraction successful",
- "payload": {
  - "url": "[https://example.com/pricing](https://example.com/pricing)",
  - "finalUrl": "[https://example.com/pricing](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](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": { }

}

## [tag/Search](https://quanticdata.io/docs/python/#tag/Search) · Search

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

## [tag/Search/operation/searchSerp](https://quanticdata.io/docs/python/#tag/Search/operation/searchSerp) · Structured search results

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

One search on Google, Bing or DuckDuckGo through the residential pool, returned as JSON in the common SERP-API shape: organic results, ads, People Also Ask, related searches, knowledge panels, AI Overview and 17 Google verticals (`search_type`). `render: true` asks for the rendered Google page (People Also Ask, related questions, ads), `render: false` pins the cheaper HTTP tier, and without `render` the service picks: the HTTP tier for Google web search, a browser for the verticals that need one. Identical requests are served from a 24h cache for free (`search_metadata.from_cache`). It does not paginate on your behalf: request one `page` at a time and read `pagination.available_pages`/`has_next`, or use `/scraper/serp/bulk`. Billed per successful search by the tier that served it (`search_metadata.path`); blocked searches answer 429 and cost nothing; `autocomplete` and `reviews` always bill the request price.

##### Authorizations:

*bearerAuth*

##### Request Body schema: application/json · required

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

### Responses

**200**

Search succeeded. The envelope's `pagination` mirrors `payload.pagination`.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object 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. |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "query": "best coffee grinder",
- "engine": "google",
- "country": "us",
- "lang": "en",
- "num": 10

}

### Response samples

- 200
- 400
- 401
- 402
- 403
- 429
- 500
- 503

Content type

application/json

{

- "type": "response",
- "message": "SERP successful",
- "payload": {
  - "search_metadata": {
    - "status": "Success",
    - "engine": "google",
    - "search_url": "[https://www.google.com/search?q=best+coffee+grinder&gl=us&hl=en](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](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](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

  }

}

## [tag/Search/operation/startSerpBulk](https://quanticdata.io/docs/python/#tag/Search/operation/startSerpBulk) · Start a multi-page search job

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

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

##### Authorizations:

*bearerAuth*

##### Request Body schema: application/json · required

| query required | string <= 2048 characters |
| --- | --- |
| engine | string Default: "google" Enum: "google" · "bing" · "duckduckgo" |
| search_type | string Default: "search" Enum: "search" · "news" · "videos" · "images" · "shopping" Alias `type`. |
| max_pages | integer [ 1 .. 10 ] Default: 5 |
| country | string (GeoValue) ^([a-zA-Z0-9 ._-]{1,56}\|all)$ Examples: "us" · "it" · "all" Alias `gl`. |
| lang | string <= 10 characters Alias `hl`. |
| device | string Enum: "desktop" · "mobile" · "ios" · "android" Device to search as. `desktop` (default) gets the computer page; `mobile`, `ios` and `android` get the phone page. Google web, news and videos are fetched as Edge: on an Android phone for every phone value, on Windows or macOS for `desktop`. Every page of one query (`num` above 10, every page of a bulk job) comes from the same device and browser; identities rotate between queries, among current versions and phone models. `search_metadata.served_device` says which page came back (phone or computer layout), `served_platform` and `served_browser` which device and browser fetched it. Desktop and phone results are cached separately. Also accepted as `brd_mobile`: `1` (mobile), `ios` or `android`. |
| render | boolean |
| wait_for | string <= 512 characters |
| browser | string Enum: "chrome" · "firefox" · "safari" Browser to search as: `chrome`, `firefox` or `safari` (Safari is iPhone or macOS, Chrome is Android or desktop, Firefox desktop only). Bing and DuckDuckGo fetch as that browser; Google web, news and videos always fetch as Edge (`search_metadata.served_browser`). Without it the browser rotates between queries. Alias `brd_browser`. |
| safe | string Enum: "active" · "off" |
| nfpr | boolean or integer |
| uule | string <= 512 characters |
| location | string <= 256 characters |
| google_params | object <= 24 properties |
| webhook | string <= 2048 characters Public http(s) URL that receives the finished job by POST. |

### Responses

**200**

Job accepted.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object Answer of a POST that started an async job. |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "query": "best coffee grinder",
- "engine": "google",
- "country": "us",
- "max_pages": 3

}

### Response samples

- 200
- 400
- 401
- 402
- 403
- 429
- 500
- 503

Content type

application/json

{

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

    }

  },
- "pagination": { }

}

## [tag/Search/operation/getSerpBulk](https://quanticdata.io/docs/python/#tag/Search/operation/getSerpBulk) · Poll a multi-page search job

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

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

##### Authorizations:

*bearerAuth*

##### path Parameters

| jobId required | string Example: job_8f2c1a Job id returned by the POST that started it. |
| --- | --- |

##### query Parameters

| since | integer Organic cursor from the previous poll's `nextCursor`. |
| --- | --- |

### Responses

**200**

Job view.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 401
- 404
- 429
- 500
- 503

Content type

application/json

{

- "type": "response",
- "message": "Bulk SERP status",
- "payload": {
  - "id": "sb_4d1e9c",
  - "status": "completed",
  - "query": "best coffee grinder",
  - "total": 3,
  - "completed": 3,
  - "failed": 0,
  - "pages": [
    - {
      - "page": 1,
      - "organic_count": 10,
      - "bytes": 210331,
      - "path": "http"

      },
    - {
      - "page": 2,
      - "organic_count": 10,
      - "bytes": 198002,
      - "path": "http"

      },
    - {
      - "page": 3,
      - "organic_count": 9,
      - "bytes": 190114,
      - "path": "http"

      }

    ],
  - "organic": [
    - {
      - "rank": 1,
      - "title": "The 6 Best Coffee Grinders of 2026",
      - "link": "[https://example.com/reviews/coffee-grinders](https://example.com/reviews/coffee-grinders)",
      - "display_link": "example.com",
      - "description": "…"

      }

    ],
  - "related_searches": [ ],
  - "ai_overview": null,
  - "nextCursor": 29,
  - "createdAt": 1759828364000,
  - "finishedAt": 1759828391000

  },
- "pagination": { }

}

## [tag/Search/operation/cancelSerpBulk](https://quanticdata.io/docs/python/#tag/Search/operation/cancelSerpBulk) · Cancel a multi-page search job

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

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

##### Authorizations:

*bearerAuth*

##### path Parameters

| jobId required | string Example: job_8f2c1a Job id returned by the POST that started it. |
| --- | --- |

### Responses

**200**

Cancelled.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 401
- 404
- 429
- 500
- 503

Content type

application/json

{

- "type": "response",
- "message": "Bulk SERP cancelled",
- "payload": {
  - "id": "sb_4d1e9c",
  - "status": "cancelled"

  },
- "pagination": { }

}

## [tag/Map-and-Crawl](https://quanticdata.io/docs/python/#tag/Map-and-Crawl) · Map & Crawl

URL discovery for a whole site and asynchronous site crawls.

## [tag/Map-and-Crawl/operation/mapSite](https://quanticdata.io/docs/python/#tag/Map-and-Crawl/operation/mapSite) · Discover a site's URLs

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

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

##### Authorizations:

*bearerAuth*

##### Request Body schema: application/json · required

| url required | string <= 2048 characters Seed URL. |
| --- | --- |
| limit | number Default: 100 Max URLs to return (service cap 5000). |
| search | string <= 256 characters Only return URLs containing this substring. |
| includeSubdomains | boolean Default: false |
| sitemapOnly | boolean Default: false Skip the homepage link scrape. |
| group_by | string Value: "path" Return the path tree with counts instead of the URL list. Alias `groupBy`. |
| country | string (GeoValue) ^([a-zA-Z0-9 ._-]{1,56}\|all)$ Examples: "us" · "it" · "all" Country code or place name: letters, digits, spaces, dots, hyphens, underscores; max 56 characters. `all` means no targeting. |

### Responses

**200**

URLs discovered.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "url": "[https://example.com](https://example.com)",
- "limit": 100,
- "search": "blog"

}

### Response samples

- 200
- 400
- 401
- 402
- 403
- 429
- 500
- 503

Content type

application/json

{

- "type": "response",
- "message": "Map successful",
- "payload": {
  - "url": "[https://example.com](https://example.com)",
  - "links": [
    - "[https://example.com/blog/](https://example.com/blog/)",
    - "[https://example.com/blog/how-to-scrape](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": { }

}

## [tag/Map-and-Crawl/operation/startCrawl](https://quanticdata.io/docs/python/#tag/Map-and-Crawl/operation/startCrawl) · Start a site crawl

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

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

##### Authorizations:

*bearerAuth*

##### Request Body schema: application/json · required

| url required | string <= 2048 characters Seed URL. |
| --- | --- |
| limit | number Default: 50 Max pages (cap 500). Billed on this up front. |
| depth | number Default: 3 Max link depth from the seed (cap 10). |
| format | string Default: "markdown" Enum: "markdown" · "html" · "text" |
| contentMode | string Default: "smart" Enum: "smart" · "article" · "full" Alias `content_mode`. |
| render | boolean Default: false Render every page with the stealth browser (slower, rendered rate). |
| sameDomain | boolean Default: true |
| allowSubdomains | boolean Default: false |
| include | Array of strings <= 50 items [ items <= 256 characters ] URL substrings/globs to include, e.g. ["/guides/*"]. |
| exclude | Array of strings <= 50 items [ items <= 256 characters ] |
| country | string (GeoValue) ^([a-zA-Z0-9 ._-]{1,56}\|all)$ Examples: "us" · "it" · "all" Country code or place name: letters, digits, spaces, dots, hyphens, underscores; max 56 characters. `all` means no targeting. |

### Responses

**200**

Crawl started.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object Answer of a POST that started an async job. |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "url": "[https://docs.example.com](https://docs.example.com)",
- "limit": 50,
- "depth": 3,
- "include": [
  - "/guides/*"

  ]

}

### Response samples

- 200
- 400
- 401
- 402
- 403
- 429
- 500
- 503

Content type

application/json

{

- "type": "response",
- "message": "Crawl started",
- "payload": {
  - "id": "cr_d5b8a1",
  - "status": "running",
  - "seed": "[https://docs.example.com/](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": { }

}

## [tag/Map-and-Crawl/operation/getCrawl](https://quanticdata.io/docs/python/#tag/Map-and-Crawl/operation/getCrawl) · Poll a crawl job

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

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

##### Authorizations:

*bearerAuth*

##### path Parameters

| jobId required | string Example: job_8f2c1a Job id returned by the POST that started it. |
| --- | --- |

##### query Parameters

| since | integer Page cursor from the previous poll's `nextCursor`. |
| --- | --- |
| include_content | string Enum: "true" · "false" Omit to get the full job; `false` strips page content. |

### Responses

**200**

Job view.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 401
- 404
- 429
- 500
- 503

Content type

application/json

{

- "type": "response",
- "message": "Crawl status",
- "payload": {
  - "id": "cr_d5b8a1",
  - "status": "completed",
  - "seed": "[https://docs.example.com/](https://docs.example.com/)",
  - "limit": 50,
  - "depth": 3,
  - "format": "markdown",
  - "pagesCrawled": 37,
  - "pagesQueued": 0,
  - "pages": [
    - {
      - "url": "[https://docs.example.com/guides/getting-started](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": { }

}

## [tag/Map-and-Crawl/operation/cancelCrawl](https://quanticdata.io/docs/python/#tag/Map-and-Crawl/operation/cancelCrawl) · Cancel a crawl job

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

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

##### Authorizations:

*bearerAuth*

##### path Parameters

| jobId required | string Example: job_8f2c1a Job id returned by the POST that started it. |
| --- | --- |

### Responses

**200**

Cancelled.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 401
- 404
- 429
- 500
- 503

Content type

application/json

{

- "type": "response",
- "message": "Crawl cancelled",
- "payload": {
  - "id": "cr_d5b8a1",
  - "status": "cancelled"

  },
- "pagination": { }

}

## [tag/Batch](https://quanticdata.io/docs/python/#tag/Batch) · Batch

Many known URLs scraped asynchronously.

## [tag/Batch/operation/startBatch](https://quanticdata.io/docs/python/#tag/Batch/operation/startBatch) · Scrape many URLs asynchronously

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

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

##### Authorizations:

*bearerAuth*

##### Request Body schema: application/json · required

| urls required | Array of strings [ 1 .. 5000 ] items [ items <= 2048 characters ] |
| --- | --- |
| format | string Default: "markdown" Enum: "markdown" · "html" · "text" |
| engine | string Default: "auto" Enum: "auto" · "tls" · "fetch" · "render" |
| render | boolean Default: false Force the headless browser for every URL. |
| extract | object (ExtractSchema) Examples: {"title":"h1","price":".price","image":{"selector":"img.hero","attr":"src"},"features":{"selector":"li.feature","all":true}} Structured-extraction schema: field name → CSS selector, or an object with `selector`, optional `attr` (attribute to read instead of text) and `all` (true = every match as an array). |
| contentMode | string Default: "smart" Enum: "smart" · "article" · "full" Alias `content_mode`. |
| fullPage | boolean Legacy: contentMode full. |
| mode | string Default: "full" Enum: "full" · "summary" `summary` stores per-URL metadata only (title, description, canonical, contentLength). |
| concurrency | number [ 1 .. 20 ] Default: 5 Simultaneous fetches (clamped 1–20; your tier's batch concurrency also applies). |
| webhook | string <= 2048 characters Public http(s) URL that receives the finished job by POST. |
| country | string (GeoValue) ^([a-zA-Z0-9 ._-]{1,56}\|all)$ Examples: "us" · "it" · "all" Country code or place name: letters, digits, spaces, dots, hyphens, underscores; max 56 characters. `all` means no targeting. |

### Responses

**200**

Batch started.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object Answer of a POST that started an async job. |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "urls": [
  - "[https://example.com/a](https://example.com/a)",
  - "[https://example.com/b](https://example.com/b)"

  ],
- "format": "markdown",
- "mode": "summary"

}

### Response samples

- 200
- 400
- 401
- 402
- 403
- 429
- 500
- 503

Content type

application/json

{

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

    }

  },
- "pagination": { }

}

## [tag/Batch/operation/getBatch](https://quanticdata.io/docs/python/#tag/Batch/operation/getBatch) · Poll a batch job

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

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

##### Authorizations:

*bearerAuth*

##### path Parameters

| jobId required | string Example: job_8f2c1a Job id returned by the POST that started it. |
| --- | --- |

##### query Parameters

| since | integer Item cursor from the previous poll's `nextCursor`. |
| --- | --- |
| include_content | string Enum: "true" · "false" `true` includes each item's page content. |

### Responses

**200**

Job view.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 401
- 404
- 429
- 500
- 503

Content type

application/json

{

- "type": "response",
- "message": "Batch status",
- "payload": {
  - "id": "bt_91ac07",
  - "status": "completed",
  - "total": 2,
  - "completed": 2,
  - "failed": 0,
  - "contentTruncated": false,
  - "items": [
    - {
      - "url": "[https://example.com/a](https://example.com/a)",
      - "status": 200,
      - "title": "Page A",
      - "description": "…",
      - "canonical": "[https://example.com/a](https://example.com/a)",
      - "contentLength": 5120,
      - "engine": "tls",
      - "bytes": 31870

      },
    - {
      - "url": "[https://example.com/b](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": { }

}

## [tag/Batch/operation/cancelBatch](https://quanticdata.io/docs/python/#tag/Batch/operation/cancelBatch) · Cancel a batch job

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

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

##### Authorizations:

*bearerAuth*

##### path Parameters

| jobId required | string Example: job_8f2c1a Job id returned by the POST that started it. |
| --- | --- |

### Responses

**200**

Cancelled.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 401
- 404
- 429
- 500
- 503

Content type

application/json

{

- "type": "response",
- "message": "Batch cancelled",
- "payload": {
  - "id": "bt_91ac07",
  - "status": "cancelled"

  },
- "pagination": { }

}

## [tag/Video](https://quanticdata.io/docs/python/#tag/Video) · Video

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

## [tag/Video/operation/readVideo](https://quanticdata.io/docs/python/#tag/Video/operation/readVideo) · Read a YouTube video for a model

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

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

##### Authorizations:

*bearerAuth*

##### Request Body schema: application/json · required

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

### Responses

**200**

The video, read.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object 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. |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "url": "[https://www.youtube.com/watch?v=aircAruvnKk](https://www.youtube.com/watch?v=aircAruvnKk)",
- "max_frames": 6,
- "max_tokens": 4000

}

### Response samples

- 200
- 400
- 401
- 402
- 403
- 404
- 422
- 429
- 502
- 503
- 504

Content type

application/json

{

- "type": "response",
- "message": "Video read successful",
- "payload": {
  - "video": {
    - "platform": "youtube",
    - "id": "aircAruvnKk",
    - "url": "[https://www.youtube.com/watch?v=aircAruvnKk](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](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": { }

}

## [tag/Web-Unlocker](https://quanticdata.io/docs/python/#tag/Web-Unlocker) · Web Unlocker

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

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

### Which endpoint

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

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

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

## [tag/Web-Unlocker/Download-a-client](https://quanticdata.io/docs/python/#tag/Web-Unlocker/Download-a-client) · Download a client

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

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

**Node.js**

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

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

**Python**

```python
from unlocker import Unlocker

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

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

## [tag/Web-Unlocker/Forward-proxy](https://quanticdata.io/docs/python/#tag/Web-Unlocker/Forward-proxy) · Forward proxy

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

### Proxy users

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

### Proxy (CONNECT)

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

**curl**

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

**Python (requests)**

```python
import requests

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

**Node (undici)**

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

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

**PHP (curl)**

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

**Go**

```go
package main

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

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

### Direct mode

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

**curl**

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

**Python (requests)**

```python
import requests

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

**Node (undici)**

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

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

**PHP (curl)**

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

**Go**

```go
package main

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

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

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

### Targeting in the username

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

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

### Control headers

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

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

### Response headers

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

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

### Modes, retries and sessions

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

### Browser actions

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

### Cache

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

### Billing and limits

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

## [tag/Web-Unlocker/Batch](https://quanticdata.io/docs/python/#tag/Web-Unlocker/Batch) · Batch

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

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

## [tag/Web-Unlocker/Errors](https://quanticdata.io/docs/python/#tag/Web-Unlocker/Errors) · Errors

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

### Unlock errors

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

### Proxy-only answers

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

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

### Blocked pages

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

### Reading a block: vendor and blockClass

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

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

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

Two things worth knowing when you read the answer:

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

## [tag/Web-Unlocker/Coming-from-another-unlocker](https://quanticdata.io/docs/python/#tag/Web-Unlocker/Coming-from-another-unlocker) · Coming from another unlocker

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

### Our names

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

### Names the proxy reads unchanged

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

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

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

### Names to rename

These are not read: replace each with ours.

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

## [tag/Web-Unlocker/operation/unlockRequest](https://quanticdata.io/docs/python/#tag/Web-Unlocker/operation/unlockRequest) · Replay a request through the Web Unlocker

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

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

##### Authorizations:

*bearerAuth*

##### Request Body schema: application/json · required

| url required | string <= 2048 characters Target URL, `http://` or `https://`. Private, reserved and internal addresses are refused (403 `target_forbidden`); some destinations are not served (403 `target_denied`). |
| --- | --- |
| method | string · ^[A-Za-z]{1,16}$ Default: "GET" |
| headers | object or string (ForwardHeaders) |
| body | string Request body as UTF-8 text (JSON, form data…). Use this OR `bodyBase64`. |
| bodyBase64 | string Request body as base64 for binary payloads. Max 8 MB decoded. |
| tier | string Default: "premium" Enum: "premium" · "mobile" Which prepaid pool pays and which exits are used. Anything other than `mobile` is `premium`. |
| mode | string Default: "auto" Enum: "auto" · "tls" · "browser" 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 | string Default: "html" Enum: "html" · "markdown" · "text" 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 | integer >= 1024 Cap on the bytes this call may move across every attempt (request and response bodies, the browser's page load included). The TLS tier stops downloading past the cap; when the bytes moved exceed it the answer is 403 `max_bytes_exceeded` with `usage` and `cost`: the bytes moved are debited. Also accepted as `maxBytes`. |
| timeout_ms | integer [ 1000 .. 120000 ] Default: 60000 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 | boolean Default: false `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 | Array of objects (UnlockAction) <= 20 items 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 | integer [ 0 .. 86400 ] Default: 0 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 | string (GeoValue) ^([a-zA-Z0-9 ._-]{1,56}\|all)$ Examples: "us" · "it" · "all" 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 | string (GeoValue) ^([a-zA-Z0-9 ._-]{1,56}\|all)$ Examples: "us" · "it" · "all" Requires `country`. |
| city | string (GeoValue) ^([a-zA-Z0-9 ._-]{1,56}\|all)$ Examples: "us" · "it" · "all" Requires `country`. |
| rotation | string Default: "rotating" Enum: "rotating" · "sticky" |
| sessionId | string <= 64 characters Sticky session id — reuse it across calls to keep one exit IP. |
| sessionDuration | number Sticky session lifetime in minutes. |
| tlsProfile | string Default: "chrome" Enum: "chrome" · "firefox" · "safari" · "safari_ios" · "edge" · "brave" · "mobile" |
| mobile | boolean Default: false Mobile Safari fingerprint (fingerprint only — the product tier is `tier`). |
| render | string or boolean `png` returns a screenshot of the page from the headless browser (GET/HEAD, one render token). `html` or `true` is the same as `mode: "browser"`; `false` is the same as `mode: "tls"`. `mode` wins when both are sent. |
| autoRender | boolean Deprecated Default: true Deprecated, use `mode`: `autoRender: false` is `mode: "tls"` (no browser escalation of a blocked GET). Still accepted, also as `auto_render`. |
| keepHeaders | boolean Default: false Send your own identity headers (User-Agent, Accept, Sec-Fetch-*) verbatim instead of the fingerprint's. |
| successStatusCodes | Array of integers <= 20 items [ items [ 100 .. 599 ] ] Origin statuses to accept as success — never treated as a block, never retried. |
| timeoutMs | integer [ 1000 .. 120000 ] Same as `timeout_ms` (older spelling): the total budget of the call, not a per-attempt timeout. |
| failOnBlock | boolean Default: false Same as `fail_on_block` (older spelling). |
| waitForSelector | string [ 1 .. 256 ] characters Browser tier: CSS selector to wait for before capture. |
| waitMs | integer [ 0 .. 15000 ] Browser tier: extra settle time in milliseconds after the page loads. |
| returnCookies | boolean Default: false Return the origin's cookie jar under `cookies`. |
| cookies | object <= 50 properties Cookies merged into the Cookie header sent to the target (e.g. a clearance obtained earlier). |

### Responses

**200**

The target's response, replayed, or the block page it answered with (`blocked: true`, see the second example). Both carry the diagnostics (`request_id`, `latency_ms`, `tier_served`, `attempt_log`) and the cost of the call (`usage`, `cost`). The third example is an answer served from the cache. The `cost.usd` figures in the examples are example values, not a price list.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object 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. |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Payload
- Python (requests)

Content type

application/json

Example

One page with the default ladder

{

- "url": "[https://example.com/](https://example.com/)",
- "country": "us",
- "tier": "premium",
- "mode": "auto",
- "format": "html",
- "timeout_ms": 60000,
- "max_bytes": 5000000

}

### Response samples

- 200
- 400
- 401
- 402
- 403
- 422
- 424
- 429
- 500
- 503
- 504

Content type

application/json

Example

Page served by the TLS tier on the first attempt (example values)

{

- "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/](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": { }

}

## [tag/Web-Unlocker/operation/startUnlockBatch](https://quanticdata.io/docs/python/#tag/Web-Unlocker/operation/startUnlockBatch) · Unlock many URLs asynchronously

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

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

##### Authorizations:

*bearerAuth*

##### Request Body schema: application/json · required

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

### Responses

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "requests": [
  - {
    - "url": "[https://example.com/a](https://example.com/a)"

    },
  - {
    - "url": "[https://example.com/b](https://example.com/b)",
    - "mode": "browser",
    - "wait_for_selector": "#prices"

    },
  - {
    - "url": "[https://example.com/c](https://example.com/c)"

    }

  ],
- "defaults": {
  - "country": "us",
  - "format": "markdown",
  - "cache_ttl": 3600

  },
- "concurrency": 3,
- "webhook_url": "[https://hooks.example.com/unlock-batch](https://hooks.example.com/unlock-batch)"

}

### Response samples

- 202
- 400
- 401
- 402
- 403
- 429
- 500
- 503
- 504

Content type

application/json

{

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

  },
- "pagination": { }

}

## [tag/Web-Unlocker/operation/getUnlockBatch](https://quanticdata.io/docs/python/#tag/Web-Unlocker/operation/getUnlockBatch) · Poll an unlock batch

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

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

##### Authorizations:

*bearerAuth*

##### path Parameters

| batch_id required | string Example: ub_5e1c9a40d27f Batch id returned by `POST /scraper/unlock/batch`. |
| --- | --- |

##### query Parameters

| include | string Value: "body" `body` adds each item's page to `results`. |
| --- | --- |
| offset | integer >= 0 Default: 0 First result to return. |
| limit | integer [ 1 .. 100 ] Default: 50 How many results to return. |

### Responses

**200**

The batch view. The `cost.usd` figures in the example are example values, not a price list.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object A batch: its progress and the outcome of its items. |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 401
- 404
- 429
- 500
- 503

Content type

application/json

{

- "type": "response",
- "message": "Batch status",
- "payload": {
  - "batch_id": "ub_5e1c9a40d27f",
  - "status": "completed",
  - "total": 3,
  - "completed": 3,
  - "ok": 1,
  - "blocked": 1,
  - "failed": 1,
  - "created_at": "2026-11-11T09:30:00.000Z",
  - "finished_at": "2026-11-11T09:31:02.000Z",
  - "results": [
    - {
      - "index": 0,
      - "url": "[https://example.com/a](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](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](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": { }

}

## [tag/Web-Unlocker/operation/cancelUnlockBatch](https://quanticdata.io/docs/python/#tag/Web-Unlocker/operation/cancelUnlockBatch) · Cancel an unlock batch

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

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

##### Authorizations:

*bearerAuth*

##### path Parameters

| batch_id required | string Example: ub_5e1c9a40d27f Batch id returned by `POST /scraper/unlock/batch`. |
| --- | --- |

### Responses

**200**

Cancelled: the counters of the batch, without `results`.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object A batch: its progress and the outcome of its items. |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 401
- 404
- 429
- 500
- 503

Content type

application/json

{

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

  },
- "pagination": { }

}

## [tag/Web-Unlocker/operation/downloadUnlockerCa](https://quanticdata.io/docs/python/#tag/Web-Unlocker/operation/downloadUnlockerCa) · Download the unlocker CA certificate

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

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

##### Authorizations:

*bearerAuth*

### Responses

**200**

PEM certificate (attachment `qp-unlocker-ca.pem`, cacheable 1h).

##### Response Schema: application/x-pem-file

string

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 401
- 429
- 503

Content type

application/x-pem-file

```
-----BEGIN CERTIFICATE-----
MIIB…
-----END CERTIFICATE-----
```

## [tag/Web-Unlocker/operation/getUnlockOffer](https://quanticdata.io/docs/python/#tag/Web-Unlocker/operation/getUnlockOffer) · Price per GB, packs and options on sale

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

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

### Responses

**200**

The current offer.

Response Headers

| Cache-Control | string `public, max-age=300`. |
| --- | --- |

##### Response Schema: application/json

| available required | boolean Whether at least one tier can be bought right now. |
| --- | --- |
| currency | string Currency of the prices. |
| price_per_gb | object Price of 1 GB (10^9 bytes) on each tier; `null` for a tier that is not on sale. |
| packs_gb | Array of numbers Pack sizes on sale, in GB. |
| validity_days | integer How many days a pack lasts. |
| pay_per_success | boolean `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 | boolean `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 | boolean `true`: DataDome and Cloudflare challenges and the captcha pages of Google and Amazon are handed to the captcha solver. |
| updated_at | string · \<date-time> |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200

Content type

application/json

{

- "available": true,
- "currency": "USD",
- "price_per_gb": {
  - "premium": 0,
  - "mobile": 0

  },
- "packs_gb": [
  - 1,
  - 5,
  - 25,
  - 100,
  - 500

  ],
- "validity_days": 30,
- "pay_per_success": false,
- "free_trial": false,
- "captcha_solver": false,
- "updated_at": "2026-11-11T00:00:00.000Z"

}

## [tag/Web-Unlocker/operation/getUnlockStatus](https://quanticdata.io/docs/python/#tag/Web-Unlocker/operation/getUnlockStatus) · Health of the Web Unlocker from our canary

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

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

### Responses

**200**

The current state, the latest canary and the history.

Response Headers

| Cache-Control | string `public, max-age=300`. |
| --- | --- |

##### Response Schema: application/json

| state required | string Enum: "operational" · "degraded" · "unknown" `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 required | UnlockCanary (object) or null The latest canary run; `null` when there is none yet. |
| history required | Array of objects (UnlockCanarySummary) The last 12 canary runs, newest first. |
| updated_at required | string · \<date-time> |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200

Content type

application/json

{

- "state": "operational",
- "canary": {
  - "measuredAt": "2026-11-11",
  - "runs": 3,
  - "targets": 27,
  - "channel": "engine-local",
  - "provisional": false,
  - "note": "Captcha demo pages (hCaptcha, reCAPTCHA) are run but excluded: interactive captchas are not solved.",
  - "summary": {
    - "calls": 81,
    - "ok": 72,
    - "rate": 88.9,
    - "p50Ms": 4103,
    - "p95Ms": 28793

    },
  - "vendors": {
    - "datadome": {
      - "label": "DataDome",
      - "calls": 9,
      - "ok": 8,
      - "rate": 88.9,
      - "p50Ms": 3557,
      - "p95Ms": 14903

      }

    }

  },
- "history": [
  - {
    - "measuredAt": "2026-11-11",
    - "calls": 81,
    - "ok": 72,
    - "rate": 88.9,
    - "p50Ms": 4103,
    - "p95Ms": 28793

    },
  - {
    - "measuredAt": "2026-11-04",
    - "calls": 51,
    - "ok": 43,
    - "rate": 84.3,
    - "p50Ms": 7212,
    - "p95Ms": 35325

    }

  ],
- "updated_at": "2026-11-11T00:00:00.000Z"

}

## [tag/AI-extraction](https://quanticdata.io/docs/python/#tag/AI-extraction) · AI extraction

Natural-language agents that drive the scraper and return JSON.

## [tag/AI-extraction/operation/aiAgent](https://quanticdata.io/docs/python/#tag/AI-extraction/operation/aiAgent) · Natural-language scraping agent

**Price:** `ai_extract` $0.005 per call, max $1.50 per call · `extract` $0.0015 per call + $3/GB, max $0.02 per call · `serp` $0.0009 per call · `map` $0.003 per call. ai_extract + steps × extract + searches × serp + mapped × map + tokens × ai_token_markup, capped at meters.ai_extract.capUsd. *(list of 2026-10-19)*
**Rate limit:** Per API key, by tier (see Rate limits and tiers).
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/ai.md)

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.

##### Authorizations:

*bearerAuth*

##### Request Body schema: application/json · required

| task required | string Plain-English instruction, e.g. "get every product with its name and price from this page". |
| --- | --- |
| url | string Starting URL, if the task does not already contain one. |

### Responses

**200**

Extraction finished.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "task": "Get every plan and its monthly price",
- "url": "[https://example.com/pricing](https://example.com/pricing)"

}

### Response samples

- 200
- 400
- 401
- 402
- 429
- 500
- 503

Content type

application/json

{

- "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](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": { }

}

## [tag/AI-extraction/operation/aiPlacesFinder](https://quanticdata.io/docs/python/#tag/AI-extraction/operation/aiPlacesFinder) · AI Places Finder

**Price:** `places_ai` $0.005 per call, max $3 per call · `serp_render` $0.002 per call. places_ai + searches × serp_render + tokens × ai_token_markup, capped at meters.places_ai.capUsd. *(list of 2026-10-19)*
**Rate limit:** Per API key, by tier (see Rate limits and tiers).
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/ai.md)

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.

##### Authorizations:

*bearerAuth*

##### Request Body schema: application/json · required

| task required | string |
| --- | --- |
| country | string ISO country override for the proxy exit and `gl`. |
| enrich | boolean Default: true Fill phone/website/hours/address from each business's knowledge panel. |
| max_enrich | number Default: 15 Knowledge-panel lookups budget (cap 30). |

### Responses

**200**

Places found.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object Shared shape of the AI Places and AI Shopping finders. |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "task": "find every car repair shop in Naples",
- "country": "it",
- "max_enrich": 10

}

### Response samples

- 200
- 400
- 401
- 402
- 429
- 500
- 503

Content type

application/json

{

- "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](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": { }

}

## [tag/AI-extraction/operation/aiShoppingFinder](https://quanticdata.io/docs/python/#tag/AI-extraction/operation/aiShoppingFinder) · AI Shopping Finder

**Price:** `shopping_ai` $0.005 per call, max $3 per call · `serp_render` $0.002 per call. shopping_ai + searches × serp_render + tokens × ai_token_markup, capped at meters.shopping_ai.capUsd. *(list of 2026-10-19)*
**Rate limit:** Per API key, by tier (see Rate limits and tiers).
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/ai.md)

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.

##### Authorizations:

*bearerAuth*

##### Request Body schema: application/json · required

| task required | string |
| --- | --- |
| country | string ISO country override for the proxy exit, `gl` and currency. |

### Responses

**200**

Products found.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object Shared shape of the AI Places and AI Shopping finders. |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "task": "cheapest Nintendo Switch OLED",
- "country": "it"

}

### Response samples

- 200
- 400
- 401
- 402
- 429
- 500
- 503

Content type

application/json

{

- "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](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": { }

}

## [tag/AI-visibility](https://quanticdata.io/docs/python/#tag/AI-visibility) · AI visibility

Can AI assistants read and cite a page?

## [tag/AI-visibility/operation/aiVisibilityAudit](https://quanticdata.io/docs/python/#tag/AI-visibility/operation/aiVisibilityAudit) · AI visibility audit

**Price:** `ai_visibility` $0.01 per call · `ai_visibility_citation` $0.01 per call · `serp` $0.0009 per call. ai_visibility + answered (query × engine) × ai_visibility_citation + (2 retrieval + 5 offsite) × serp, only for SERPs that answered. Pre-check reserves the worst case. *(list of 2026-10-19)*
**Rate limit:** Per API key, by tier (see Rate limits and tiers).
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/ai.md)

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.

##### Authorizations:

*bearerAuth*

##### Request Body schema: application/json · required

| url required | string <= 2048 characters |
| --- | --- |
| queries | Array of strings <= 10 items Questions to ask the engines. Absent = on-page audit only. |
| engines | Array of strings Items Enum: "perplexity" · "openai" · "anthropic" · "aio" · "copilot" · "deepseek" Subset of engines for the citation panel; default all six. `deepseek` = our Google top-10 handed to DeepSeek (cheapest). |
| competitors | Array of strings <= 20 items Domains to name explicitly in the share of voice. |
| brand | string <= 80 characters Name to look for in answer text ("mentioned"). |
| country | string (GeoValue) ^([a-zA-Z0-9 ._-]{1,56}\|all)$ Examples: "us" · "it" · "all" Country code or place name: letters, digits, spaces, dots, hyphens, underscores; max 56 characters. `all` means no targeting. |
| no_render | boolean Default: false Skip the rendered pass (cheaper). Alias `noRender`. |
| no_bot_fetch | boolean Default: false Skip the extra request that identifies as an AI crawler. Alias `noBotFetch`. |
| no_retrieval | boolean Default: false Skip the 2 retrievability SERPs (rank for the page's own H1 question, index status). Alias `noRetrieval`. |
| offsite | boolean Default: false Also search the brand on YouTube, Reddit, Wikipedia, LinkedIn and review sites (5 SERPs). |

### Responses

**200**

Audit finished. `billing` says how many citation calls and SERPs were charged.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "url": "[https://example.com/blog/how-to-choose-a-proxy](https://example.com/blog/how-to-choose-a-proxy)",
- "queries": [
  - "how do I choose a residential proxy provider?"

  ],
- "engines": [
  - "perplexity",
  - "aio"

  ],
- "brand": "Example"

}

### Response samples

- 200
- 400
- 401
- 402
- 403
- 429
- 500
- 503

Content type

application/json

{

- "type": "response",
- "message": "AI visibility audit successful",
- "payload": {
  - "url": "[https://example.com/blog/how-to-choose-a-proxy](https://example.com/blog/how-to-choose-a-proxy)",
  - "finalUrl": "[https://example.com/blog/how-to-choose-a-proxy](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](https://example.com/robots.txt)",
    - "blockedCritical": [ ],
    - "sitemaps": [
      - "[https://example.com/sitemap.xml](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": { }

}

## [tag/SEO-audit](https://quanticdata.io/docs/python/#tag/SEO-audit) · SEO audit

No-JS vs rendered view of a page and the diff between them.

## [tag/SEO-audit/operation/seoAudit](https://quanticdata.io/docs/python/#tag/SEO-audit/operation/seoAudit) · No-JS vs rendered SEO audit

**Price:** `seo_audit` $0.003 per call · `extract` $0.0015 per call + $3/GB, max $0.02 per call. seo_audit when the render pass ran; extract when no_render is true or the render pass errored. *(list of 2026-10-19)*
**Rate limit:** Per API key, by tier (see Rate limits and tiers).
**Short alias:** `POST https://api.quanticdata.io/v1/seo-audit` (same handler, primary host only)
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/ai.md)

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.

##### Authorizations:

*bearerAuth*

##### Request Body schema: application/json · required

| url required | string <= 2048 characters |
| --- | --- |
| country | string (GeoValue) ^([a-zA-Z0-9 ._-]{1,56}\|all)$ Examples: "us" · "it" · "all" Country code or place name: letters, digits, spaces, dots, hyphens, underscores; max 56 characters. `all` means no targeting. |
| no_render | boolean Default: false Skip the rendered pass. Alias `noRender`. |

### Responses

**200**

Audit finished.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "url": "[https://example.com](https://example.com)"

}

### Response samples

- 200
- 400
- 401
- 402
- 403
- 429
- 500
- 503

Content type

application/json

{

- "type": "response",
- "message": "SEO audit successful",
- "payload": {
  - "url": "[https://example.com](https://example.com)",
  - "finalUrl": "[https://example.com/](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": { }

}

## [tag/Collectors](https://quanticdata.io/docs/python/#tag/Collectors) · Collectors

Ready-made, versioned scrapers on a semantic input; billed per delivered row. The catalog is dynamic: read it from GET /scraper/collectors.

## [tag/Collectors/operation/listCollectors](https://quanticdata.io/docs/python/#tag/Collectors/operation/listCollectors) · Collector catalog

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

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.

##### Authorizations:

*bearerAuth*

##### query Parameters

| category | string Enum: "search" · "seo" · "social" · "apps" · "real_estate" · "local" · "jobs" · "news" · "ecommerce" · "travel" · "leads" · "company" · "classifieds" · "finance" · "dev" · "knowledge" · "gaming" · "osint" · "research" Only collectors of this category. |
| --- | --- |

### Responses

**200**

Catalog.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 401
- 429
- 503

Content type

application/json

{

- "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": { }

}

## [tag/Collectors/operation/getCollector](https://quanticdata.io/docs/python/#tag/Collectors/operation/getCollector) · One collector

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

The catalog entry of one collector plus its changelog and the last 24 health probes. Free.

##### Authorizations:

*bearerAuth*

##### path Parameters

| slug required | string Example: google_maps_places Collector slug from the catalog. |
| --- | --- |

### Responses

**200**

Collector.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 401
- 404
- 429
- 503

Content type

application/json

{

- "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": { }

}

## [tag/Collectors/operation/runCollector](https://quanticdata.io/docs/python/#tag/Collectors/operation/runCollector) · Run a collector

**Price:** `collector_result` per delivered result, price by collector (see the collector price table). 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. *(list of 2026-10-19)*
**Rate limit:** Per API key, by tier (see Rate limits and tiers).
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/collectors-datasets.md)

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.

##### Authorizations:

*bearerAuth*

##### path Parameters

| slug required | string Example: google_maps_places Collector slug from the catalog. |
| --- | --- |

##### Request Body schema: application/json · required

| async | boolean Default: false Force background processing (202 + statusUrl). |
| --- | --- |
| mode | string Value: "async" Alias of `async: true`. |
| wait | boolean `false` = alias of `async: true`. |
| input | object Optional wrapper for the collector input. |
| property name* additional property | any |

### Responses

**200**

Synchronous run finished with rows.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "query": "pizza restaurants",
- "location": "Brooklyn, NY",
- "country": "us",
- "max_results": 20

}

### Response samples

- 200
- 202
- 400
- 401
- 402
- 404
- 422
- 424
- 429
- 503

Content type

application/json

{

- "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": { }

}

## [tag/Collectors/operation/listCollectorRuns](https://quanticdata.io/docs/python/#tag/Collectors/operation/listCollectorRuns) · Your collector runs

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

Newest first, without result rows. Page with `next_cursor`. Free.

##### Authorizations:

*bearerAuth*

##### query Parameters

| limit | integer [ 1 .. 100 ] Default: 20 |
| --- | --- |
| cursor | string `next_cursor` from the previous page. |
| slug | string Only runs of this collector. |

### Responses

**200**

Runs.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 401
- 429
- 503

Content type

application/json

{

- "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": { }

}

## [tag/Collectors/operation/getCollectorRun](https://quanticdata.io/docs/python/#tag/Collectors/operation/getCollectorRun) · One run with its rows

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

The run you own with its delivered results. `format=csv` streams the rows as CSV (columns follow the collector's `output_schema`). Free.

##### Authorizations:

*bearerAuth*

##### path Parameters

| runId required | string · ^[a-z0-9]{10,40}$ Example: cmgfq2x1b0001 Collector run id (10–40 alphanumeric characters). |
| --- | --- |

##### query Parameters

| format | string Value: "csv" `csv` returns a file instead of the JSON envelope. |
| --- | --- |

### Responses

**200**

Run view (JSON) or CSV file.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 400
- 401
- 404
- 429
- 503

Content type

application/json

{

- "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": { }

}

## [tag/Datasets](https://quanticdata.io/docs/python/#tag/Datasets) · Datasets

Prompt-driven dataset builder: one prompt, a validated table.

## [tag/Datasets/operation/listDatasets](https://quanticdata.io/docs/python/#tag/Datasets/operation/listDatasets) · Your recent dataset runs

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

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.

##### Authorizations:

*bearerAuth*

### Responses

**200**

Datasets.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 401
- 429
- 503

Content type

application/json

{

- "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": { }

}

## [tag/Datasets/operation/createDataset](https://quanticdata.io/docs/python/#tag/Datasets/operation/createDataset) · Build a dataset from a prompt

**Price:** `dataset_row` $0.03 per call · `dataset_row_refresh` $0.01 per call. 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). *(list of 2026-10-19)*
**Rate limit:** Per API key, by tier (see Rate limits and tiers).
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/collectors-datasets.md)

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.

##### Authorizations:

*bearerAuth*

##### Request Body schema: application/json · required

| prompt required | string <= 2000 characters What the dataset is. |
| --- | --- |
| columns | Array of objects Omit to let the planner infer columns from the prompt. |
| country | string (GeoValue) ^([a-zA-Z0-9 ._-]{1,56}\|all)$ Examples: "us" · "it" · "all" Country code or place name: letters, digits, spaces, dots, hyphens, underscores; max 56 characters. `all` means no targeting. |
| sources | object Domain allow/deny lists. |
| limits | object |
| webhook | string <= 2048 characters Public http(s) URL that receives the finished, filtered dataset by POST. |
| refresh | boolean Default: false |
| refreshUrls | Array of strings <= 1000 items [ items <= 2048 characters ] Required with `refresh: true`. |

### Responses

**200**

Dataset job started.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object Answer of a POST that started an async job. |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "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

  }

}

### Response samples

- 200
- 400
- 401
- 402
- 403
- 429
- 500
- 503

Content type

application/json

{

- "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": { }

}

## [tag/Datasets/operation/getDataset](https://quanticdata.io/docs/python/#tag/Datasets/operation/getDataset) · Poll a dataset job

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

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.

##### Authorizations:

*bearerAuth*

##### path Parameters

| jobId required | string Example: job_8f2c1a Job id returned by the POST that started it. |
| --- | --- |

##### query Parameters

| since | integer Row cursor from the previous poll's `nextCursor`. |
| --- | --- |
| mode | string Value: "summary" `summary` omits rows. |

### Responses

**200**

Job view.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object Live job view (from the service) or the stored view of a finished run (`source: storage`, no progress/steps). |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 401
- 404
- 429
- 500
- 503

Content type

application/json

{

- "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](https://example.it)"

        },
      - "_source_url": "[https://example.it/contatti](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": { }

}

## [tag/Datasets/operation/cancelDataset](https://quanticdata.io/docs/python/#tag/Datasets/operation/cancelDataset) · Cancel a dataset job

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

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

##### Authorizations:

*bearerAuth*

##### path Parameters

| jobId required | string Example: job_8f2c1a Job id returned by the POST that started it. |
| --- | --- |

### Responses

**200**

Cancelled.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 401
- 404
- 429
- 500
- 503

Content type

application/json

{

- "type": "response",
- "message": "Dataset cancelled",
- "payload": {
  - "id": "ds_7a1c22",
  - "status": "cancelled"

  },
- "pagination": { }

}

## [tag/Datasets/operation/downloadDataset](https://quanticdata.io/docs/python/#tag/Datasets/operation/downloadDataset) · Download a dataset file

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

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.

##### Authorizations:

*bearerAuth*

##### path Parameters

| jobId required | string Example: job_8f2c1a Job id returned by the POST that started it. |
| --- | --- |

##### query Parameters

| format | string Default: "csv" Enum: "csv" · "json" |
| --- | --- |

### Responses

**200**

File attachment `dataset-{jobId}.csv|json`.

##### Response Schema: text/csv

string

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 400
- 401
- 404
- 429
- 500
- 503

Content type

text/csv

```
company,phone,website,_source_url
Bologna Rent,+39 051 000000,https://example.it,https://example.it/contatti
```

## [tag/Datasets/operation/renameDataset](https://quanticdata.io/docs/python/#tag/Datasets/operation/renameDataset) · Rename a dataset run

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

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.

##### Authorizations:

*bearerAuth*

##### path Parameters

| jobId required | string Example: job_8f2c1a Job id returned by the POST that started it. |
| --- | --- |

##### Request Body schema: application/json · required

| name | string or null <= 120 characters |
| --- | --- |

### Responses

**200**

Renamed.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "name": "Bologna car rentals — October"

}

### Response samples

- 200
- 400
- 401
- 404
- 429
- 503

Content type

application/json

{

- "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": { }

}

## [tag/Datasets/operation/deleteDatasetRecord](https://quanticdata.io/docs/python/#tag/Datasets/operation/deleteDatasetRecord) · Delete a dataset run's stored record

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

Permanently removes the record and its stored rows. A run still in flight must be cancelled first (400). Irreversible. Free.

##### Authorizations:

*bearerAuth*

##### path Parameters

| jobId required | string Example: job_8f2c1a Job id returned by the POST that started it. |
| --- | --- |

### Responses

**200**

Deleted.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 400
- 401
- 404
- 429
- 503

Content type

application/json

{

- "type": "response",
- "message": "Dataset deleted",
- "payload": {
  - "jobId": "ds_7a1c22"

  },
- "pagination": { }

}

## [tag/Parser-presets](https://quanticdata.io/docs/python/#tag/Parser-presets) · Parser presets

Generate CSS selectors once with an LLM, replay them for free, let them self-heal.

## [tag/Parser-presets/operation/generateParser](https://quanticdata.io/docs/python/#tag/Parser-presets/operation/generateParser) · Generate CSS selectors with an LLM, once

**Price:** `parser_generate` $0.02 per call. parser_generate, only when coverage > 0. *(list of 2026-10-19)*
**Rate limit:** Per API key, by tier (see Rate limits and tiers).
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/collectors-datasets.md)

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

##### Authorizations:

*bearerAuth*

##### Request Body schema: application/json · required

| url | string <= 2048 characters Required unless `html` is given. |
| --- | --- |
| html | string |
| fields | object <= 25 properties field name → what it is. Required unless `prompt` is given. |
| prompt | string <= 2000 characters Free-text alternative to `fields` (the model names them). |
| render | boolean Default: false |
| country | string (GeoValue) ^([a-zA-Z0-9 ._-]{1,56}\|all)$ Examples: "us" · "it" · "all" Country code or place name: letters, digits, spaces, dots, hyphens, underscores; max 56 characters. `all` means no targeting. |

### Responses

**200**

Parser generated (message says when no usable selector could be produced; then not charged).

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "url": "[https://example.com/products/42](https://example.com/products/42)",
- "fields": {
  - "title": "product name",
  - "price": "current price with currency",
  - "sku": "SKU code"

  }

}

### Response samples

- 200
- 400
- 401
- 402
- 403
- 429
- 500
- 503

Content type

application/json

{

- "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": { }

}

## [tag/Parser-presets/operation/listParserPresets](https://quanticdata.io/docs/python/#tag/Parser-presets/operation/listParserPresets) · List your presets

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

Every stored parser of your account with its stats and version history. Free.

##### Authorizations:

*bearerAuth*

### Responses

**200**

Presets.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 401
- 429
- 500
- 503

Content type

application/json

{

- "type": "response",
- "message": "Presets",
- "payload": {
  - "presets": [
    - {
      - "id": "pst_7Qk3",
      - "name": "example-product",
      - "sourceUrl": "[https://example.com/products/42](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": { }

}

## [tag/Parser-presets/operation/createParserPreset](https://quanticdata.io/docs/python/#tag/Parser-presets/operation/createParserPreset) · Save a parser as a preset

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

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.

##### Authorizations:

*bearerAuth*

##### Request Body schema: application/json · required

| name required | string <= 120 characters |
| --- | --- |
| parser required | object (ExtractSchema) Examples: {"title":"h1","price":".price","image":{"selector":"img.hero","attr":"src"},"features":{"selector":"li.feature","all":true}} Non-empty, at most 25 fields. |
| sourceUrl | string <= 2048 characters Page the parser was learned from — self-healing refetches it. |
| fields | object field → description, so a heal can regenerate the same shape. |
| render | boolean Default: false |
| autoHeal | boolean |

### Responses

**200**

Created.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "name": "example-product",
- "parser": {
  - "title": "h1.product-title",
  - "price": "span.price"

  },
- "sourceUrl": "[https://example.com/products/42](https://example.com/products/42)",
- "fields": {
  - "title": "product name",
  - "price": "current price"

  },
- "autoHeal": true

}

### Response samples

- 200
- 400
- 401
- 429
- 500
- 503

Content type

application/json

{

- "type": "response",
- "message": "Preset created",
- "payload": {
  - "id": "pst_7Qk3",
  - "name": "example-product",
  - "sourceUrl": "[https://example.com/products/42](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": { }

}

## [tag/Parser-presets/operation/getParserPreset](https://quanticdata.io/docs/python/#tag/Parser-presets/operation/getParserPreset) · Read a preset

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

Parser, stats and version history. A preset belonging to someone else answers 404. Free.

##### Authorizations:

*bearerAuth*

##### path Parameters

| id required | string Example: pst_7Qk3 Preset id returned when it was created. |
| --- | --- |

### Responses

**200**

Preset.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 401
- 404
- 429
- 500
- 503

Content type

application/json

{

- "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": { }

}

## [tag/Parser-presets/operation/updateParserPreset](https://quanticdata.io/docs/python/#tag/Parser-presets/operation/updateParserPreset) · Update a preset

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

Rename, replace the parser (bumps the version), toggle `autoHeal`, update `fields`/`sourceUrl`. Only the keys you send change. Free.

##### Authorizations:

*bearerAuth*

##### path Parameters

| id required | string Example: pst_7Qk3 Preset id returned when it was created. |
| --- | --- |

##### Request Body schema: application/json · required

| name | string |
| --- | --- |
| parser | object (ExtractSchema) Examples: {"title":"h1","price":".price","image":{"selector":"img.hero","attr":"src"},"features":{"selector":"li.feature","all":true}} Non-empty, at most 25 fields. |
| autoHeal | boolean |
| fields | object |
| sourceUrl | string |

### Responses

**200**

Updated.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "autoHeal": false

}

### Response samples

- 200
- 400
- 401
- 404
- 429
- 500
- 503

Content type

application/json

{

- "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": { }

}

## [tag/Parser-presets/operation/deleteParserPreset](https://quanticdata.io/docs/python/#tag/Parser-presets/operation/deleteParserPreset) · Delete a preset

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

Removes the preset and its version history. Scrapes that still send its `presetId` answer 404 afterwards. Free.

##### Authorizations:

*bearerAuth*

##### path Parameters

| id required | string Example: pst_7Qk3 Preset id returned when it was created. |
| --- | --- |

### Responses

**200**

Deleted.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 401
- 404
- 429
- 500
- 503

Content type

application/json

{

- "type": "response",
- "message": "Preset deleted",
- "payload": {
  - "ok": true

  },
- "pagination": { }

}

## [tag/Parser-presets/operation/healParserPreset](https://quanticdata.io/docs/python/#tag/Parser-presets/operation/healParserPreset) · Regenerate a preset's parser now

**Price:** `parser_generate` $0.02 per call. parser_generate only when healed is true. *(list of 2026-10-19)*
**Rate limit:** Per API key, by tier (see Rate limits and tiers).
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/collectors-datasets.md)

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`).

##### Authorizations:

*bearerAuth*

##### path Parameters

| id required | string Example: pst_7Qk3 Preset id returned when it was created. |
| --- | --- |

##### Request Body schema: application/json · optional

| force | boolean Default: false |
| --- | --- |

### Responses

**200**

Heal attempted (message says whether a new version was adopted).

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "force": false

}

### Response samples

- 200
- 400
- 401
- 402
- 404
- 429
- 500
- 503

Content type

application/json

{

- "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": { }

}

## [tag/Parser-presets/operation/getParserPresetStats](https://quanticdata.io/docs/python/#tag/Parser-presets/operation/getParserPresetStats) · How well a preset still works

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

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.

##### Authorizations:

*bearerAuth*

##### path Parameters

| id required | string Example: pst_7Qk3 Preset id returned when it was created. |
| --- | --- |

### Responses

**200**

Stats.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 401
- 404
- 429
- 500
- 503

Content type

application/json

{

- "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": { }

}

## [tag/Proxies](https://quanticdata.io/docs/python/#tag/Proxies) · Proxies

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` shares a lookup budget of about 45 calls a minute. Every call also counts in the hourly window of your API key (see Rate limits and tiers).

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

| Plan type (`planType`) | Rotating strings | Sticky strings | New IP on demand |
| --- | --- | --- | --- |
| `residentialbasic`, `datacentertraffic` | New IP per request | Same IP for `sessionTime` | `rotate` or a rotation link: same string, new IP |
| `residentialpremium`, `resiprivate`, `mobile_v2`, `mobile`, `ipv6` | New IP per request | Same IP for `sessionTime` | Request a new sticky string with `generate` |
| `datacenter` | Assigned by the gateway | Assigned by the gateway | Not applicable |
| `isp`, `isppremium` | Static IPs | Static IPs | Not applicable: dedicated static IPs |

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

Build proxy strings with `generate` and use them as returned; do not edit them by hand.

## [tag/Proxies/operation/listProxies](https://quanticdata.io/docs/python/#tag/Proxies/operation/listProxies) · List your proxy plans

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

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

##### Authorizations:

*bearerAuth*

##### query Parameters

| limit | integer <= 100 Default: 50 |
| --- | --- |
| offset | integer Default: 0 |
| planType | string Enum: "residentialbasic" · "residentialpremium" · "resiprivate" · "isp" · "isppremium" · "datacenter" · "datacentertraffic" · "ipv6" · "mobile" · "mobile_v2" |
| active | string Enum: "true" · "false" Filter by expiry; omit for all. |

### Responses

**200**

Plans.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 400
- 401
- 429
- 500

Content type

application/json

{

- "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": { }

}

## [tag/Proxies/operation/generateProxies](https://quanticdata.io/docs/python/#tag/Proxies/operation/generateProxies) · Generate proxy strings for a plan

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

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

##### Authorizations:

*bearerAuth*

##### Request Body schema: application/json · required

| orderId required | string From GET /public/proxies. |
| --- | --- |
| protocol | string Default: "http" Enum: "http" · "socks5" |
| format | string Default: "user:pass@host:port" Enum: "user:pass@host:port" · "host:port:user:pass" · "http://user:pass@host:port" · "socks5://user:pass@host:port" `ip:port:user:pass` and the `…@ip:port` spellings are accepted as aliases. |
| quantity | integer [ 1 .. 10000 ] Default: 10 |
| country | string Lowercase country code (e.g. `us`); `all` = none. |
| state | string Region slug (Residential Premium / Mobile V2: from the location tree). Alias `region`. |
| city | string City slug. |
| rotation | string Default: "rotating" Enum: "rotating" · "sticky" · "static" `static` is IPv6 only. |
| sessionTime | integer [ 1 .. 1440 ] Default: 10 Sticky session minutes (Residential Basic / Datacenter traffic: min 3 enforced by the gateway). |
| superSticky | boolean Default: false 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 | boolean Default: false 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 | string ISP code (Residential Premium / Mobile V2) or carrier ASN (Mobile). |
| asn | string ASN, e.g. `AS12345` (Residential Basic / Datacenter traffic). |
| strict | boolean Default: false Residential/Datacenter Basic: `true` allows location fallback. |
| os | string Default: "any" Enum: "any" · "windows" · "android" · "ios" · "macos" 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 | string Enum: "speed" · "speed-quality" · "quality" Residential Premium / Mobile V2 pool filter (default: max pool). |
| isExtension | boolean Default: false Rewrite hostnames with a unique prefix so a browser extension cannot cache the proxy (needs the wildcard DNS of the gateway). |
| ip | string Mobile V2: a whitelisted IP — returns the IP-auth proxy list instead of user:pass strings. |
| gateway | string Default: "ww" Enum: "ww" · "us" · "eu" · "as" 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. |

### Responses

**200**

Proxy strings. Example: two sticky US lines of a Residential Premium plan.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "orderId": "ord_8c21",
- "protocol": "http",
- "format": "user:pass@host:port",
- "quantity": 2,
- "country": "us",
- "rotation": "sticky",
- "sessionTime": 10

}

### Response samples

- 200
- 202
- 400
- 401
- 403
- 404
- 429
- 500
- 502

Content type

application/json

{

- "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": { }

}

## [tag/Proxies/operation/getIpInfo](https://quanticdata.io/docs/python/#tag/Proxies/operation/getIpInfo) · Geolocate an IP

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

Country, region, city, coordinates, timezone, ISP and ASN of an IP address — useful to verify where a sticky session actually exits. Served by a third-party geolocation source with its own fair-use limit (about 45 lookups/minute shared). Free.

##### Authorizations:

*bearerAuth*

##### query Parameters

| ip required | string Example: ip=203.0.113.7 |
| --- | --- |

### Responses

**200**

IP information.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 400
- 401
- 429
- 500

Content type

application/json

{

- "type": "response",
- "message": "Success",
- "payload": {
  - "ip": "203.0.113.7",
  - "country": "United States",
  - "countryCode": "US",
  - "flag": "🇺🇸",
  - "region": "California",
  - "regionCode": "CA",
  - "city": "Los Angeles",
  - "zip": "90001",
  - "lat": 34.05,
  - "lon": -118.24,
  - "timezone": "America/Los_Angeles",
  - "isp": "Example Telecom",
  - "org": "Example Telecom LLC",
  - "as": "AS64496 Example Telecom"

  },
- "pagination": { }

}

## [tag/Proxies/operation/getIpEcho](https://quanticdata.io/docs/python/#tag/Proxies/operation/getIpEcho) · Where your IP is, as Cloudflare sees it

**Price:** No charge.
**Rate limit:** None of its own; the edge's limits apply.
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/proxies.md)

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.

### Responses

**200**

The caller's IP and Cloudflare's location for it.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object 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. |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

r = requests.get(
    'https://api.quanticdata.io/v1/public/ip-echo',
    timeout=120,
)
data = r.json()
if data["type"] != "response":
    raise SystemExit(data["message"])
print(data["payload"])
```

### Response samples

- 200

Content type

application/json

{

- "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": { }

}

## [tag/Proxies/operation/listWhitelistIps](https://quanticdata.io/docs/python/#tag/Proxies/operation/listWhitelistIps) · List whitelisted IPs of an order

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

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.

##### Authorizations:

*bearerAuth*

##### query Parameters

| orderId required | string |
| --- | --- |

### Responses

**200**

Whitelist.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

r = requests.get(
    'https://api.quanticdata.io/v1/public/proxies/whitelist-ip?orderId=ORDERID',
    headers={"Authorization": "Bearer qd_live_YOUR_API_KEY"},
    timeout=120,
)
data = r.json()
if data["type"] != "response":
    raise SystemExit(data["message"])
print(data["payload"])
```

### Response samples

- 200
- 400
- 401
- 403
- 404
- 429
- 500

Content type

application/json

{

- "type": "response",
- "message": "Success",
- "payload": {
  - "orderId": "ord_8c21",
  - "whitelist_ip": [
    - "203.0.113.7"

    ]

  },
- "pagination": { }

}

## [tag/Proxies/operation/addWhitelistIp](https://quanticdata.io/docs/python/#tag/Proxies/operation/addWhitelistIp) · Whitelist an IP

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

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.

##### Authorizations:

*bearerAuth*

##### Request Body schema: application/json · required

| orderId required | string |
| --- | --- |
| ip required | string · ^(\d{1,3}\.){3}\d{1,3}$ IPv4 address. |
| action | string Default: "add" Enum: "add" · "update" Mobile V2 only: `update` edits an existing entry's settings. |
| ports_count | integer [ 1 .. 1000 ] Mobile V2: ports to allocate. |
| protocol | string Enum: "HTTP" · "SOCKS5" Mobile V2. |
| country | string Mobile V2 geo targeting for the allocated ports. |
| region | string Mobile V2. |
| city | string Mobile V2. |
| isp | string Mobile V2. |
| sticky | boolean Mobile V2: keep the same IP per port. |
| ttl | integer Mobile V2: sticky session TTL in seconds. |

### Responses

**200**

Whitelisted (or not applicable to this plan type).

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "orderId": "ord_8c21",
- "ip": "203.0.113.7"

}

### Response samples

- 200
- 400
- 401
- 403
- 404
- 429
- 500

Content type

application/json

{

- "type": "response",
- "message": "IP whitelisted successfully",
- "payload": {
  - "ip": "203.0.113.7",
  - "whitelisted": true,
  - "whitelist_ip": [
    - "203.0.113.7"

    ]

  },
- "pagination": { }

}

## [tag/Proxies/operation/removeWhitelistIp](https://quanticdata.io/docs/python/#tag/Proxies/operation/removeWhitelistIp) · Remove a whitelisted IP

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

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.

##### Authorizations:

*bearerAuth*

##### Request Body schema: application/json · required

| orderId required | string |
| --- | --- |
| ip required | string |
| id | string Mobile V2 entry id (alternative handle). |

### Responses

**200**

Removed (or not applicable).

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "orderId": "ord_8c21",
- "ip": "203.0.113.7"

}

### Response samples

- 200
- 400
- 401
- 403
- 404
- 429
- 500

Content type

application/json

{

- "type": "response",
- "message": "IP removed from whitelist",
- "payload": {
  - "ip": "203.0.113.7",
  - "removed": true,
  - "whitelist_ip": [ ]

  },
- "pagination": { }

}

## [tag/Proxies/operation/rotateProxySession](https://quanticdata.io/docs/python/#tag/Proxies/operation/rotateProxySession) · Rotate a sticky session (new IP, same string)

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

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.

##### Authorizations:

*bearerAuth*

##### path Parameters

| orderId required | string Example: ord_8c21 Order id of the plan (`orderId` in `GET /public/proxies`). |
| --- | --- |

##### Request Body schema: application/json · required

| proxy | string <= 2048 characters A sticky proxy string of this plan, exactly as `generate` returned it (any format). |
| --- | --- |
| sessionId | string · ^[A-Za-z0-9]{1,32}$ Instead of `proxy`: the session of your sticky string. |
| protocol | string Default: "http" Enum: "http" · "socks5" With `sessionId`: the protocol of your sticky string. |
| port | integer With `sessionId`, instead of `protocol`: the port of your sticky string. |

### Responses

**200**

Session restarted.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object A restarted sticky session. The next request on the same proxy string gets a new IP. |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "proxy": "user_8c21-country-us-session-a1b2c3-time-10:p4ssw0rd@residential-ww.quanticdata.io:9999"

}

### Response samples

- 200
- 400
- 401
- 403
- 404
- 409
- 410
- 429
- 502
- 503

Content type

application/json

{

- "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": { }

}

## [tag/Proxies/operation/listRotationLinks](https://quanticdata.io/docs/python/#tag/Proxies/operation/listRotationLinks) · List rotation links of a plan

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

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.

##### Authorizations:

*bearerAuth*

##### path Parameters

| orderId required | string Example: ord_8c21 Order id of the plan (`orderId` in `GET /public/proxies`). |
| --- | --- |

##### query Parameters

| includeRevoked | boolean Default: false Include revoked links. |
| --- | --- |

### Responses

**200**

Rotation links.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 400
- 401
- 403
- 404
- 409
- 429
- 503

Content type

application/json

{

- "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": { }

}

## [tag/Proxies/operation/createRotationLinks](https://quanticdata.io/docs/python/#tag/Proxies/operation/createRotationLinks) · Create rotation links

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

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.

##### Authorizations:

*bearerAuth*

##### path Parameters

| orderId required | string Example: ord_8c21 Order id of the plan (`orderId` in `GET /public/proxies`). |
| --- | --- |

##### Request Body schema: application/json · required

| proxy | string <= 2048 characters A sticky proxy string of this plan, exactly as `generate` returned it (any format). |
| --- | --- |
| sessionId | string · ^[A-Za-z0-9]{1,32}$ Instead of `proxy`: the session of your sticky string. |
| protocol | string Default: "http" Enum: "http" · "socks5" With `sessionId`: the protocol of your sticky string. |
| port | integer With `sessionId`, instead of `protocol`: the port of your sticky string. |
| proxies | Array of strings [ 1 .. 100 ] items [ items <= 2048 characters ] Several sticky proxy strings of this plan: one link per string. |
| label | string <= 64 characters Optional name stored on every link created by this call: letters, digits, spaces and . _ : # / - |

### Responses

**201**

Links created. Each `url` is shown once.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "proxy": "user_8c21-country-us-session-a1b2c3-time-10:p4ssw0rd@residential-ww.quanticdata.io:9999",
- "label": "Profile 12"

}

### Response samples

- 201
- 400
- 401
- 403
- 404
- 409
- 410
- 429
- 503

Content type

application/json

{

- "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](https://api.quanticdata.io/v1/public/rotate/rl_6f1c0e2b9a7d4c3e8f5a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e)",
      - "token": "rl_6f1c0e2b9a7d4c3e8f5a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e"

      }

    ]

  },
- "pagination": { }

}

## [tag/Proxies/operation/revokeRotationLink](https://quanticdata.io/docs/python/#tag/Proxies/operation/revokeRotationLink) · Revoke a rotation link

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

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.

##### Authorizations:

*bearerAuth*

##### path Parameters

| orderId required | string Example: ord_8c21 Order id of the plan (`orderId` in `GET /public/proxies`). |
| --- | --- |
| linkId required | string Example: rlk_3f9a1c7e5b2d4a6c8e0f1a2b Link id (`id` in the link list). |

### Responses

**200**

Link revoked.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

r = requests.delete(
    'https://api.quanticdata.io/v1/public/proxies/ord_8c21/rotation-links/rlk_3f9a1c7e5b2d4a6c8e0f1a2b',
    headers={"Authorization": "Bearer qd_live_YOUR_API_KEY"},
    timeout=120,
)
data = r.json()
if data["type"] != "response":
    raise SystemExit(data["message"])
print(data["payload"])
```

### Response samples

- 200
- 401
- 403
- 404
- 409
- 429
- 503

Content type

application/json

{

- "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": { }

}

## [tag/Proxies/operation/useRotationLink](https://quanticdata.io/docs/python/#tag/Proxies/operation/useRotationLink) · Call a rotation link

**Price:** No charge.
**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.
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/proxies.md)

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.

##### path Parameters

| token required | string · ^rl_[a-f0-9]{64}$ Example: rl_6f1c0e2b9a7d4c3e8f5a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e The token at the end of the link URL. |
| --- | --- |

### Responses

**200**

Session restarted.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object A restarted sticky session. The next request on the same proxy string gets a new IP. |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

r = requests.get(
    'https://api.quanticdata.io/v1/public/rotate/rl_6f1c0e2b9a7d4c3e8f5a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e',
    timeout=120,
)
data = r.json()
if data["type"] != "response":
    raise SystemExit(data["message"])
print(data["payload"])
```

### Response samples

- 200
- 403
- 404
- 409
- 410
- 429
- 502
- 503

Content type

application/json

{

- "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": { }

}

## [tag/Proxies/operation/useRotationLinkPost](https://quanticdata.io/docs/python/#tag/Proxies/operation/useRotationLinkPost) · Call a rotation link (POST)

**Price:** No charge.
**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.
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/proxies.md)

Same as `GET /public/rotate/{token}`, for tools that can only send POST. No API key, no header, no body.

##### path Parameters

| token required | string · ^rl_[a-f0-9]{64}$ Example: rl_6f1c0e2b9a7d4c3e8f5a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e The token at the end of the link URL. |
| --- | --- |

### Responses

**200**

Session restarted.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object A restarted sticky session. The next request on the same proxy string gets a new IP. |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

r = requests.post(
    'https://api.quanticdata.io/v1/public/rotate/rl_6f1c0e2b9a7d4c3e8f5a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e',
    timeout=120,
)
data = r.json()
if data["type"] != "response":
    raise SystemExit(data["message"])
print(data["payload"])
```

### Response samples

- 200
- 403
- 404
- 409
- 410
- 429
- 502
- 503

Content type

application/json

{

- "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": { }

}

## [tag/Premium-ISP](https://quanticdata.io/docs/python/#tag/Premium-ISP)Premium ISP

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.

## [tag/Premium-ISP/operation/listPremiumIspPools](https://quanticdata.io/docs/python/#tag/Premium-ISP/operation/listPremiumIspPools) · List Premium ISP pools

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

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.

##### Authorizations:

*bearerAuth*

##### query Parameters

| country | string ISO 3166-1 alpha-2 filter, e.g. `US`. |
| --- | --- |

### Responses

**200**

Pools.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 400
- 401
- 403
- 429
- 503

Content type

application/json

{

- "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": { }

}

## [tag/Premium-ISP/operation/listPremiumIspCities](https://quanticdata.io/docs/python/#tag/Premium-ISP/operation/listPremiumIspCities) · List Premium ISP cities with stock

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

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.

##### Authorizations:

*bearerAuth*

##### query Parameters

| type | string Default: "city" Enum: "city" · "fraud-score-0" |
| --- | --- |
| udp | string Default: "0" Enum: "0" · "1" `1` for UDP-capable IPs. |
| country | string ISO 3166-1 alpha-2 filter. |

### Responses

**200**

Catalog.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object 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. |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 400
- 401
- 403
- 429
- 503

Content type

application/json

{

- "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": { }

}

## [tag/Premium-ISP/operation/listPremiumIspCarriers](https://quanticdata.io/docs/python/#tag/Premium-ISP/operation/listPremiumIspCarriers) · List the carriers (ASN) of a city

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

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.

##### Authorizations:

*bearerAuth*

##### query Parameters

| location required | string `location` from `GET /public/premium-isp/cities`. |
| --- | --- |
| type | string Default: "city" Enum: "city" · "fraud-score-0" |
| udp | string Default: "0" Enum: "0" · "1" |

### Responses

**200**

Carriers.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

r = requests.get(
    'https://api.quanticdata.io/v1/public/premium-isp/cities/carriers?location=LOCATION',
    headers={"Authorization": "Bearer qd_live_YOUR_API_KEY"},
    timeout=120,
)
data = r.json()
if data["type"] != "response":
    raise SystemExit(data["message"])
print(data["payload"])
```

### Response samples

- 200
- 400
- 401
- 403
- 409
- 429
- 503

Content type

application/json

{

- "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": { }

}

## [tag/Premium-ISP/operation/quotePremiumIsp](https://quanticdata.io/docs/python/#tag/Premium-ISP/operation/quotePremiumIsp) · Quote a Premium ISP selection

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

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.

##### Authorizations:

*bearerAuth*

##### Request Body schema: application/json · required

| product required | string Enum: "pool" · "city" |
| --- | --- |
| quantity required | integer >= 1 Number of IPs, within the length's or pool's minQuantity/maxQuantity: exactly 256 for a subnet pool. |
| poolId | string Pool id from `GET /public/premium-isp/pools` (pool only). A `-subnet` pool buys a whole /24. |
| type | string Default: "city" Enum: "city" · "fraud-score-0" City plans only. `fraud-score-0`: every IP is checked for a fraud score of 0 before delivery. |
| length | string Enum: "1_day" · "7_days" · "1_month" · "2_months" · "3_months" City plans only; the lengths on sale are listed by the catalog. |
| location | string 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 | integer or null Default: null 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 | boolean Default: false City plans only: UDP-capable IPs. |
| ispNameCheck | boolean Deprecated Default: false 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 | object or null 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. |
| replacements | integer [ 0 .. 5 ] Default: 0 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. |
| paymentMethod | string Default: "BALANCE" Value: "BALANCE" |

### Responses

**200**

Quote.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object Server-side price of a selection. Nothing is reserved (`reserved: false`). |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Payload
- Python (requests)

Content type

application/json

Example

city

{

- "product": "city",
- "type": "city",
- "length": "1_month",
- "location": "United States - New York City",
- "asn": 7922,
- "udp": false,
- "replacements": 2,
- "quantity": 10

}

### Response samples

- 200
- 400
- 401
- 403
- 409
- 429
- 503

Content type

application/json

{

- "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": { }

}

## [tag/Premium-ISP/operation/listPremiumIspOrders](https://quanticdata.io/docs/python/#tag/Premium-ISP/operation/listPremiumIspOrders) · List Premium ISP orders

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

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.

##### Authorizations:

*bearerAuth*

##### query Parameters

| limit | integer <= 100 Default: 50 |
| --- | --- |
| offset | integer Default: 0 |

### Responses

**200**

Orders.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 400
- 401
- 403
- 429
- 503

Content type

application/json

{

- "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": { }

}

## [tag/Premium-ISP/operation/createPremiumIspOrder](https://quanticdata.io/docs/python/#tag/Premium-ISP/operation/createPremiumIspOrder) · Buy Premium ISP IPs from the balance

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

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.

##### Authorizations:

*bearerAuth*

##### header Parameters

| Idempotency-Key required | string · ^[a-zA-Z0-9-]{16,128}$ 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`. |
| --- | --- |

##### Request Body schema: application/json · required

| product required | string Enum: "pool" · "city" |
| --- | --- |
| quantity required | integer >= 1 Number of IPs, within the length's or pool's minQuantity/maxQuantity: exactly 256 for a subnet pool. |
| poolId | string Pool id from `GET /public/premium-isp/pools` (pool only). A `-subnet` pool buys a whole /24. |
| type | string Default: "city" Enum: "city" · "fraud-score-0" City plans only. `fraud-score-0`: every IP is checked for a fraud score of 0 before delivery. |
| length | string Enum: "1_day" · "7_days" · "1_month" · "2_months" · "3_months" City plans only; the lengths on sale are listed by the catalog. |
| location | string 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 | integer or null Default: null 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 | boolean Default: false City plans only: UDP-capable IPs. |
| ispNameCheck | boolean Deprecated Default: false 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 | object or null 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. |
| replacements | integer [ 0 .. 5 ] Default: 0 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. |
| paymentMethod | string Default: "BALANCE" Value: "BALANCE" |
| maxTotal | number Highest total you accept, in USD. Above it: 409 `PRICE_CHANGED`, nothing charged. |

### Responses

**200**

Replayed: this Idempotency-Key was already used for this selection. Nothing new was charged.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

**201**

Delivered.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Payload
- Python (requests)

Content type

application/json

Example

city

{

- "product": "city",
- "type": "city",
- "length": "1_month",
- "location": "United States - New York City",
- "asn": 7922,
- "udp": false,
- "replacements": 2,
- "quantity": 10

}

### Response samples

- 200
- 201
- 202
- 400
- 401
- 402
- 403
- 409
- 422
- 429
- 503

Content type

application/json

{

- "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": { }

}

## [tag/Premium-ISP/operation/getPremiumIspOrder](https://quanticdata.io/docs/python/#tag/Premium-ISP/operation/getPremiumIspOrder) · Get a Premium ISP order and its proxy lines

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

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.

##### Authorizations:

*bearerAuth*

##### path Parameters

| orderId required | string `id` of the order (from `POST /public/premium-isp/orders` or `GET /public/premium-isp/orders`). |
| --- | --- |

##### query Parameters

| include | string Value: "lines" |
| --- | --- |
| protocol | string Default: "http" Enum: "http" · "socks5" |
| format | string Default: "host:port:user:pass" Enum: "host:port:user:pass" · "ip:port:user:pass" · "user:pass@host:port" · "http://user:pass@host:port" · "socks5://user:pass@host:port" |
| quantity | integer >= 1 Return only the first N lines. |
| server | string 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. |

### Responses

**200**

Order (and lines).

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 202
- 400
- 401
- 403
- 404
- 409
- 429
- 503

Content type

application/json

{

- "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

      }

    },
  - "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": { }

}

## [tag/Premium-ISP/operation/quotePremiumIspRenewal](https://quanticdata.io/docs/python/#tag/Premium-ISP/operation/quotePremiumIspRenewal) · Quote a Premium ISP renewal

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

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.

##### Authorizations:

*bearerAuth*

##### path Parameters

| orderId required | string `id` of the order (from `POST /public/premium-isp/orders` or `GET /public/premium-isp/orders`). |
| --- | --- |

### Responses

**200**

Renewal quote.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 400
- 401
- 403
- 404
- 409
- 429
- 503

Content type

application/json

{

- "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": { }

}

## [tag/Premium-ISP/operation/renewPremiumIspOrder](https://quanticdata.io/docs/python/#tag/Premium-ISP/operation/renewPremiumIspOrder) · Renew a Premium ISP plan from the balance

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

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.

##### Authorizations:

*bearerAuth*

##### path Parameters

| orderId required | string `id` of the order (from `POST /public/premium-isp/orders` or `GET /public/premium-isp/orders`). |
| --- | --- |

##### header Parameters

| Idempotency-Key required | string · ^[a-zA-Z0-9-]{16,128}$ 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`. |
| --- | --- |

##### Request Body schema: application/json · optional

| days | integer Optional. One of the `days` in the quote's `options`; without it, the plan's own term. |
| --- | --- |

### Responses

**200**

Renewed.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "days": 30

}

### Response samples

- 200
- 202
- 400
- 401
- 402
- 403
- 404
- 409
- 429
- 503

Content type

application/json

{

- "type": "response",
- "message": "Success",
- "payload": {
  - "renewed": true,
  - "daysAdded": 30,
  - "newExpiry": "2026-12-18T10:00:00.000Z"

  },
- "pagination": { }

}

## [tag/Premium-ISP/operation/getPremiumIspReplacements](https://quanticdata.io/docs/python/#tag/Premium-ISP/operation/getPremiumIspReplacements) · IP swaps of a city plan

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

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). Pools have no API replacements (their 24-hour replacement goes through support). Free.

##### Authorizations:

*bearerAuth*

##### path Parameters

| orderId required | string `id` of the order (from `POST /public/premium-isp/orders` or `GET /public/premium-isp/orders`). |
| --- | --- |

### Responses

**200**

IP swaps.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 400
- 401
- 403
- 404
- 409
- 429
- 503

Content type

application/json

{

- "type": "response",
- "message": "Success",
- "payload": {
  - "bought": 2,
  - "used": 0,
  - "checking": 0,
  - "left": 2,
  - "paid": 0,
  - "paidSwapPrice": 1.5

  },
- "pagination": { }

}

## [tag/Premium-ISP/operation/replacePremiumIspIp](https://quanticdata.io/docs/python/#tag/Premium-ISP/operation/replacePremiumIspIp) · Replace one IP of a city plan

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

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`). 30 replacements an hour per account.

##### Authorizations:

*bearerAuth*

##### path Parameters

| orderId required | string `id` of the order (from `POST /public/premium-isp/orders` or `GET /public/premium-isp/orders`). |
| --- | --- |

##### Request Body schema: application/json · required

| ip required | string One of the plan's exit IPs (`lines.ipAddresses`). |
| --- | --- |
| pay | boolean Default: false 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. |

### Responses

**200**

Replaced.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "ip": "203.0.113.7",
- "pay": false

}

### Response samples

- 200
- 202
- 400
- 401
- 402
- 403
- 404
- 409
- 429
- 502
- 503

Content type

application/json

{

- "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": { }

}

## [tag/Premium-ISP/operation/getPremiumIspAutoReplace](https://quanticdata.io/docs/python/#tag/Premium-ISP/operation/getPremiumIspAutoReplace) · Auto-replace setting of a city plan

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

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.

##### Authorizations:

*bearerAuth*

##### path Parameters

| orderId required | string `id` of the order (from `POST /public/premium-isp/orders` or `GET /public/premium-isp/orders`). |
| --- | --- |

### Responses

**200**

The setting.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

r = requests.get(
    'https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/auto-replace',
    headers={"Authorization": "Bearer qd_live_YOUR_API_KEY"},
    timeout=120,
)
data = r.json()
if data["type"] != "response":
    raise SystemExit(data["message"])
print(data["payload"])
```

### Response samples

- 200
- 400
- 401
- 403
- 404
- 409
- 429
- 503

Content type

application/json

{

- "type": "response",
- "message": "Success",
- "payload": {
  - "available": true,
  - "state": "on",
  - "ips": 5

  },
- "pagination": { }

}

## [tag/Premium-ISP/operation/setPremiumIspAutoReplace](https://quanticdata.io/docs/python/#tag/Premium-ISP/operation/setPremiumIspAutoReplace) · Switch auto-replace on or off

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

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.

##### Authorizations:

*bearerAuth*

##### path Parameters

| orderId required | string `id` of the order (from `POST /public/premium-isp/orders` or `GET /public/premium-isp/orders`). |
| --- | --- |

##### Request Body schema: application/json · required

| enabled required | boolean `true` = replace offline IPs by itself; `false` = never replace an IP without a request. |
| --- | --- |

### Responses

**200**

Changed.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "enabled": false

}

### Response samples

- 200
- 400
- 401
- 403
- 404
- 409
- 429
- 503

Content type

application/json

{

- "type": "response",
- "message": "Auto-replace switched off.",
- "payload": {
  - "available": true,
  - "state": "off",
  - "ips": 5

  },
- "pagination": { }

}

## [tag/IPv6](https://quanticdata.io/docs/python/#tag/IPv6) · IPv6

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

## [tag/IPv6/operation/listIpv6SpeedPlans](https://quanticdata.io/docs/python/#tag/IPv6/operation/listIpv6SpeedPlans) · List IPv6 speed plans

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

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

##### Authorizations:

*bearerAuth*

### Responses

**200**

The grid.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object 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. |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 401
- 403
- 429
- 503

Content type

application/json

{

- "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": { }

}

## [tag/IPv6/operation/quoteIpv6SpeedPlan](https://quanticdata.io/docs/python/#tag/IPv6/operation/quoteIpv6SpeedPlan) · Quote an IPv6 speed plan

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

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

##### Authorizations:

*bearerAuth*

##### Request Body schema: application/json · required

| speedMbps required | integer A speed of the grid (`GET /public/ipv6/plans`). 1000 answers `CONTACT_REQUIRED`. |
| --- | --- |
| days required | integer Enum: 1 · 7 · 30 The term. Traffic is not metered for the whole term. |
| paymentMethod | string Default: "BALANCE" Value: "BALANCE" |

### Responses

**200**

Quote.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object Server-side price of one cell. Nothing is reserved. |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "speedMbps": 200,
- "days": 7

}

### Response samples

- 200
- 400
- 401
- 403
- 409
- 429
- 503

Content type

application/json

{

- "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": { }

}

## [tag/IPv6/operation/listIpv6Orders](https://quanticdata.io/docs/python/#tag/IPv6/operation/listIpv6Orders) · List IPv6 speed orders

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

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

##### Authorizations:

*bearerAuth*

##### query Parameters

| limit | integer [ 1 .. 100 ] Default: 50 |
| --- | --- |
| offset | integer >= 0 Default: 0 |

### Responses

**200**

Orders.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 401
- 403
- 429
- 503

Content type

application/json

{

- "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": { }

}

## [tag/IPv6/operation/createIpv6Order](https://quanticdata.io/docs/python/#tag/IPv6/operation/createIpv6Order) · Buy an IPv6 speed plan

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

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.

##### Authorizations:

*bearerAuth*

##### header Parameters

| Idempotency-Key required | string · ^[a-zA-Z0-9-]{16,128}$ 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`. |
| --- | --- |

##### Request Body schema: application/json · required

| speedMbps required | integer A speed of the grid (`GET /public/ipv6/plans`). 1000 answers `CONTACT_REQUIRED`. |
| --- | --- |
| days required | integer Enum: 1 · 7 · 30 The term. Traffic is not metered for the whole term. |
| paymentMethod | string Default: "BALANCE" Value: "BALANCE" |
| maxTotal | number Refuse the purchase if the total is above this amount (USD). Nothing is charged then. |
| idempotencyKey | string · ^[a-zA-Z0-9-]{16,128}$ Alternative to the header. |

### Responses

**200**

Replayed: this Idempotency-Key was already paid. The order it created, no new charge.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

**201**

Delivered: the plan is active.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "speedMbps": 200,
- "days": 7,
- "maxTotal": 150

}

### Response samples

- 200
- 201
- 400
- 401
- 402
- 403
- 409
- 422
- 429
- 503

Content type

application/json

{

- "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": { }

}

## [tag/IPv6/operation/getIpv6Order](https://quanticdata.io/docs/python/#tag/IPv6/operation/getIpv6Order) · Get an IPv6 speed order

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

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

##### Authorizations:

*bearerAuth*

##### path Parameters

| orderId required | string `id` of the order (from `POST /public/ipv6/orders` or `GET /public/ipv6/orders`). The same id goes to `POST /public/proxies/generate`. |
| --- | --- |

### Responses

**200**

The order.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 400
- 401
- 403
- 404
- 429
- 503

Content type

application/json

{

- "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": { }

}

## [tag/Plans-and-orders](https://quanticdata.io/docs/python/#tag/Plans-and-orders) · Plans & orders

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.

## [tag/Plans-and-orders/operation/listPlans](https://quanticdata.io/docs/python/#tag/Plans-and-orders/operation/listPlans) · List the plans you can buy

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

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.

##### Authorizations:

*bearerAuth*

##### query Parameters

| planType | string Enum: "residentialbasic" · "residentialpremium" · "resiprivate" · "isp" · "isppremium" · "datacenter" · "datacentertraffic" · "ipv6" · "mobile" · "mobile_v2" Example: planType=residentialpremium Only plans of this type. An unknown value returns an empty list. |
| --- | --- |

### Responses

**200**

Plans on sale.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 401
- 429
- 500

Content type

application/json

{

- "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": { }

}

## [tag/Plans-and-orders/operation/purchasePlan](https://quanticdata.io/docs/python/#tag/Plans-and-orders/operation/purchasePlan) · Buy a plan from the balance

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

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.

##### Authorizations:

*bearerAuth*

##### Request Body schema: application/json · required

| planId required | string `id` of a plan from `GET /public/plans`. |
| --- | --- |
| coupon | string or null Coupon code (optional; empty string or null = none). |

### Responses

**200**

Paid and active. Credentials in `payload.proxy`.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "planId": "pln_3e7a"

}

### Response samples

- 200
- 400
- 401
- 403
- 404
- 409
- 422
- 429
- 500

Content type

application/json

{

- "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": { }

}

## [tag/Plans-and-orders/operation/listOrders](https://quanticdata.io/docs/python/#tag/Plans-and-orders/operation/listOrders) · List your orders

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

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.

##### Authorizations:

*bearerAuth*

##### query Parameters

| limit | integer <= 100 Default: 50 |
| --- | --- |
| offset | integer Default: 0 |
| type | string Enum: "PROXY" · "TOPUP" Only proxy plans (`PROXY`) or balance top-ups (`TOPUP`); omit for every order. |

### Responses

**200**

Orders.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 401
- 429
- 500

Content type

application/json

{

- "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": { }

}

## [tag/Plans-and-orders/operation/getBalance](https://quanticdata.io/docs/python/#tag/Plans-and-orders/operation/getBalance) · Get the wallet balance

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

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.

##### Authorizations:

*bearerAuth*

### Responses

**200**

Balance.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 401
- 429
- 500

Content type

application/json

{

- "type": "response",
- "message": "success",
- "payload": {
  - "balance": 42.5,
  - "balanceUSD": 42.5,
  - "totalSpent": 120,
  - "totalSpentUSD": 120

  },
- "pagination": { }

}

## [tag/Proxy-locations](https://quanticdata.io/docs/python/#tag/Proxy-locations) · Proxy locations

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:

| Plan type | Location values |
| --- | --- |
| `residentialpremium` | `GET /public/generator/residential-premium/targeting-options`: the whole tree (country, region, city, ISP) in one call |
| `mobile_v2` | `GET /public/generator/mobile/targeting-options`: the whole tree (country, region, city, carrier) in one call |
| `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) |
| `ipv6` | `GET /public/geo/countries?planType=ipv6` |
| `datacenter` (static gateways) | `GET /public/generator/datacenter/targeting-options`: the gateway hosts and ports |

Locations follow the network and change over time: read them when you build a request instead of keeping a copy for months. All free.

## [tag/Proxy-locations/operation/listGeoCountries](https://quanticdata.io/docs/python/#tag/Proxy-locations/operation/listGeoCountries) · List countries for a plan type

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

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.

##### Authorizations:

*bearerAuth*

##### query Parameters

| planType required | string Enum: "residentialbasic" · "residentialpremium" · "resiprivate" · "isp" · "isppremium" · "datacenter" · "datacentertraffic" · "ipv6" · "mobile" · "mobile_v2" Example: planType=residentialbasic Plan type whose countries you want. |
| --- | --- |

### Responses

**200**

Countries.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 400
- 401
- 429
- 500

Content type

application/json

{

- "type": "response",
- "message": "success",
- "payload": {
  - "countries": [
    - {
      - "code": "us",
      - "name": "United States"

      },
    - {
      - "code": "de",
      - "name": "Germany"

      }

    ],
  - "planType": "residentialbasic"

  },
- "pagination": { }

}

## [tag/Proxy-locations/operation/listGeoStates](https://quanticdata.io/docs/python/#tag/Proxy-locations/operation/listGeoStates) · List states or regions of a country

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

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.

##### Authorizations:

*bearerAuth*

##### query Parameters

| planType required | string Enum: "residentialbasic" · "residentialpremium" · "resiprivate" · "isp" · "isppremium" · "datacenter" · "datacentertraffic" · "ipv6" · "mobile" · "mobile_v2" Example: planType=residentialpremium Plan type. |
| --- | --- |
| country required | string Example: country=AL Country code, either case. |

### Responses

**200**

States.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

r = requests.get(
    'https://api.quanticdata.io/v1/public/geo/states?planType=residentialpremium&country=AL',
    headers={"Authorization": "Bearer qd_live_YOUR_API_KEY"},
    timeout=120,
)
data = r.json()
if data["type"] != "response":
    raise SystemExit(data["message"])
print(data["payload"])
```

### Response samples

- 200
- 400
- 401
- 404
- 429
- 500

Content type

application/json

{

- "type": "response",
- "message": "success",
- "payload": {
  - "states": [
    - {
      - "code": "durres",
      - "state_code": "durres",
      - "name": "Durres",
      - "state": "Durres"

      }

    ],
  - "country": "AL",
  - "planType": "residentialpremium"

  },
- "pagination": { }

}

## [tag/Proxy-locations/operation/listGeoCities](https://quanticdata.io/docs/python/#tag/Proxy-locations/operation/listGeoCities) · List cities of a country or state

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

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.

##### Authorizations:

*bearerAuth*

##### query Parameters

| planType required | string Enum: "residentialbasic" · "residentialpremium" · "resiprivate" · "isp" · "isppremium" · "datacenter" · "datacentertraffic" · "ipv6" · "mobile" · "mobile_v2" Example: planType=residentialpremium Plan type. |
| --- | --- |
| country required | string Example: country=AL Country code, either case. |
| state | string Example: state=durres State `code` from `GET /public/geo/states` (Residential Basic also accepts the name). |

### Responses

**200**

Cities.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

r = requests.get(
    'https://api.quanticdata.io/v1/public/geo/cities?planType=residentialpremium&country=AL&state=durres',
    headers={"Authorization": "Bearer qd_live_YOUR_API_KEY"},
    timeout=120,
)
data = r.json()
if data["type"] != "response":
    raise SystemExit(data["message"])
print(data["payload"])
```

### Response samples

- 200
- 400
- 401
- 404
- 429
- 500

Content type

application/json

{

- "type": "response",
- "message": "success",
- "payload": {
  - "cities": [
    - {
      - "code": "durres",
      - "name": "Durres"

      }

    ],
  - "country": "AL",
  - "state": "durres",
  - "planType": "residentialpremium"

  },
- "pagination": { }

}

## [tag/Proxy-locations/operation/listGeoAsns](https://quanticdata.io/docs/python/#tag/Proxy-locations/operation/listGeoAsns) · List ASNs for Residential Basic and Datacenter

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

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.

##### Authorizations:

*bearerAuth*

##### query Parameters

| planType required | string Enum: "residentialbasic" · "residentialpremium" · "resiprivate" · "isp" · "isppremium" · "datacenter" · "datacentertraffic" · "ipv6" · "mobile" · "mobile_v2" Example: planType=residentialbasic `residentialbasic` or `datacentertraffic`. |
| --- | --- |
| country | string Example: country=US Country code; omit for every country. |

### Responses

**200**

ASNs.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

r = requests.get(
    'https://api.quanticdata.io/v1/public/geo/asns?planType=residentialbasic&country=US',
    headers={"Authorization": "Bearer qd_live_YOUR_API_KEY"},
    timeout=120,
)
data = r.json()
if data["type"] != "response":
    raise SystemExit(data["message"])
print(data["payload"])
```

### Response samples

- 200
- 400
- 401
- 404
- 429
- 500

Content type

application/json

{

- "type": "response",
- "message": "success",
- "payload": {
  - "asns": [
    - {
      - "asn": "7922",
      - "name": "Comcast Cable Communications, LLC"

      }

    ],
  - "country": "US",
  - "planType": "residentialbasic"

  },
- "pagination": { }

}

## [tag/Proxy-locations/operation/getGeoLocations](https://quanticdata.io/docs/python/#tag/Proxy-locations/operation/getGeoLocations) · Residential Premium location tree (geo)

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

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.

##### Authorizations:

*bearerAuth*

##### query Parameters

| planType | string Value: "residentialpremium" Optional; only `residentialpremium` is accepted. |
| --- | --- |

### Responses

**200**

Location tree.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 400
- 401
- 429

Content type

application/json

{

- "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": { }

}

## [tag/Proxy-locations/operation/getResidentialPremiumTargetingOptions](https://quanticdata.io/docs/python/#tag/Proxy-locations/operation/getResidentialPremiumTargetingOptions) · Residential Premium targeting options

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

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.

##### Authorizations:

*bearerAuth*

### Responses

**200**

Location tree.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 401
- 429

Content type

application/json

{

- "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": { }

}

## [tag/Proxy-locations/operation/getMobileTargetingOptions](https://quanticdata.io/docs/python/#tag/Proxy-locations/operation/getMobileTargetingOptions) · Mobile targeting options

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

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.

##### Authorizations:

*bearerAuth*

### Responses

**200**

Location tree.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 401
- 429
- 502

Content type

application/json

{

- "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": { }

}

## [tag/Proxy-locations/operation/getDatacenterTargetingOptions](https://quanticdata.io/docs/python/#tag/Proxy-locations/operation/getDatacenterTargetingOptions) · Datacenter gateway locations

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

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.

##### Authorizations:

*bearerAuth*

### Responses

**200**

Gateways.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 401
- 429

Content type

application/json

{

- "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": { }

}

## [tag/Account](https://quanticdata.io/docs/python/#tag/Account) · Account

Usage, billing status and platform settings.

## [tag/Account/operation/getUsage](https://quanticdata.io/docs/python/#tag/Account/operation/getUsage) · Per-day usage and cost

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

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.

##### Authorizations:

*bearerAuth*

##### query Parameters

| days | integer [ 1 .. 90 ] Default: 30 |
| --- | --- |

### Responses

**200**

Usage report.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 401
- 429

Content type

application/json

{

- "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": { }

}

## [tag/Account/operation/getBilling](https://quanticdata.io/docs/python/#tag/Account/operation/getBilling) · Billing status and your price list

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

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.

##### Authorizations:

*bearerAuth*

### Responses

**200**

Billing status.

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 401
- 429

Content type

application/json

{

- "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": { }

}

## [tag/Account/operation/getMcpTrialConfig](https://quanticdata.io/docs/python/#tag/Account/operation/getMcpTrialConfig) · No-key MCP trial settings

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

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.

##### query Parameters

| brand | string Enum: "QP" · "QD" QP = QuantumProxies, QD = QuanticData. Defaults to the brand of the host you call. |
| --- | --- |

### Responses

**200**

Trial settings.

Response Headers

| Cache-Control | string `public, max-age=60`. |
| --- | --- |

##### Response Schema: application/json

| type required | string Value: "response" |
| --- | --- |
| message required | string |
| payload required | object |
| pagination | object Empty `{}` unless the endpoint pages (SERP mirrors its own pagination here). |

### Request samples

- Python (requests)

```python
import requests

r = requests.get(
    'https://api.quanticdata.io/v1/mcp/trial-config',
    timeout=120,
)
data = r.json()
if data["type"] != "response":
    raise SystemExit(data["message"])
print(data["payload"])
```

### Response samples

- 200

Content type

application/json

{

- "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"

    ]

  }

}

## [tag/Agents](https://quanticdata.io/docs/python/#tag/Agents) · Agents

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.

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

1. 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`.
2. 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`.
3. 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.
4. 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.
5. 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.

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

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

## [tag/Agents/operation/agentRegister](https://quanticdata.io/docs/python/#tag/Agents/operation/agentRegister) · Register an agent with a verified email (step 1 of 2)

**Price:** No charge.
**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`.
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/account.md)

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.

##### Request Body schema: application/json · required

| email required | string · \<email> The person's permanent email address: it receives the code, and later invoices and API alerts. |
| --- | --- |
| method | string Default: "verified_email" Value: "verified_email" The only method offered. `{"type": "service_auth", "login_hint": "…"}` is accepted as an alias of `{"method": "verified_email", "email": "…"}`. |
| agent | object Who is registering (optional). Shown in the verification email and in the key's name on the dashboard. |
| property name* additional property | any |

### Responses

**200**

Code sent. Ask the user for the 6 digits, then call `claim_uri`.

##### Response Schema: application/json

| status required | string Value: "pending" |
| --- | --- |
| registration_type required | string Value: "verified_email" |
| claim_uri required | string · \<uri> Where to exchange the code for the key (step 2). |
| expires_in required | integer Seconds the code stays valid (600). |
| interval | integer Always 0: there is nothing to poll, the person gives the code to the agent. |
| message | string What to do next, written for the agent. |

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "method": "verified_email",
- "email": "user@example.com",
- "agent": {
  - "name": "Research agent",
  - "url": "[https://example.com/agent](https://example.com/agent)"

  }

}

### Response samples

- 200
- 400
- 422
- 428
- 429
- 503

Content type

application/json

{

- "status": "pending",
- "registration_type": "verified_email",
- "claim_uri": "[https://app.quanticdata.io/api/v1/agent/auth/claim](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."

}

## [tag/Agents/operation/agentClaim](https://quanticdata.io/docs/python/#tag/Agents/operation/agentClaim) · Exchange the emailed code for an API key (step 2 of 2)

**Price:** No charge.
**Rate limit:** 30 claim attempts per IP an hour (429 `rate_limited` with `Retry-After`); 5 wrong codes per registration.
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/account.md)

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.

##### Request Body schema: application/json · required

| email required | string · \<email> The same address as in step 1. |
| --- | --- |
| code required | string · ^[0-9 -]{6,8}$ The 6 digits from the email. |
| property name* additional property | any |

### Responses

**200**

The API key, once.

##### Response Schema: application/json

| credential_type required | string Value: "api_key" |
| --- | --- |
| api_key required | string `qd_live_` + 64 hex characters. Shown once, never emailed: keep it in an environment variable. |
| key_prefix required | string The first characters of the key, as the dashboard lists it. |
| account_status required | string Enum: "created" · "existing" `created`: a new account was opened for that email. `existing`: the email already had an account and the key was added to it. |
| email required | string · \<email> |
| usage | object |
| docs | string · \<uri> |
| auth_md | string · \<uri> |
| note | string |

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "email": "user@example.com",
- "code": "482913"

}

### Response samples

- 200
- 400
- 410
- 429
- 503

Content type

application/json

{

- "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](https://api.quanticdata.io/v1)"

  },
- "docs": "[https://quanticdata.io/docs/](https://quanticdata.io/docs/)",
- "auth_md": "[https://quanticdata.io/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)."

}

## [tag/Agents/operation/ucpProfile](https://quanticdata.io/docs/python/#tag/Agents/operation/ucpProfile) · UCP discovery profile

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

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.

### Responses

**200**

The profile.

##### Response Schema: application/json

| ucp | object |
| --- | --- |
| keys | Array of objects |
| endpoints | object |
| property name* additional property | any |

### Request samples

- Python (requests)

```python
import requests

r = requests.get(
    'https://api.quanticdata.io/v1/agent/ucp',
    timeout=120,
)
data = r.json()
if data["type"] != "response":
    raise SystemExit(data["message"])
print(data["payload"])
```

### Response samples

- 200

Content type

application/json

{

- "ucp": {
  - "version": "2026-08-25",
  - "services": {
    - "dev.ucp.shopping": [
      - {
        - "version": "2026-08-25",
        - "spec": "[https://ucp.dev/2026-08-25/specification/overview/](https://ucp.dev/2026-08-25/specification/overview/)",
        - "schema": "[https://ucp.dev/2026-08-25/services/shopping/rest.openapi.json](https://ucp.dev/2026-08-25/services/shopping/rest.openapi.json)",
        - "transport": "rest",
        - "endpoint": "[https://api.quanticdata.io/v1/agent/ucp](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/](https://ucp.dev/2026-08-25/specification/shopping/checkout/)",
        - "schema": "[https://ucp.dev/2026-08-25/schemas/shopping/checkout.json](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](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](https://api.quanticdata.io/v1/agent/ucp/checkout-sessions)",
  - "openapi": "[https://api.quanticdata.io/openapi.json](https://api.quanticdata.io/openapi.json)",
  - "catalog": "[https://api.quanticdata.io/v1/public/plans](https://api.quanticdata.io/v1/public/plans)",
  - "docs": "[https://quanticdata.io/docs/](https://quanticdata.io/docs/)"

  }

}

## [tag/Agents/operation/ucpBalanceHandlerSchema](https://quanticdata.io/docs/python/#tag/Agents/operation/ucpBalanceHandlerSchema) · JSON Schema of the balance payment instrument

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

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.

### Responses

**200**

JSON Schema (draft 2020-12).

##### Response Schema: application/json

| property name* additional property | any |
| --- | --- |

### Request samples

- Python (requests)

```python
import requests

r = requests.get(
    'https://api.quanticdata.io/v1/agent/ucp/handlers/balance.json',
    timeout=120,
)
data = r.json()
if data["type"] != "response":
    raise SystemExit(data["message"])
print(data["payload"])
```

### Response samples

- 200

Content type

application/json

{

- "$schema": "[https://json-schema.org/draft/2020-12/schema](https://json-schema.org/draft/2020-12/schema)",
- "$id": "[https://api.quanticdata.io/v1/agent/ucp/handlers/balance.json](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"

  ]

}

## [tag/Agents/operation/ucpCreateCheckout](https://quanticdata.io/docs/python/#tag/Agents/operation/ucpCreateCheckout) · Create a checkout session for one plan

**Price:** No charge. Creating a session is free; the plan costs its `amount` from `GET /public/plans`, charged only when the session is completed.
**Rate limit:** Per API key, by tier (see Rate limits and tiers).
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/account.md)

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.

##### Authorizations:

*bearerAuth*

##### header Parameters

| Idempotency-Key | string · ^[A-Za-z0-9_.:-]{8,128}$ 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. |
| --- | --- |

##### Request Body schema: application/json · required

| line_items required | Array of objects = 1 items |
| --- | --- |
| buyer | object |
| payment_method | string Default: "BALANCE" Enum: "BALANCE" · "NOWPAYMENTS" · "PAYPAL" · "PAYPAL_CARD" What the quote assumes. `BALANCE` is the only one the agent can complete; the others are paid by a person at `continue_url`. |
| property name* additional property | any |

### Responses

**200**

Replay of an `Idempotency-Key` already used: the existing session.

##### Response Schema: application/json

| ucp required | object Protocol block: `version`, `status` (`success`), the `capabilities` and `payment_handlers` the session supports. |
| --- | --- |
| id required | string `chk_` + 24 hex characters. |
| status required | string Enum: "incomplete" · "requires_escalation" · "ready_for_complete" · "complete_in_progress" · "completed" · "canceled" `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 required | string Value: "USD" |
| expires_at required | string · \<date-time> |
| line_items required | Array of objects |
| totals required | Array of objects (UcpLineTotal) `subtotal`, `tax` (only when VAT applies) and `total`. |
| payment required | object |
| continue_url required | string · \<uri> Dashboard page where a person finishes this order (the plan is preselected and the session id is carried along). |
| messages required | Array of objects (UcpMessage) |
| buyer | object |
| links | Array of objects |
| order | object Present once `completed`. |
| created_at | string · \<date-time> |
| updated_at | string · \<date-time> |

**201**

Session created.

##### Response Schema: application/json

| ucp required | object Protocol block: `version`, `status` (`success`), the `capabilities` and `payment_handlers` the session supports. |
| --- | --- |
| id required | string `chk_` + 24 hex characters. |
| status required | string Enum: "incomplete" · "requires_escalation" · "ready_for_complete" · "complete_in_progress" · "completed" · "canceled" `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 required | string Value: "USD" |
| expires_at required | string · \<date-time> |
| line_items required | Array of objects |
| totals required | Array of objects (UcpLineTotal) `subtotal`, `tax` (only when VAT applies) and `total`. |
| payment required | object |
| continue_url required | string · \<uri> Dashboard page where a person finishes this order (the plan is preselected and the session id is carried along). |
| messages required | Array of objects (UcpMessage) |
| buyer | object |
| links | Array of objects |
| order | object Present once `completed`. |
| created_at | string · \<date-time> |
| updated_at | string · \<date-time> |

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "line_items": [
  - {
    - "item": {
      - "id": "pln_3e7a"

      },
    - "quantity": 1

    }

  ],
- "buyer": {
  - "email": "user@example.com"

  },
- "payment_method": "BALANCE"

}

### Response samples

- 200
- 201
- 400
- 401
- 404
- 503

Content type

application/json

{

- "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/](https://ucp.dev/2026-08-25/specification/shopping/checkout/)",
        - "schema": "[https://ucp.dev/2026-08-25/schemas/shopping/checkout.json](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)](https://quanticdata.io/docs/#section/Agent-checkout-%28UCP%29)",
        - "schema": "[https://api.quanticdata.io/v1/agent/ucp/handlers/balance.json](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](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](https://quanticdata.io/privacy)"

    },
  - {
    - "type": "terms_of_service",
    - "url": "[https://quanticdata.io/terms](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"

}

## [tag/Agents/operation/ucpGetCheckout](https://quanticdata.io/docs/python/#tag/Agents/operation/ucpGetCheckout) · Read a checkout session

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

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

##### Authorizations:

*bearerAuth*

##### path Parameters

| id required | string · ^chk_[0-9a-f]{24}$ Session id (`chk_` + 24 hex). A session of another account answers 404. |
| --- | --- |

### Responses

**200**

The session document.

##### Response Schema: application/json

| ucp required | object Protocol block: `version`, `status` (`success`), the `capabilities` and `payment_handlers` the session supports. |
| --- | --- |
| id required | string `chk_` + 24 hex characters. |
| status required | string Enum: "incomplete" · "requires_escalation" · "ready_for_complete" · "complete_in_progress" · "completed" · "canceled" `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 required | string Value: "USD" |
| expires_at required | string · \<date-time> |
| line_items required | Array of objects |
| totals required | Array of objects (UcpLineTotal) `subtotal`, `tax` (only when VAT applies) and `total`. |
| payment required | object |
| continue_url required | string · \<uri> Dashboard page where a person finishes this order (the plan is preselected and the session id is carried along). |
| messages required | Array of objects (UcpMessage) |
| buyer | object |
| links | Array of objects |
| order | object Present once `completed`. |
| created_at | string · \<date-time> |
| updated_at | string · \<date-time> |

### Request samples

- Python (requests)

```python
import requests

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

### Response samples

- 200
- 401
- 404

Content type

application/json

{

- "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/](https://ucp.dev/2026-08-25/specification/shopping/checkout/)",
        - "schema": "[https://ucp.dev/2026-08-25/schemas/shopping/checkout.json](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)](https://quanticdata.io/docs/#section/Agent-checkout-%28UCP%29)",
        - "schema": "[https://api.quanticdata.io/v1/agent/ucp/handlers/balance.json](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](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](https://quanticdata.io/privacy)"

    },
  - {
    - "type": "terms_of_service",
    - "url": "[https://quanticdata.io/terms](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"

}

## [tag/Agents/operation/ucpUpdateCheckout](https://quanticdata.io/docs/python/#tag/Agents/operation/ucpUpdateCheckout) · Change the declared payment method or the buyer email

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

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

##### Authorizations:

*bearerAuth*

##### path Parameters

| id required | string · ^chk_[0-9a-f]{24}$ Session id (`chk_` + 24 hex). A session of another account answers 404. |
| --- | --- |

##### Request Body schema: application/json · required

| line_items | Array of objects |
| --- | --- |
| buyer | object |
| payment_method | string Enum: "BALANCE" · "NOWPAYMENTS" · "PAYPAL" · "PAYPAL_CARD" |
| property name* additional property | any |

### Responses

**200**

The updated session.

##### Response Schema: application/json

| ucp required | object Protocol block: `version`, `status` (`success`), the `capabilities` and `payment_handlers` the session supports. |
| --- | --- |
| id required | string `chk_` + 24 hex characters. |
| status required | string Enum: "incomplete" · "requires_escalation" · "ready_for_complete" · "complete_in_progress" · "completed" · "canceled" `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 required | string Value: "USD" |
| expires_at required | string · \<date-time> |
| line_items required | Array of objects |
| totals required | Array of objects (UcpLineTotal) `subtotal`, `tax` (only when VAT applies) and `total`. |
| payment required | object |
| continue_url required | string · \<uri> Dashboard page where a person finishes this order (the plan is preselected and the session id is carried along). |
| messages required | Array of objects (UcpMessage) |
| buyer | object |
| links | Array of objects |
| order | object Present once `completed`. |
| created_at | string · \<date-time> |
| updated_at | string · \<date-time> |

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "payment_method": "PAYPAL_CARD",
- "buyer": {
  - "email": "user@example.com"

  }

}

### Response samples

- 200
- 400
- 401
- 404
- 409

Content type

application/json

{

- "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/](https://ucp.dev/2026-08-25/specification/shopping/checkout/)",
        - "schema": "[https://ucp.dev/2026-08-25/schemas/shopping/checkout.json](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)](https://quanticdata.io/docs/#section/Agent-checkout-%28UCP%29)",
        - "schema": "[https://api.quanticdata.io/v1/agent/ucp/handlers/balance.json](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](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](https://quanticdata.io/privacy)"

    },
  - {
    - "type": "terms_of_service",
    - "url": "[https://quanticdata.io/terms](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"

}

## [tag/Agents/operation/ucpCompleteCheckout](https://quanticdata.io/docs/python/#tag/Agents/operation/ucpCompleteCheckout) · Pay the session from the account balance

**Price:** No charge. Charges the plan's `amount` to the balance, 0% VAT. Nothing is charged on a failed outcome.
**Rate limit:** Per API key, by tier (see Rate limits and tiers).
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/account.md)

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

##### Authorizations:

*bearerAuth*

##### path Parameters

| id required | string · ^chk_[0-9a-f]{24}$ Session id (`chk_` + 24 hex). A session of another account answers 404. |
| --- | --- |

##### Request Body schema: application/json · optional

| payment | object |
| --- | --- |
| property name* additional property | any |

### Responses

**200**

The session after the attempt: `completed` with `order`, or back to `ready_for_complete` with an `error` message.

##### Response Schema: application/json

| ucp required | object Protocol block: `version`, `status` (`success`), the `capabilities` and `payment_handlers` the session supports. |
| --- | --- |
| id required | string `chk_` + 24 hex characters. |
| status required | string Enum: "incomplete" · "requires_escalation" · "ready_for_complete" · "complete_in_progress" · "completed" · "canceled" `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 required | string Value: "USD" |
| expires_at required | string · \<date-time> |
| line_items required | Array of objects |
| totals required | Array of objects (UcpLineTotal) `subtotal`, `tax` (only when VAT applies) and `total`. |
| payment required | object |
| continue_url required | string · \<uri> Dashboard page where a person finishes this order (the plan is preselected and the session id is carried along). |
| messages required | Array of objects (UcpMessage) |
| buyer | object |
| links | Array of objects |
| order | object Present once `completed`. |
| created_at | string · \<date-time> |
| updated_at | string · \<date-time> |

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "payment": {
  - "instruments": [
    - {
      - "handler_id": "balance",
      - "type": "account_balance",
      - "selected": true

      }

    ]

  }

}

### Response samples

- 200
- 401
- 404
- 409

Content type

application/json

{

- "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/](https://ucp.dev/2026-08-25/specification/shopping/checkout/)",
        - "schema": "[https://ucp.dev/2026-08-25/schemas/shopping/checkout.json](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)](https://quanticdata.io/docs/#section/Agent-checkout-%28UCP%29)",
        - "schema": "[https://api.quanticdata.io/v1/agent/ucp/handlers/balance.json](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](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](https://quanticdata.io/privacy)"

    },
  - {
    - "type": "terms_of_service",
    - "url": "[https://quanticdata.io/terms](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](https://app.quanticdata.io/proxies)"

  }

}

## [tag/Agents/operation/ucpCancelCheckout](https://quanticdata.io/docs/python/#tag/Agents/operation/ucpCancelCheckout) · Cancel a checkout session

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

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

##### Authorizations:

*bearerAuth*

##### path Parameters

| id required | string · ^chk_[0-9a-f]{24}$ Session id (`chk_` + 24 hex). A session of another account answers 404. |
| --- | --- |

### Responses

**200**

The session, now `canceled`.

##### Response Schema: application/json

| ucp required | object Protocol block: `version`, `status` (`success`), the `capabilities` and `payment_handlers` the session supports. |
| --- | --- |
| id required | string `chk_` + 24 hex characters. |
| status required | string Enum: "incomplete" · "requires_escalation" · "ready_for_complete" · "complete_in_progress" · "completed" · "canceled" `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 required | string Value: "USD" |
| expires_at required | string · \<date-time> |
| line_items required | Array of objects |
| totals required | Array of objects (UcpLineTotal) `subtotal`, `tax` (only when VAT applies) and `total`. |
| payment required | object |
| continue_url required | string · \<uri> Dashboard page where a person finishes this order (the plan is preselected and the session id is carried along). |
| messages required | Array of objects (UcpMessage) |
| buyer | object |
| links | Array of objects |
| order | object Present once `completed`. |
| created_at | string · \<date-time> |
| updated_at | string · \<date-time> |

### Request samples

- Python (requests)

```python
import requests

r = requests.post(
    'https://api.quanticdata.io/v1/agent/ucp/checkout-sessions/ID/cancel',
    headers={"Authorization": "Bearer qd_live_YOUR_API_KEY"},
    timeout=120,
)
data = r.json()
if data["type"] != "response":
    raise SystemExit(data["message"])
print(data["payload"])
```

### Response samples

- 200
- 401
- 404
- 409

Content type

application/json

{

- "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/](https://ucp.dev/2026-08-25/specification/shopping/checkout/)",
        - "schema": "[https://ucp.dev/2026-08-25/schemas/shopping/checkout.json](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)](https://quanticdata.io/docs/#section/Agent-checkout-%28UCP%29)",
        - "schema": "[https://api.quanticdata.io/v1/agent/ucp/handlers/balance.json](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](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](https://quanticdata.io/privacy)"

    },
  - {
    - "type": "terms_of_service",
    - "url": "[https://quanticdata.io/terms](https://quanticdata.io/terms)"

    }

  ],
- "messages": [ ],
- "created_at": "2026-10-26T12:00:00.000Z",
- "updated_at": "2026-10-26T12:00:00.000Z"

}

## [tag/Agents/operation/agentContact](https://quanticdata.io/docs/python/#tag/Agents/operation/agentContact) · Contact the team as an agent (higher credit limit, enterprise, dataset)

**Price:** No charge.
**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.
[Try it in the Playground](https://app.quanticdata.io/data-api/playground) · [Markdown for this group](https://quanticdata.io/docs/account.md)

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/`.

##### Authorizations:

*bearerAuth*

##### Request Body schema: application/json · required

| email required | string · \<email> <= 254 characters 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 required | string <= 100 characters Name of the person, or of the agent acting for them. |
| subject required | string <= 140 characters |
| message required | string <= 4000 characters 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 | string <= 200 characters |
| company_url | string · \<uri> <= 300 characters http(s) URL of the company. |
| expected_monthly_usd | number >= 0 Expected monthly spend, USD. Helps the team size the limit. |
| need | string Enum: "credit_limit" · "enterprise" · "dataset" · "other" `credit_limit` after a 402 with `escalation`; `enterprise` for volumes, SLAs or invoicing; `dataset` for a ready-made or custom dataset. |

### Responses

### Request samples

- Payload
- Python (requests)

Content type

application/json

{

- "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](https://acme.example)",
- "expected_monthly_usd": 3500,
- "need": "credit_limit"

}

### Response samples

- 202
- 400
- 401
- 429
- 500

Content type

application/json

{

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

}

---

Source: https://quanticdata.io/docs/python/ · Site index for AI: https://quanticdata.io/llms.txt
