# Proxies — QuanticData API

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

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

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

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

### List your proxy plans

`GET /public/proxies`

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

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer | no |  Default `50`. |
| `offset` | query | integer | no |  Default `0`. |
| `planType` | query | string: `residentialbasic`, `residentialpremium`, `resiprivate`, `isp`, `isppremium`, `datacenter`, `datacentertraffic`, `ipv6`, `mobile`, `mobile_v2` | no |  |
| `active` | query | string: `true`, `false` | no | Filter by expiry; omit for all. |

#### Examples

**curl**

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

**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"])
```

**Node (fetch)**

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

**PHP (curl)**

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

#### Responses

- `200` — Plans.
- `400` — Malformed input. `message` names the parameter and the rule it broke.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `500` — Our side: the scraper service is unavailable or the call timed out. Never billed.

Example `200` response:

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

Example `400`:

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

Example `401`:

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

Example `429`:

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

Example `500`:

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

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

### Generate proxy strings for a plan

`POST /public/proxies/generate`

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

#### Request body (required)

`Content-Type: application/json`

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

Example:

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

#### Examples

**curl**

```bash
curl -X POST 'https://api.quanticdata.io/v1/public/proxies/generate' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"orderId":"ord_8c21","protocol":"http","format":"user:pass@host:port","quantity":2,"country":"us","rotation":"sticky","sessionTime":10}'
```

**Python (requests)**

```python
import requests

r = requests.post(
    'https://api.quanticdata.io/v1/public/proxies/generate',
    headers={"Authorization": "Bearer qd_live_YOUR_API_KEY"},
    json={
        "orderId": "ord_8c21",
        "protocol": "http",
        "format": "user:pass@host:port",
        "quantity": 2,
        "country": "us",
        "rotation": "sticky",
        "sessionTime": 10
    },
    timeout=120,
)
data = r.json()
if data["type"] != "response":
    raise SystemExit(data["message"])
print(data["payload"])
```

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/public/proxies/generate", {
  method: "POST",
  headers: {
    Authorization: "Bearer qd_live_YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "orderId": "ord_8c21",
    "protocol": "http",
    "format": "user:pass@host:port",
    "quantity": 2,
    "country": "us",
    "rotation": "sticky",
    "sessionTime": 10
  })
});
const data = await res.json();
if (data.type !== "response") throw new Error(data.message);
console.log(data.payload);
```

**PHP (curl)**

```php
<?php
$ch = curl_init('https://api.quanticdata.io/v1/public/proxies/generate');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode([
    'orderId' => 'ord_8c21',
    'protocol' => 'http',
    'format' => 'user:pass@host:port',
    'quantity' => 2,
    'country' => 'us',
    'rotation' => 'sticky',
    'sessionTime' => 10
  ]),
]);
$raw = curl_exec($ch);
curl_close($ch);
$data = json_decode($raw, true);
if ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }
print_r($data['payload']);
```

#### Responses

- `200` — Proxy strings. Example: two sticky US lines of a Residential Premium plan.
- `202` — Premium ISP order still being provisioned.
- `400` — Missing orderId, expired plan, inactive sub-user, a plan type that cannot generate, `superSticky` / `udp` / `os` on a plan or protocol that does not support them, or an unknown `os` or Residential Basic `gateway` value.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `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.
- `404` — Order (or its proxy) not found on this account.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `500` — Our side: the scraper service is unavailable or the call timed out. Never billed.
- `502` — The plan's network did not answer; retry.

Example `200` response:

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

Example `400`:

```json
{
  "type": "error",
  "message": "Proxy has expired"
}
```

Example `401`:

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

Example `403`:

```json
{
  "type": "error",
  "message": "This plan is not available. Contact support."
}
```

Example `404`:

```json
{
  "type": "error",
  "message": "Order or proxy not found"
}
```

Example `429`:

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

Example `500`:

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

Example `502`:

```json
{
  "type": "error",
  "message": "Unable to generate proxies. Please try again."
}
```

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

### Geolocate an IP

`GET /public/proxies/ip-info`

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

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `ip` | query | string | yes |  |

#### Examples

**curl**

```bash
curl -X GET 'https://api.quanticdata.io/v1/public/proxies/ip-info?ip=203.0.113.7' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'
```

**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"])
```

**Node (fetch)**

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

**PHP (curl)**

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

#### Responses

- `200` — IP information.
- `400` — Missing `ip`, or the lookup source refused the address (private range, malformed).
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `500` — Our side: the scraper service is unavailable or the call timed out. Never billed.

Example `200` response:

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

Example `400`:

```json
{
  "type": "error",
  "message": "IP address is required. Use ?ip=x.x.x.x"
}
```

Example `401`:

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

Example `429`:

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

Example `500`:

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

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

### Where your IP is, as Cloudflare sees it

`GET /public/ip-echo`

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

#### Examples

**curl**

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

**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"])
```

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/public/ip-echo", {
  method: "GET"
});
const data = await res.json();
if (data.type !== "response") throw new Error(data.message);
console.log(data.payload);
```

**PHP (curl)**

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

#### Responses

- `200` — The caller's IP and Cloudflare's location for it.

Example `200` response:

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

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

### List whitelisted IPs of an order

`GET /public/proxies/whitelist-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)

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.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orderId` | query | string | yes |  |

#### Examples

**curl**

```bash
curl -X GET 'https://api.quanticdata.io/v1/public/proxies/whitelist-ip?orderId=ORDERID' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'
```

**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"])
```

**Node (fetch)**

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

**PHP (curl)**

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

#### Responses

- `200` — Whitelist.
- `400` — Malformed input. `message` names the parameter and the rule it broke.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `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.
- `404` — Order not found on this account.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `500` — Our side: the scraper service is unavailable or the call timed out. Never billed.

Example `200` response:

```json
{
  "type": "response",
  "message": "Success",
  "payload": {
    "orderId": "ord_8c21",
    "whitelist_ip": [
      "203.0.113.7"
    ]
  },
  "pagination": {}
}
```

Example `400`:

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

Example `401`:

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

Example `403`:

```json
{
  "type": "error",
  "message": "This plan is not available. Contact support."
}
```

Example `429`:

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

Example `500`:

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

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

### Whitelist an IP

`POST /public/proxies/whitelist-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.

#### Request body (required)

`Content-Type: application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `orderId` | string | yes |  |
| `ip` | string | yes | IPv4 address. |
| `action` | string: `add`, `update` | no | Mobile V2 only: `update` edits an existing entry's settings. Default `"add"`. |
| `ports_count` | integer | no | Mobile V2: ports to allocate. |
| `protocol` | string: `HTTP`, `SOCKS5` | no | Mobile V2. |
| `country` | string | no | Mobile V2 geo targeting for the allocated ports. |
| `region` | string | no | Mobile V2. |
| `city` | string | no | Mobile V2. |
| `isp` | string | no | Mobile V2. |
| `sticky` | boolean | no | Mobile V2: keep the same IP per port. |
| `ttl` | integer | no | Mobile V2: sticky session TTL in seconds. |

Example:

```json
{
  "orderId": "ord_8c21",
  "ip": "203.0.113.7"
}
```

#### Examples

**curl**

```bash
curl -X POST 'https://api.quanticdata.io/v1/public/proxies/whitelist-ip' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"orderId":"ord_8c21","ip":"203.0.113.7"}'
```

**Python (requests)**

```python
import requests

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

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/public/proxies/whitelist-ip", {
  method: "POST",
  headers: {
    Authorization: "Bearer qd_live_YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "orderId": "ord_8c21",
    "ip": "203.0.113.7"
  })
});
const data = await res.json();
if (data.type !== "response") throw new Error(data.message);
console.log(data.payload);
```

**PHP (curl)**

```php
<?php
$ch = curl_init('https://api.quanticdata.io/v1/public/proxies/whitelist-ip');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode([
    'orderId' => 'ord_8c21',
    'ip' => '203.0.113.7'
  ]),
]);
$raw = curl_exec($ch);
curl_close($ch);
$data = json_decode($raw, true);
if ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }
print_r($data['payload']);
```

#### Responses

- `200` — Whitelisted (or not applicable to this plan type).
- `400` — Missing fields, malformed IP, or the plan's network refused the entry.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `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.
- `404` — Order not found on this account (or its residential sub-user is missing).
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `500` — Our side: the scraper service is unavailable or the call timed out. Never billed.

Example `200` response:

```json
{
  "type": "response",
  "message": "IP whitelisted successfully",
  "payload": {
    "ip": "203.0.113.7",
    "whitelisted": true,
    "whitelist_ip": [
      "203.0.113.7"
    ]
  },
  "pagination": {}
}
```

Example `400`:

```json
{
  "type": "error",
  "message": "Invalid IP address format"
}
```

Example `401`:

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

Example `403`:

```json
{
  "type": "error",
  "message": "This plan is not available. Contact support."
}
```

Example `429`:

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

Example `500`:

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

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

### Remove a whitelisted IP

`DELETE /public/proxies/whitelist-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.

#### Request body (required)

`Content-Type: application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `orderId` | string | yes |  |
| `ip` | string | yes |  |
| `id` | string | no | Mobile V2 entry id (alternative handle). |

Example:

```json
{
  "orderId": "ord_8c21",
  "ip": "203.0.113.7"
}
```

#### Examples

**curl**

```bash
curl -X DELETE 'https://api.quanticdata.io/v1/public/proxies/whitelist-ip' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"orderId":"ord_8c21","ip":"203.0.113.7"}'
```

**Python (requests)**

```python
import requests

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

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/public/proxies/whitelist-ip", {
  method: "DELETE",
  headers: {
    Authorization: "Bearer qd_live_YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "orderId": "ord_8c21",
    "ip": "203.0.113.7"
  })
});
const data = await res.json();
if (data.type !== "response") throw new Error(data.message);
console.log(data.payload);
```

**PHP (curl)**

```php
<?php
$ch = curl_init('https://api.quanticdata.io/v1/public/proxies/whitelist-ip');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'DELETE',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode([
    'orderId' => 'ord_8c21',
    'ip' => '203.0.113.7'
  ]),
]);
$raw = curl_exec($ch);
curl_close($ch);
$data = json_decode($raw, true);
if ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }
print_r($data['payload']);
```

#### Responses

- `200` — Removed (or not applicable).
- `400` — Malformed input. `message` names the parameter and the rule it broke.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `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.
- `404` — Order not found on this account.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `500` — Our side: the scraper service is unavailable or the call timed out. Never billed.

Example `200` response:

```json
{
  "type": "response",
  "message": "IP removed from whitelist",
  "payload": {
    "ip": "203.0.113.7",
    "removed": true,
    "whitelist_ip": []
  },
  "pagination": {}
}
```

Example `400`:

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

Example `401`:

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

Example `403`:

```json
{
  "type": "error",
  "message": "This plan is not available. Contact support."
}
```

Example `429`:

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

Example `500`:

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

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

### Rotate a sticky session (new IP, same string)

`POST /public/proxies/{orderId}/rotate`

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

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orderId` | path | string | yes | Order id of the plan (`orderId` in `GET /public/proxies`). |

#### Request body (required)

`Content-Type: application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `proxy` | string | no | A sticky proxy string of this plan, exactly as `generate` returned it (any format). |
| `sessionId` | string | no | Instead of `proxy`: the session of your sticky string. |
| `protocol` | string: `http`, `socks5` | no | With `sessionId`: the protocol of your sticky string. Default `"http"`. |
| `port` | integer | no | With `sessionId`, instead of `protocol`: the port of your sticky string. |

Example:

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

#### Examples

**curl**

```bash
curl -X POST 'https://api.quanticdata.io/v1/public/proxies/ord_8c21/rotate' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"proxy":"user_8c21-country-us-session-a1b2c3-time-10:p4ssw0rd@residential-ww.quanticdata.io:9999"}'
```

**Python (requests)**

```python
import requests

r = requests.post(
    'https://api.quanticdata.io/v1/public/proxies/ord_8c21/rotate',
    headers={"Authorization": "Bearer qd_live_YOUR_API_KEY"},
    json={
        "proxy": "user_8c21-country-us-session-a1b2c3-time-10:p4ssw0rd@residential-ww.quanticdata.io:9999"
    },
    timeout=120,
)
data = r.json()
if data["type"] != "response":
    raise SystemExit(data["message"])
print(data["payload"])
```

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/public/proxies/ord_8c21/rotate", {
  method: "POST",
  headers: {
    Authorization: "Bearer qd_live_YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "proxy": "user_8c21-country-us-session-a1b2c3-time-10:p4ssw0rd@residential-ww.quanticdata.io:9999"
  })
});
const data = await res.json();
if (data.type !== "response") throw new Error(data.message);
console.log(data.payload);
```

**PHP (curl)**

```php
<?php
$ch = curl_init('https://api.quanticdata.io/v1/public/proxies/ord_8c21/rotate');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode([
    'proxy' => 'user_8c21-country-us-session-a1b2c3-time-10:p4ssw0rd@residential-ww.quanticdata.io:9999'
  ]),
]);
$raw = curl_exec($ch);
curl_close($ch);
$data = json_decode($raw, true);
if ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }
print_r($data['payload']);
```

#### Responses

- `200` — Session restarted.
- `400` — `VALIDATION_ERROR` (missing or malformed input), `SESSION_REQUIRED` (a rotating string: it already changes IP on every request) or `SESSION_NOT_IN_PLAN` (the string belongs to another plan).
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `403` — `KEY_REQUIRED`: call with your own API key (keyless and pay-per-call access cannot rotate). `PLAN_UNAVAILABLE`: the plan was disabled; contact support.
- `404` — `ORDER_NOT_FOUND`: no such order on this account.
- `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).
- `410` — `PLAN_EXPIRED`: the plan has expired.
- `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.
- `502` — `ROTATION_FAILED`: the session could not be restarted this time. The proxy string keeps working with its current IP. Retry after Retry-After.
- `503` — `SERVICE_UNAVAILABLE`: rotation is temporarily unavailable. Retry after Retry-After.

Example `200` response:

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

Example `400`:

```json
{
  "type": "error",
  "message": "This is a rotating proxy string: it already gets a new IP on every request. Rotation works on sticky strings (rotation: \"sticky\" in generate).",
  "payload": {
    "code": "SESSION_REQUIRED"
  }
}
```

Example `401`:

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

Example `403`:

```json
{
  "type": "error",
  "message": "Rotation needs your own API key. Create one in the dashboard under API keys.",
  "payload": {
    "code": "KEY_REQUIRED"
  }
}
```

Example `404`:

```json
{
  "type": "error",
  "message": "Order not found.",
  "payload": {
    "code": "ORDER_NOT_FOUND"
  }
}
```

Example `409`:

```json
{
  "type": "error",
  "message": "Rotation links are not available for this plan. For a new IP, request a new sticky proxy string with POST /v1/public/proxies/generate: each string has its own session.",
  "payload": {
    "code": "ROTATION_NOT_SUPPORTED",
    "planType": "residentialpremium",
    "reason": "new_string_only"
  }
}
```

Example `410`:

```json
{
  "type": "error",
  "message": "This plan has expired.",
  "payload": {
    "code": "PLAN_EXPIRED",
    "planType": "residentialbasic"
  }
}
```

Example `429`:

```json
{
  "type": "error",
  "message": "This session was rotated less than 10 seconds ago. Try again in 7 s.",
  "payload": {
    "code": "RATE_LIMITED",
    "scope": "session",
    "retryAfter": 7
  }
}
```

Example `502`:

```json
{
  "type": "error",
  "message": "The IP could not be rotated right now. Your proxy string still works. Try again in a few seconds.",
  "payload": {
    "code": "ROTATION_FAILED"
  }
}
```

Example `503`:

```json
{
  "type": "error",
  "message": "Rotation links are temporarily unavailable. Please try again later.",
  "payload": {
    "code": "SERVICE_UNAVAILABLE"
  }
}
```

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

### List rotation links of a plan

`GET /public/proxies/{orderId}/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)

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.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orderId` | path | string | yes | Order id of the plan (`orderId` in `GET /public/proxies`). |
| `includeRevoked` | query | boolean | no | Include revoked links. Default `false`. |

#### Examples

**curl**

```bash
curl -X GET 'https://api.quanticdata.io/v1/public/proxies/ord_8c21/rotation-links' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'
```

**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"])
```

**Node (fetch)**

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

**PHP (curl)**

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

#### Responses

- `200` — Rotation links.
- `400` — `VALIDATION_ERROR`: malformed orderId.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `403` — `KEY_REQUIRED`: call with your own API key (keyless and pay-per-call access cannot rotate). `PLAN_UNAVAILABLE`: the plan was disabled; contact support.
- `404` — `ORDER_NOT_FOUND`: no such order on this account.
- `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).
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `503` — `SERVICE_UNAVAILABLE`: rotation is temporarily unavailable. Retry after Retry-After.

Example `200` response:

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

Example `400`:

```json
{
  "type": "error",
  "message": "A valid orderId is required.",
  "payload": {
    "code": "VALIDATION_ERROR"
  }
}
```

Example `401`:

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

Example `403`:

```json
{
  "type": "error",
  "message": "Rotation needs your own API key. Create one in the dashboard under API keys.",
  "payload": {
    "code": "KEY_REQUIRED"
  }
}
```

Example `404`:

```json
{
  "type": "error",
  "message": "Order not found.",
  "payload": {
    "code": "ORDER_NOT_FOUND"
  }
}
```

Example `409`:

```json
{
  "type": "error",
  "message": "Rotation links are not available for this plan. For a new IP, request a new sticky proxy string with POST /v1/public/proxies/generate: each string has its own session.",
  "payload": {
    "code": "ROTATION_NOT_SUPPORTED",
    "planType": "residentialpremium",
    "reason": "new_string_only"
  }
}
```

Example `429`:

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

Example `503`:

```json
{
  "type": "error",
  "message": "Rotation links are temporarily unavailable. Please try again later.",
  "payload": {
    "code": "SERVICE_UNAVAILABLE"
  }
}
```

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

### Create rotation links

`POST /public/proxies/{orderId}/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.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orderId` | path | string | yes | Order id of the plan (`orderId` in `GET /public/proxies`). |

#### Request body (required)

`Content-Type: application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `proxy` | string | no | A sticky proxy string of this plan, exactly as `generate` returned it (any format). |
| `sessionId` | string | no | Instead of `proxy`: the session of your sticky string. |
| `protocol` | string: `http`, `socks5` | no | With `sessionId`: the protocol of your sticky string. Default `"http"`. |
| `port` | integer | no | With `sessionId`, instead of `protocol`: the port of your sticky string. |
| `proxies` | array of string | no | Several sticky proxy strings of this plan: one link per string. |
| `label` | string | no | Optional name stored on every link created by this call: letters, digits, spaces and . _ : # / - |

Example:

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

#### Examples

**curl**

```bash
curl -X POST 'https://api.quanticdata.io/v1/public/proxies/ord_8c21/rotation-links' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"proxy":"user_8c21-country-us-session-a1b2c3-time-10:p4ssw0rd@residential-ww.quanticdata.io:9999","label":"Profile 12"}'
```

**Python (requests)**

```python
import requests

r = requests.post(
    'https://api.quanticdata.io/v1/public/proxies/ord_8c21/rotation-links',
    headers={"Authorization": "Bearer qd_live_YOUR_API_KEY"},
    json={
        "proxy": "user_8c21-country-us-session-a1b2c3-time-10:p4ssw0rd@residential-ww.quanticdata.io:9999",
        "label": "Profile 12"
    },
    timeout=120,
)
data = r.json()
if data["type"] != "response":
    raise SystemExit(data["message"])
print(data["payload"])
```

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/public/proxies/ord_8c21/rotation-links", {
  method: "POST",
  headers: {
    Authorization: "Bearer qd_live_YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "proxy": "user_8c21-country-us-session-a1b2c3-time-10:p4ssw0rd@residential-ww.quanticdata.io:9999",
    "label": "Profile 12"
  })
});
const data = await res.json();
if (data.type !== "response") throw new Error(data.message);
console.log(data.payload);
```

**PHP (curl)**

```php
<?php
$ch = curl_init('https://api.quanticdata.io/v1/public/proxies/ord_8c21/rotation-links');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode([
    'proxy' => 'user_8c21-country-us-session-a1b2c3-time-10:p4ssw0rd@residential-ww.quanticdata.io:9999',
    'label' => 'Profile 12'
  ]),
]);
$raw = curl_exec($ch);
curl_close($ch);
$data = json_decode($raw, true);
if ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }
print_r($data['payload']);
```

#### Responses

- `201` — Links created. Each `url` is shown once.
- `400` — `VALIDATION_ERROR` (missing or malformed input), `SESSION_REQUIRED` (a rotating string: it already changes IP on every request) or `SESSION_NOT_IN_PLAN` (the string belongs to another plan).
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `403` — `KEY_REQUIRED`: call with your own API key (keyless and pay-per-call access cannot rotate). `PLAN_UNAVAILABLE`: the plan was disabled; contact support.
- `404` — `ORDER_NOT_FOUND`: no such order on this account.
- `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).
- `410` — `PLAN_EXPIRED`: the plan has expired.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `503` — `SERVICE_UNAVAILABLE`: rotation is temporarily unavailable. Retry after Retry-After.

Example `201` response:

```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",
        "token": "rl_6f1c0e2b9a7d4c3e8f5a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e"
      }
    ]
  },
  "pagination": {}
}
```

Example `400`:

```json
{
  "type": "error",
  "message": "This is a rotating proxy string: it already gets a new IP on every request. Rotation works on sticky strings (rotation: \"sticky\" in generate).",
  "payload": {
    "code": "SESSION_REQUIRED"
  }
}
```

Example `401`:

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

Example `403`:

```json
{
  "type": "error",
  "message": "Rotation needs your own API key. Create one in the dashboard under API keys.",
  "payload": {
    "code": "KEY_REQUIRED"
  }
}
```

Example `404`:

```json
{
  "type": "error",
  "message": "Order not found.",
  "payload": {
    "code": "ORDER_NOT_FOUND"
  }
}
```

Example `409`:

```json
{
  "type": "error",
  "message": "Rotation links are not available for this plan. For a new IP, request a new sticky proxy string with POST /v1/public/proxies/generate: each string has its own session.",
  "payload": {
    "code": "ROTATION_NOT_SUPPORTED",
    "planType": "residentialpremium",
    "reason": "new_string_only"
  }
}
```

Example `410`:

```json
{
  "type": "error",
  "message": "This plan has expired.",
  "payload": {
    "code": "PLAN_EXPIRED",
    "planType": "residentialbasic"
  }
}
```

Example `429`:

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

Example `503`:

```json
{
  "type": "error",
  "message": "Rotation links are temporarily unavailable. Please try again later.",
  "payload": {
    "code": "SERVICE_UNAVAILABLE"
  }
}
```

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

### Revoke a rotation link

`DELETE /public/proxies/{orderId}/rotation-links/{linkId}`

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

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orderId` | path | string | yes | Order id of the plan (`orderId` in `GET /public/proxies`). |
| `linkId` | path | string | yes | Link id (`id` in the link list). |

#### Examples

**curl**

```bash
curl -X DELETE 'https://api.quanticdata.io/v1/public/proxies/ord_8c21/rotation-links/rlk_3f9a1c7e5b2d4a6c8e0f1a2b' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'
```

**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"])
```

**Node (fetch)**

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

**PHP (curl)**

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

#### Responses

- `200` — Link revoked.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `403` — `KEY_REQUIRED`: call with your own API key (keyless and pay-per-call access cannot rotate). `PLAN_UNAVAILABLE`: the plan was disabled; contact support.
- `404` — `LINK_NOT_FOUND`: no such link on this plan, or `ORDER_NOT_FOUND`.
- `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).
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `503` — `SERVICE_UNAVAILABLE`: rotation is temporarily unavailable. Retry after Retry-After.

Example `200` response:

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

Example `401`:

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

Example `403`:

```json
{
  "type": "error",
  "message": "Rotation needs your own API key. Create one in the dashboard under API keys.",
  "payload": {
    "code": "KEY_REQUIRED"
  }
}
```

Example `404`:

```json
{
  "type": "error",
  "message": "Rotation link not found on this plan.",
  "payload": {
    "code": "LINK_NOT_FOUND"
  }
}
```

Example `409`:

```json
{
  "type": "error",
  "message": "Rotation links are not available for this plan. For a new IP, request a new sticky proxy string with POST /v1/public/proxies/generate: each string has its own session.",
  "payload": {
    "code": "ROTATION_NOT_SUPPORTED",
    "planType": "residentialpremium",
    "reason": "new_string_only"
  }
}
```

Example `429`:

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

Example `503`:

```json
{
  "type": "error",
  "message": "Rotation links are temporarily unavailable. Please try again later.",
  "payload": {
    "code": "SERVICE_UNAVAILABLE"
  }
}
```

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

### Call a rotation link

`GET /public/rotate/{token}`

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

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `token` | path | string | yes | The token at the end of the link URL. |

#### Examples

**curl**

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

**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"])
```

**Node (fetch)**

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

**PHP (curl)**

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

#### Responses

- `200` — Session restarted.
- `403` — `ACCOUNT_DISABLED`: the account that owns the link is disabled. `PLAN_UNAVAILABLE`: the plan was disabled.
- `404` — `LINK_NOT_FOUND`: unknown link, or `ORDER_NOT_FOUND` when the plan is no longer on the account.
- `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).
- `410` — `LINK_REVOKED`: the link was revoked; create a new one. `PLAN_EXPIRED`: the plan has expired.
- `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.
- `502` — `ROTATION_FAILED`: the session could not be restarted this time. The proxy string keeps working with its current IP. Retry after Retry-After.
- `503` — `SERVICE_UNAVAILABLE`: rotation is temporarily unavailable. Retry after Retry-After.

Example `200` response:

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

Example `403`:

```json
{
  "type": "error",
  "message": "This account is disabled. Contact support.",
  "payload": {
    "code": "ACCOUNT_DISABLED"
  }
}
```

Example `404`:

```json
{
  "type": "error",
  "message": "Rotation link not found. Check the URL, or create a new link.",
  "payload": {
    "code": "LINK_NOT_FOUND"
  }
}
```

Example `409`:

```json
{
  "type": "error",
  "message": "Rotation links are not available for this plan. For a new IP, request a new sticky proxy string with POST /v1/public/proxies/generate: each string has its own session.",
  "payload": {
    "code": "ROTATION_NOT_SUPPORTED",
    "planType": "residentialpremium",
    "reason": "new_string_only"
  }
}
```

Example `410`:

```json
{
  "type": "error",
  "message": "This rotation link was revoked. Create a new one for this session.",
  "payload": {
    "code": "LINK_REVOKED"
  }
}
```

Example `429`:

```json
{
  "type": "error",
  "message": "This session was rotated less than 10 seconds ago. Try again in 7 s.",
  "payload": {
    "code": "RATE_LIMITED",
    "scope": "session",
    "retryAfter": 7
  }
}
```

Example `502`:

```json
{
  "type": "error",
  "message": "The IP could not be rotated right now. Your proxy string still works. Try again in a few seconds.",
  "payload": {
    "code": "ROTATION_FAILED"
  }
}
```

Example `503`:

```json
{
  "type": "error",
  "message": "Rotation links are temporarily unavailable. Please try again later.",
  "payload": {
    "code": "SERVICE_UNAVAILABLE"
  }
}
```

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

### Call a rotation link (POST)

`POST /public/rotate/{token}`

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

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `token` | path | string | yes | The token at the end of the link URL. |

#### Examples

**curl**

```bash
curl -X POST 'https://api.quanticdata.io/v1/public/rotate/rl_6f1c0e2b9a7d4c3e8f5a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e'
```

**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"])
```

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/public/rotate/rl_6f1c0e2b9a7d4c3e8f5a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e", {
  method: "POST"
});
const data = await res.json();
if (data.type !== "response") throw new Error(data.message);
console.log(data.payload);
```

**PHP (curl)**

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

#### Responses

- `200` — Session restarted.
- `403` — `ACCOUNT_DISABLED`: the account that owns the link is disabled. `PLAN_UNAVAILABLE`: the plan was disabled.
- `404` — `LINK_NOT_FOUND`: unknown link, or `ORDER_NOT_FOUND` when the plan is no longer on the account.
- `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).
- `410` — `LINK_REVOKED`: the link was revoked; create a new one. `PLAN_EXPIRED`: the plan has expired.
- `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.
- `502` — `ROTATION_FAILED`: the session could not be restarted this time. The proxy string keeps working with its current IP. Retry after Retry-After.
- `503` — `SERVICE_UNAVAILABLE`: rotation is temporarily unavailable. Retry after Retry-After.

Example `200` response:

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

Example `403`:

```json
{
  "type": "error",
  "message": "This account is disabled. Contact support.",
  "payload": {
    "code": "ACCOUNT_DISABLED"
  }
}
```

Example `404`:

```json
{
  "type": "error",
  "message": "Rotation link not found. Check the URL, or create a new link.",
  "payload": {
    "code": "LINK_NOT_FOUND"
  }
}
```

Example `409`:

```json
{
  "type": "error",
  "message": "Rotation links are not available for this plan. For a new IP, request a new sticky proxy string with POST /v1/public/proxies/generate: each string has its own session.",
  "payload": {
    "code": "ROTATION_NOT_SUPPORTED",
    "planType": "residentialpremium",
    "reason": "new_string_only"
  }
}
```

Example `410`:

```json
{
  "type": "error",
  "message": "This rotation link was revoked. Create a new one for this session.",
  "payload": {
    "code": "LINK_REVOKED"
  }
}
```

Example `429`:

```json
{
  "type": "error",
  "message": "This session was rotated less than 10 seconds ago. Try again in 7 s.",
  "payload": {
    "code": "RATE_LIMITED",
    "scope": "session",
    "retryAfter": 7
  }
}
```

Example `502`:

```json
{
  "type": "error",
  "message": "The IP could not be rotated right now. Your proxy string still works. Try again in a few seconds.",
  "payload": {
    "code": "ROTATION_FAILED"
  }
}
```

Example `503`:

```json
{
  "type": "error",
  "message": "Rotation links are temporarily unavailable. Please try again later.",
  "payload": {
    "code": "SERVICE_UNAVAILABLE"
  }
}
```

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

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

### List Premium ISP pools

`GET /public/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.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `country` | query | string | no | ISO 3166-1 alpha-2 filter, e.g. `US`. |

#### Examples

**curl**

```bash
curl -X GET 'https://api.quanticdata.io/v1/public/premium-isp/pools' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'
```

**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"])
```

**Node (fetch)**

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

**PHP (curl)**

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

#### Responses

- `200` — Pools.
- `400` — Malformed input. `message` names the parameter and the rule it broke.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `403` — Your own API key is required (keyless and pay-per-call access cannot buy), keys created by a connected app cannot spend the balance, or the plan was disabled by support.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `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.

Example `200` response:

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

Example `400`:

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

Example `401`:

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

Example `403`:

```json
{
  "type": "error",
  "message": "Premium ISP needs your own API key. Create one in the dashboard under API keys.",
  "payload": {
    "code": "KEY_REQUIRED"
  }
}
```

Example `429`:

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

Example `503`:

```json
{
  "type": "error",
  "message": "Premium ISP is not available through the API yet. Use the dashboard to buy Premium ISP plans.",
  "payload": {
    "code": "PRODUCT_DISABLED"
  }
}
```

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

### List Premium ISP cities with stock

`GET /public/premium-isp/cities`

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

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `type` | query | string: `city`, `fraud-score-0` | no |  Default `"city"`. |
| `udp` | query | string: `0`, `1` | no | `1` for UDP-capable IPs. Default `"0"`. |
| `country` | query | string | no | ISO 3166-1 alpha-2 filter. |

#### Examples

**curl**

```bash
curl -X GET 'https://api.quanticdata.io/v1/public/premium-isp/cities' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'
```

**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"])
```

**Node (fetch)**

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

**PHP (curl)**

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

#### Responses

- `200` — Catalog.
- `400` — Malformed input. `message` names the parameter and the rule it broke.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `403` — Your own API key is required (keyless and pay-per-call access cannot buy), keys created by a connected app cannot spend the balance, or the plan was disabled by support.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `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.

Example `200` response:

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

Example `400`:

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

Example `401`:

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

Example `403`:

```json
{
  "type": "error",
  "message": "Premium ISP needs your own API key. Create one in the dashboard under API keys.",
  "payload": {
    "code": "KEY_REQUIRED"
  }
}
```

Example `429`:

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

Example `503`:

```json
{
  "type": "error",
  "message": "Premium ISP is not available through the API yet. Use the dashboard to buy Premium ISP plans.",
  "payload": {
    "code": "PRODUCT_DISABLED"
  }
}
```

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

### List the carriers (ASN) of a city

`GET /public/premium-isp/cities/carriers`

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

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `location` | query | string | yes | `location` from `GET /public/premium-isp/cities`. |
| `type` | query | string: `city`, `fraud-score-0` | no |  Default `"city"`. |
| `udp` | query | string: `0`, `1` | no |  Default `"0"`. |

#### Examples

**curl**

```bash
curl -X GET 'https://api.quanticdata.io/v1/public/premium-isp/cities/carriers?location=LOCATION' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'
```

**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"])
```

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/public/premium-isp/cities/carriers?location=LOCATION", {
  method: "GET",
  headers: {
    Authorization: "Bearer qd_live_YOUR_API_KEY"
  }
});
const data = await res.json();
if (data.type !== "response") throw new Error(data.message);
console.log(data.payload);
```

**PHP (curl)**

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

#### Responses

- `200` — Carriers.
- `400` — Malformed input. `message` names the parameter and the rule it broke.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `403` — Your own API key is required (keyless and pay-per-call access cannot buy), keys created by a connected app cannot spend the balance, or the plan was disabled by support.
- `409` — The selection cannot be sold right now, or the request conflicts with an earlier one. Nothing was charged unless the code says so.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `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.

Example `200` response:

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

Example `400`:

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

Example `401`:

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

Example `403`:

```json
{
  "type": "error",
  "message": "Premium ISP needs your own API key. Create one in the dashboard under API keys.",
  "payload": {
    "code": "KEY_REQUIRED"
  }
}
```

Example `409`:

```json
{
  "type": "error",
  "message": "This city is not available right now.",
  "payload": {
    "code": "CITY_UNAVAILABLE"
  }
}
```

Example `429`:

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

Example `503`:

```json
{
  "type": "error",
  "message": "Premium ISP is not available through the API yet. Use the dashboard to buy Premium ISP plans.",
  "payload": {
    "code": "PRODUCT_DISABLED"
  }
}
```

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

### Quote a Premium ISP selection

`POST /public/premium-isp/quote`

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

#### Request body (required)

`Content-Type: application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `product` | string: `pool`, `city` | yes |  |
| `poolId` | string | no | Pool id from `GET /public/premium-isp/pools` (pool only). A `-subnet` pool buys a whole /24. |
| `type` | string: `city`, `fraud-score-0` | no | City plans only. `fraud-score-0`: every IP is checked for a fraud score of 0 before delivery. Default `"city"`. |
| `length` | string: `1_day`, `7_days`, `1_month`, `2_months`, `3_months` | no | City plans only; the lengths on sale are listed by the catalog. |
| `location` | string | no | 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 | no | 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). Default `null`. |
| `udp` | boolean | no | City plans only: UDP-capable IPs. Default `false`. |
| `ispNameCheck` | boolean | no | 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.) Default `false`. |
| `siteCheck` | object | no | 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. |
| `siteCheck.url` | string | yes | A full http or https address with a public host name, no credentials. |
| `siteCheck.expectedStatus` | integer | no |  Default `200`. |
| `replacements` | integer | no | 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. Default `0`. |
| `quantity` | integer | yes | Number of IPs, within the length's or pool's minQuantity/maxQuantity: exactly 256 for a subnet pool. |
| `paymentMethod` | string: `BALANCE` | no |  Default `"BALANCE"`. |

Example:

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

#### Examples

**curl**

```bash
curl -X POST 'https://api.quanticdata.io/v1/public/premium-isp/quote' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'
```

**Python (requests)**

```python
import requests

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

**Node (fetch)**

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

**PHP (curl)**

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

#### Responses

- `200` — Quote.
- `400` — Malformed input. `message` names the parameter and the rule it broke.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `403` — Your own API key is required (keyless and pay-per-call access cannot buy), keys created by a connected app cannot spend the balance, or the plan was disabled by support.
- `409` — The selection cannot be sold right now, or the request conflicts with an earlier one. Nothing was charged unless the code says so.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `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.

Example `200` response:

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

Example `400`:

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

Example `401`:

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

Example `403`:

```json
{
  "type": "error",
  "message": "Premium ISP needs your own API key. Create one in the dashboard under API keys.",
  "payload": {
    "code": "KEY_REQUIRED"
  }
}
```

Example `409`:

```json
{
  "type": "error",
  "message": "This city is not available right now.",
  "payload": {
    "code": "CITY_UNAVAILABLE"
  }
}
```

Example `429`:

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

Example `503`:

```json
{
  "type": "error",
  "message": "Premium ISP is not available through the API yet. Use the dashboard to buy Premium ISP plans.",
  "payload": {
    "code": "PRODUCT_DISABLED"
  }
}
```

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

### List Premium ISP orders

`GET /public/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.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer | no |  Default `50`. |
| `offset` | query | integer | no |  Default `0`. |

#### Examples

**curl**

```bash
curl -X GET 'https://api.quanticdata.io/v1/public/premium-isp/orders' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'
```

**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"])
```

**Node (fetch)**

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

**PHP (curl)**

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

#### Responses

- `200` — Orders.
- `400` — Malformed input. `message` names the parameter and the rule it broke.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `403` — Your own API key is required (keyless and pay-per-call access cannot buy), keys created by a connected app cannot spend the balance, or the plan was disabled by support.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `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.

Example `200` response:

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

Example `400`:

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

Example `401`:

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

Example `403`:

```json
{
  "type": "error",
  "message": "Premium ISP needs your own API key. Create one in the dashboard under API keys.",
  "payload": {
    "code": "KEY_REQUIRED"
  }
}
```

Example `429`:

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

Example `503`:

```json
{
  "type": "error",
  "message": "Premium ISP is not available through the API yet. Use the dashboard to buy Premium ISP plans.",
  "payload": {
    "code": "PRODUCT_DISABLED"
  }
}
```

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

### Buy Premium ISP IPs from the balance

`POST /public/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)

Buys a pool or city selection and charges the wallet balance (VAT 0%). The `Idempotency-Key` header is required: a retry with the same key never charges twice and answers with the same order. `maxTotal` (optional) refuses the purchase if the price went above it. The balance is checked before anything is created. Answers: 201 delivered; 202 paid and being prepared (poll `GET /public/premium-isp/orders/{orderId}`, see `Location`); 200 `replayed: true` for a key already used; 422 not delivered and refunded to the balance. Coupons are not accepted through the API. Whole /24 subnets and the 24-hour replacement of pool IPs are arranged with support. 20 purchases an hour per account. A city selection may carry `siteCheck` (a URL and the status it must answer): only IPs that pass it are delivered; if none does, the order fails and the balance is refunded by itself.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | yes | 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 (required)

`Content-Type: application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `product` | string: `pool`, `city` | yes |  |
| `poolId` | string | no | Pool id from `GET /public/premium-isp/pools` (pool only). A `-subnet` pool buys a whole /24. |
| `type` | string: `city`, `fraud-score-0` | no | City plans only. `fraud-score-0`: every IP is checked for a fraud score of 0 before delivery. Default `"city"`. |
| `length` | string: `1_day`, `7_days`, `1_month`, `2_months`, `3_months` | no | City plans only; the lengths on sale are listed by the catalog. |
| `location` | string | no | 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 | no | 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). Default `null`. |
| `udp` | boolean | no | City plans only: UDP-capable IPs. Default `false`. |
| `ispNameCheck` | boolean | no | 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.) Default `false`. |
| `siteCheck` | object | no | 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. |
| `siteCheck.url` | string | yes | A full http or https address with a public host name, no credentials. |
| `siteCheck.expectedStatus` | integer | no |  Default `200`. |
| `replacements` | integer | no | 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. Default `0`. |
| `quantity` | integer | yes | Number of IPs, within the length's or pool's minQuantity/maxQuantity: exactly 256 for a subnet pool. |
| `paymentMethod` | string: `BALANCE` | no |  Default `"BALANCE"`. |
| `maxTotal` | number | no | Highest total you accept, in USD. Above it: 409 `PRICE_CHANGED`, nothing charged. |

Example:

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

#### Examples

**curl**

```bash
curl -X POST 'https://api.quanticdata.io/v1/public/premium-isp/orders' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'
```

**Python (requests)**

```python
import requests

r = requests.post(
    '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"])
```

**Node (fetch)**

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

**PHP (curl)**

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

#### Responses

- `200` — Replayed: this Idempotency-Key was already used for this selection. Nothing new was charged.
- `201` — Delivered.
- `202` — Paid, the IPs are being prepared. Poll the order; do not buy again. If a city order cannot be filled, it is closed and the amount paid goes back to your balance: the order then reads `refunded`.
- `400` — Malformed input. `message` names the parameter and the rule it broke.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `402` — The wallet balance cannot cover the total. Nothing was created or charged: top up in the dashboard and send the request again.
- `403` — Your own API key is required (keyless and pay-per-call access cannot buy), keys created by a connected app cannot spend the balance, or the plan was disabled by support.
- `409` — The selection cannot be sold right now, or the request conflicts with an earlier one. Nothing was charged unless the code says so.
- `422` — The IPs could not be delivered and the amount is back on your balance: you have not been charged. Send the purchase again with a new Idempotency-Key.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `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.

Example `200` response:

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

Example `400`:

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

Example `401`:

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

Example `402`:

```json
{
  "type": "error",
  "message": "Your balance is too low for this purchase. Top up in the dashboard and try again.",
  "payload": {
    "code": "INSUFFICIENT_BALANCE"
  }
}
```

Example `403`:

```json
{
  "type": "error",
  "message": "Premium ISP needs your own API key. Create one in the dashboard under API keys.",
  "payload": {
    "code": "KEY_REQUIRED"
  }
}
```

Example `409`:

```json
{
  "type": "error",
  "message": "This city is not available right now.",
  "payload": {
    "code": "CITY_UNAVAILABLE"
  }
}
```

Example `422`:

```json
{
  "type": "error",
  "message": "The IPs could not be delivered. You have not been charged: the amount is back on your balance.",
  "payload": {
    "code": "NOT_DELIVERED_REFUNDED",
    "refunded": true,
    "newCheckoutRequired": true,
    "orderId": "ord_5f2a",
    "invoiceId": "inv_77c1"
  }
}
```

Example `429`:

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

Example `503`:

```json
{
  "type": "error",
  "message": "Premium ISP is not available through the API yet. Use the dashboard to buy Premium ISP plans.",
  "payload": {
    "code": "PRODUCT_DISABLED"
  }
}
```

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

### Get a Premium ISP order and its proxy lines

`GET /public/premium-isp/orders/{orderId}`

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

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orderId` | path | string | yes | `id` of the order (from `POST /public/premium-isp/orders` or `GET /public/premium-isp/orders`). |
| `include` | query | string: `lines` | no |  |
| `protocol` | query | string: `http`, `socks5` | no |  Default `"http"`. |
| `format` | query | string: `host:port:user:pass`, `ip:port:user:pass`, `user:pass@host:port`, `http://user:pass@host:port`, `socks5://user:pass@host:port` | no |  Default `"host:port:user:pass"`. |
| `quantity` | query | integer | no | Return only the first N lines. |
| `server` | query | string | no | 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. |

#### Examples

**curl**

```bash
curl -X GET 'https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'
```

**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"])
```

**Node (fetch)**

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

**PHP (curl)**

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

#### Responses

- `200` — Order (and lines).
- `202` — The IPs are being prepared: check again shortly.
- `400` — Malformed input. `message` names the parameter and the rule it broke.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `403` — Your own API key is required (keyless and pay-per-call access cannot buy), keys created by a connected app cannot spend the balance, or the plan was disabled by support.
- `404` — Unknown id — or an id that belongs to another account (ownership failures answer 404, never 403, so ids cannot be probed).
- `409` — The selection cannot be sold right now, or the request conflicts with an earlier one. Nothing was charged unless the code says so.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `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.

Example `200` response:

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

Example `400`:

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

Example `401`:

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

Example `403`:

```json
{
  "type": "error",
  "message": "Premium ISP needs your own API key. Create one in the dashboard under API keys.",
  "payload": {
    "code": "KEY_REQUIRED"
  }
}
```

Example `404`:

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

Example `409`:

```json
{
  "type": "error",
  "message": "This city is not available right now.",
  "payload": {
    "code": "CITY_UNAVAILABLE"
  }
}
```

Example `429`:

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

Example `503`:

```json
{
  "type": "error",
  "message": "Premium ISP is not available through the API yet. Use the dashboard to buy Premium ISP plans.",
  "payload": {
    "code": "PRODUCT_DISABLED"
  }
}
```

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

### Quote a Premium ISP renewal

`GET /public/premium-isp/orders/{orderId}/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.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orderId` | path | string | yes | `id` of the order (from `POST /public/premium-isp/orders` or `GET /public/premium-isp/orders`). |

#### Examples

**curl**

```bash
curl -X GET 'https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/renewal' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'
```

**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"])
```

**Node (fetch)**

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

**PHP (curl)**

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

#### Responses

- `200` — Renewal quote.
- `400` — Malformed input. `message` names the parameter and the rule it broke.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `403` — Your own API key is required (keyless and pay-per-call access cannot buy), keys created by a connected app cannot spend the balance, or the plan was disabled by support.
- `404` — Unknown id — or an id that belongs to another account (ownership failures answer 404, never 403, so ids cannot be probed).
- `409` — The selection cannot be sold right now, or the request conflicts with an earlier one. Nothing was charged unless the code says so.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `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.

Example `200` response:

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

Example `400`:

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

Example `401`:

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

Example `403`:

```json
{
  "type": "error",
  "message": "Premium ISP needs your own API key. Create one in the dashboard under API keys.",
  "payload": {
    "code": "KEY_REQUIRED"
  }
}
```

Example `404`:

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

Example `409`:

```json
{
  "type": "error",
  "message": "This city is not available right now.",
  "payload": {
    "code": "CITY_UNAVAILABLE"
  }
}
```

Example `429`:

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

Example `503`:

```json
{
  "type": "error",
  "message": "Premium ISP is not available through the API yet. Use the dashboard to buy Premium ISP plans.",
  "payload": {
    "code": "PRODUCT_DISABLED"
  }
}
```

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

### Renew a Premium ISP plan from the balance

`POST /public/premium-isp/orders/{orderId}/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)

Extends the plan by its own term with the same IPs and charges the balance (the carrier fee again, when the plan has a pinned carrier), or by `days` when the renewal quote lists that length in `options`. `Idempotency-Key` is required. 202 means the renewal is being verified: do not send it again, it completes or is refunded automatically. A `days` the plan cannot take is refused with 400 VALIDATION_ERROR before any charge. 20 renewals an hour per account.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orderId` | path | string | yes | `id` of the order (from `POST /public/premium-isp/orders` or `GET /public/premium-isp/orders`). |
| `Idempotency-Key` | header | string | yes | 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

`Content-Type: application/json`

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

Example:

```json
{
  "days": 30
}
```

#### Examples

**curl**

```bash
curl -X POST 'https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/renewal' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"days":30}'
```

**Python (requests)**

```python
import requests

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

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/renewal", {
  method: "POST",
  headers: {
    Authorization: "Bearer qd_live_YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "days": 30
  })
});
const data = await res.json();
if (data.type !== "response") throw new Error(data.message);
console.log(data.payload);
```

**PHP (curl)**

```php
<?php
$ch = curl_init('https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/renewal');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode([
    'days' => 30
  ]),
]);
$raw = curl_exec($ch);
curl_close($ch);
$data = json_decode($raw, true);
if ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }
print_r($data['payload']);
```

#### Responses

- `200` — Renewed.
- `202` — Being verified: do not send it again.
- `400` — Malformed input. `message` names the parameter and the rule it broke.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `402` — The wallet balance cannot cover the total. Nothing was created or charged: top up in the dashboard and send the request again.
- `403` — Your own API key is required (keyless and pay-per-call access cannot buy), keys created by a connected app cannot spend the balance, or the plan was disabled by support.
- `404` — Unknown id — or an id that belongs to another account (ownership failures answer 404, never 403, so ids cannot be probed).
- `409` — The selection cannot be sold right now, or the request conflicts with an earlier one. Nothing was charged unless the code says so.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `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.

Example `200` response:

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

Example `400`:

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

Example `401`:

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

Example `402`:

```json
{
  "type": "error",
  "message": "Your balance is too low for this purchase. Top up in the dashboard and try again.",
  "payload": {
    "code": "INSUFFICIENT_BALANCE"
  }
}
```

Example `403`:

```json
{
  "type": "error",
  "message": "Premium ISP needs your own API key. Create one in the dashboard under API keys.",
  "payload": {
    "code": "KEY_REQUIRED"
  }
}
```

Example `404`:

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

Example `409`:

```json
{
  "type": "error",
  "message": "This city is not available right now.",
  "payload": {
    "code": "CITY_UNAVAILABLE"
  }
}
```

Example `429`:

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

Example `503`:

```json
{
  "type": "error",
  "message": "Premium ISP is not available through the API yet. Use the dashboard to buy Premium ISP plans.",
  "payload": {
    "code": "PRODUCT_DISABLED"
  }
}
```

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

### IP swaps of a city plan

`GET /public/premium-isp/orders/{orderId}/replacements`

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

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orderId` | path | string | yes | `id` of the order (from `POST /public/premium-isp/orders` or `GET /public/premium-isp/orders`). |

#### Examples

**curl**

```bash
curl -X GET 'https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/replacements' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'
```

**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"])
```

**Node (fetch)**

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

**PHP (curl)**

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

#### Responses

- `200` — IP swaps.
- `400` — Malformed input. `message` names the parameter and the rule it broke.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `403` — Your own API key is required (keyless and pay-per-call access cannot buy), keys created by a connected app cannot spend the balance, or the plan was disabled by support.
- `404` — Unknown id — or an id that belongs to another account (ownership failures answer 404, never 403, so ids cannot be probed).
- `409` — The selection cannot be sold right now, or the request conflicts with an earlier one. Nothing was charged unless the code says so.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `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.

Example `200` response:

```json
{
  "type": "response",
  "message": "Success",
  "payload": {
    "bought": 2,
    "used": 0,
    "checking": 0,
    "left": 2,
    "paid": 0,
    "paidSwapPrice": 1.5
  },
  "pagination": {}
}
```

Example `400`:

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

Example `401`:

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

Example `403`:

```json
{
  "type": "error",
  "message": "Premium ISP needs your own API key. Create one in the dashboard under API keys.",
  "payload": {
    "code": "KEY_REQUIRED"
  }
}
```

Example `404`:

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

Example `409`:

```json
{
  "type": "error",
  "message": "This city is not available right now.",
  "payload": {
    "code": "CITY_UNAVAILABLE"
  }
}
```

Example `429`:

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

Example `503`:

```json
{
  "type": "error",
  "message": "Premium ISP is not available through the API yet. Use the dashboard to buy Premium ISP plans.",
  "payload": {
    "code": "PRODUCT_DISABLED"
  }
}
```

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

### Replace one IP of a city plan

`POST /public/premium-isp/orders/{orderId}/replacements`

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

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orderId` | path | string | yes | `id` of the order (from `POST /public/premium-isp/orders` or `GET /public/premium-isp/orders`). |

#### Request body (required)

`Content-Type: application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ip` | string | yes | One of the plan's exit IPs (`lines.ipAddresses`). |
| `pay` | boolean | no | 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. Default `false`. |

Example:

```json
{
  "ip": "203.0.113.7",
  "pay": false
}
```

#### Examples

**curl**

```bash
curl -X POST 'https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/replacements' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"ip":"203.0.113.7","pay":false}'
```

**Python (requests)**

```python
import requests

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

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/replacements", {
  method: "POST",
  headers: {
    Authorization: "Bearer qd_live_YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "ip": "203.0.113.7",
    "pay": false
  })
});
const data = await res.json();
if (data.type !== "response") throw new Error(data.message);
console.log(data.payload);
```

**PHP (curl)**

```php
<?php
$ch = curl_init('https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/replacements');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode([
    'ip' => '203.0.113.7',
    'pay' => false
  ]),
]);
$raw = curl_exec($ch);
curl_close($ch);
$data = json_decode($raw, true);
if ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }
print_r($data['payload']);
```

#### Responses

- `200` — Replaced.
- `202` — Being prepared: counts as used, do not send it again.
- `400` — Malformed input. `message` names the parameter and the rule it broke.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `402` — The wallet balance cannot cover the total. Nothing was created or charged: top up in the dashboard and send the request again.
- `403` — Your own API key is required (keyless and pay-per-call access cannot buy), keys created by a connected app cannot spend the balance, or the plan was disabled by support.
- `404` — Unknown id — or an id that belongs to another account (ownership failures answer 404, never 403, so ids cannot be probed).
- `409` — The selection cannot be sold right now, or the request conflicts with an earlier one. Nothing was charged unless the code says so.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `502` — The IP could not be swapped right now. No swap was used.
- `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.

Example `200` response:

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

Example `400`:

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

Example `401`:

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

Example `402`:

```json
{
  "type": "error",
  "message": "Your balance is too low for this purchase. Top up in the dashboard and try again.",
  "payload": {
    "code": "INSUFFICIENT_BALANCE"
  }
}
```

Example `403`:

```json
{
  "type": "error",
  "message": "Premium ISP needs your own API key. Create one in the dashboard under API keys.",
  "payload": {
    "code": "KEY_REQUIRED"
  }
}
```

Example `404`:

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

Example `409`:

```json
{
  "type": "error",
  "message": "This city is not available right now.",
  "payload": {
    "code": "CITY_UNAVAILABLE"
  }
}
```

Example `429`:

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

Example `502`:

```json
{
  "type": "error",
  "message": "The IP could not be swapped right now. No swap was used.",
  "payload": {
    "code": "REPLACEMENT_REFUSED"
  }
}
```

Example `503`:

```json
{
  "type": "error",
  "message": "Premium ISP is not available through the API yet. Use the dashboard to buy Premium ISP plans.",
  "payload": {
    "code": "PRODUCT_DISABLED"
  }
}
```

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

### Auto-replace setting of a city plan

`GET /public/premium-isp/orders/{orderId}/auto-replace`

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

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orderId` | path | string | yes | `id` of the order (from `POST /public/premium-isp/orders` or `GET /public/premium-isp/orders`). |

#### Examples

**curl**

```bash
curl -X GET 'https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/auto-replace' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'
```

**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"])
```

**Node (fetch)**

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

**PHP (curl)**

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

#### Responses

- `200` — The setting.
- `400` — Malformed input. `message` names the parameter and the rule it broke.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `403` — Your own API key is required (keyless and pay-per-call access cannot buy), keys created by a connected app cannot spend the balance, or the plan was disabled by support.
- `404` — Unknown id — or an id that belongs to another account (ownership failures answer 404, never 403, so ids cannot be probed).
- `409` — The selection cannot be sold right now, or the request conflicts with an earlier one. Nothing was charged unless the code says so.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `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.

Example `200` response:

```json
{
  "type": "response",
  "message": "Success",
  "payload": {
    "available": true,
    "state": "on",
    "ips": 5
  },
  "pagination": {}
}
```

Example `400`:

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

Example `401`:

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

Example `403`:

```json
{
  "type": "error",
  "message": "Premium ISP needs your own API key. Create one in the dashboard under API keys.",
  "payload": {
    "code": "KEY_REQUIRED"
  }
}
```

Example `404`:

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

Example `409`:

```json
{
  "type": "error",
  "message": "This city is not available right now.",
  "payload": {
    "code": "CITY_UNAVAILABLE"
  }
}
```

Example `429`:

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

Example `503`:

```json
{
  "type": "error",
  "message": "Premium ISP is not available through the API yet. Use the dashboard to buy Premium ISP plans.",
  "payload": {
    "code": "PRODUCT_DISABLED"
  }
}
```

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

### Switch auto-replace on or off

`POST /public/premium-isp/orders/{orderId}/auto-replace`

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

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orderId` | path | string | yes | `id` of the order (from `POST /public/premium-isp/orders` or `GET /public/premium-isp/orders`). |

#### Request body (required)

`Content-Type: application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | boolean | yes | `true` = replace offline IPs by itself; `false` = never replace an IP without a request. |

Example:

```json
{
  "enabled": false
}
```

#### Examples

**curl**

```bash
curl -X POST 'https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/auto-replace' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"enabled":false}'
```

**Python (requests)**

```python
import requests

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

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/auto-replace", {
  method: "POST",
  headers: {
    Authorization: "Bearer qd_live_YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "enabled": false
  })
});
const data = await res.json();
if (data.type !== "response") throw new Error(data.message);
console.log(data.payload);
```

**PHP (curl)**

```php
<?php
$ch = curl_init('https://api.quanticdata.io/v1/public/premium-isp/orders/ORDERID/auto-replace');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode([
    'enabled' => false
  ]),
]);
$raw = curl_exec($ch);
curl_close($ch);
$data = json_decode($raw, true);
if ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }
print_r($data['payload']);
```

#### Responses

- `200` — Changed.
- `400` — Malformed input. `message` names the parameter and the rule it broke.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `403` — Your own API key is required (keyless and pay-per-call access cannot buy), keys created by a connected app cannot spend the balance, or the plan was disabled by support.
- `404` — Unknown id — or an id that belongs to another account (ownership failures answer 404, never 403, so ids cannot be probed).
- `409` — The selection cannot be sold right now, or the request conflicts with an earlier one. Nothing was charged unless the code says so.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `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.

Example `200` response:

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

Example `400`:

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

Example `401`:

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

Example `403`:

```json
{
  "type": "error",
  "message": "Premium ISP needs your own API key. Create one in the dashboard under API keys.",
  "payload": {
    "code": "KEY_REQUIRED"
  }
}
```

Example `404`:

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

Example `409`:

```json
{
  "type": "error",
  "message": "This city is not available right now.",
  "payload": {
    "code": "CITY_UNAVAILABLE"
  }
}
```

Example `429`:

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

Example `503`:

```json
{
  "type": "error",
  "message": "Premium ISP is not available through the API yet. Use the dashboard to buy Premium ISP plans.",
  "payload": {
    "code": "PRODUCT_DISABLED"
  }
}
```

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

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

### List IPv6 speed plans

`GET /public/ipv6/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).

#### Examples

**curl**

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

**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"])
```

**Node (fetch)**

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

**PHP (curl)**

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

#### Responses

- `200` — The grid.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `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.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `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.

Example `200` response:

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

Example `401`:

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

Example `403`:

```json
{
  "type": "error",
  "message": "IPv6 speed plans need your own API key. Create one in the dashboard under API keys.",
  "payload": {
    "code": "KEY_REQUIRED"
  }
}
```

Example `429`:

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

Example `503`:

```json
{
  "type": "error",
  "message": "IPv6 speed plans are not available through the API yet. Use the dashboard to buy them.",
  "payload": {
    "code": "PRODUCT_DISABLED"
  }
}
```

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

### Quote an IPv6 speed plan

`POST /public/ipv6/quote`

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

#### Request body (required)

`Content-Type: application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `speedMbps` | integer | yes | A speed of the grid (`GET /public/ipv6/plans`). 1000 answers `CONTACT_REQUIRED`. |
| `days` | integer: `1`, `7`, `30` | yes | The term. Traffic is not metered for the whole term. |
| `paymentMethod` | string: `BALANCE` | no |  Default `"BALANCE"`. |

Example:

```json
{
  "speedMbps": 200,
  "days": 7
}
```

#### Examples

**curl**

```bash
curl -X POST 'https://api.quanticdata.io/v1/public/ipv6/quote' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"speedMbps":200,"days":7}'
```

**Python (requests)**

```python
import requests

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

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/public/ipv6/quote", {
  method: "POST",
  headers: {
    Authorization: "Bearer qd_live_YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "speedMbps": 200,
    "days": 7
  })
});
const data = await res.json();
if (data.type !== "response") throw new Error(data.message);
console.log(data.payload);
```

**PHP (curl)**

```php
<?php
$ch = curl_init('https://api.quanticdata.io/v1/public/ipv6/quote');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode([
    'speedMbps' => 200,
    'days' => 7
  ]),
]);
$raw = curl_exec($ch);
curl_close($ch);
$data = json_decode($raw, true);
if ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }
print_r($data['payload']);
```

#### Responses

- `200` — Quote.
- `400` — Malformed input. `message` names the parameter and the rule it broke.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `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.
- `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.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `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.

Example `200` response:

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

Example `400`:

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

Example `401`:

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

Example `403`:

```json
{
  "type": "error",
  "message": "IPv6 speed plans need your own API key. Create one in the dashboard under API keys.",
  "payload": {
    "code": "KEY_REQUIRED"
  }
}
```

Example `409`:

```json
{
  "type": "error",
  "message": "This speed is not sold. Available: 30 Mbps, 60 Mbps, 120 Mbps, 200 Mbps; 1000 Mbps on request.",
  "payload": {
    "code": "SPEED_UNAVAILABLE",
    "speeds": [
      30,
      60,
      120,
      200
    ]
  }
}
```

Example `429`:

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

Example `503`:

```json
{
  "type": "error",
  "message": "IPv6 speed plans are not available through the API yet. Use the dashboard to buy them.",
  "payload": {
    "code": "PRODUCT_DISABLED"
  }
}
```

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

### List IPv6 speed orders

`GET /public/ipv6/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).

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer | no |  Default `50`. |
| `offset` | query | integer | no |  Default `0`. |

#### Examples

**curl**

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

**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"])
```

**Node (fetch)**

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

**PHP (curl)**

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

#### Responses

- `200` — Orders.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `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.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `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.

Example `200` response:

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

Example `401`:

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

Example `403`:

```json
{
  "type": "error",
  "message": "IPv6 speed plans need your own API key. Create one in the dashboard under API keys.",
  "payload": {
    "code": "KEY_REQUIRED"
  }
}
```

Example `429`:

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

Example `503`:

```json
{
  "type": "error",
  "message": "IPv6 speed plans are not available through the API yet. Use the dashboard to buy them.",
  "payload": {
    "code": "PRODUCT_DISABLED"
  }
}
```

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

### Buy an IPv6 speed plan

`POST /public/ipv6/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)

Buy one speed × term cell from the wallet balance. Send a unique `Idempotency-Key` with every purchase: the same key again answers with the order already created, never a second charge. The grid is read again at purchase time; `maxTotal` lets you refuse a price above what you quoted (409 `PRICE_CHANGED`, nothing charged). Answers: 201 delivered (the plan is active; generate the endpoint strings with `POST /public/proxies/generate` and the order id), 200 replayed for a key already paid, 422 not delivered and refunded to the balance. Keyless and pay-per-call access cannot buy; keys created by a connected app cannot spend. 20 purchases an hour per account.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | yes | 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 (required)

`Content-Type: application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `speedMbps` | integer | yes | A speed of the grid (`GET /public/ipv6/plans`). 1000 answers `CONTACT_REQUIRED`. |
| `days` | integer: `1`, `7`, `30` | yes | The term. Traffic is not metered for the whole term. |
| `paymentMethod` | string: `BALANCE` | no |  Default `"BALANCE"`. |
| `maxTotal` | number | no | Refuse the purchase if the total is above this amount (USD). Nothing is charged then. |
| `idempotencyKey` | string | no | Alternative to the header. |

Example:

```json
{
  "speedMbps": 200,
  "days": 7,
  "maxTotal": 150
}
```

#### Examples

**curl**

```bash
curl -X POST 'https://api.quanticdata.io/v1/public/ipv6/orders' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"speedMbps":200,"days":7,"maxTotal":150}'
```

**Python (requests)**

```python
import requests

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

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/public/ipv6/orders", {
  method: "POST",
  headers: {
    Authorization: "Bearer qd_live_YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "speedMbps": 200,
    "days": 7,
    "maxTotal": 150
  })
});
const data = await res.json();
if (data.type !== "response") throw new Error(data.message);
console.log(data.payload);
```

**PHP (curl)**

```php
<?php
$ch = curl_init('https://api.quanticdata.io/v1/public/ipv6/orders');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer qd_live_YOUR_API_KEY', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode([
    'speedMbps' => 200,
    'days' => 7,
    'maxTotal' => 150
  ]),
]);
$raw = curl_exec($ch);
curl_close($ch);
$data = json_decode($raw, true);
if ($data['type'] !== 'response') { throw new RuntimeException($data['message']); }
print_r($data['payload']);
```

#### Responses

- `200` — Replayed: this Idempotency-Key was already paid. The order it created, no new charge.
- `201` — Delivered: the plan is active.
- `400` — Malformed input. `message` names the parameter and the rule it broke.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `402` — The wallet balance cannot cover the total. Nothing was created or charged: top up in the dashboard and send the request again.
- `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.
- `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.
- `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.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `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.

Example `200` response:

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

Example `400`:

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

Example `401`:

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

Example `402`:

```json
{
  "type": "error",
  "message": "Your balance is too low for this purchase. Top up in the dashboard and try again.",
  "payload": {
    "code": "INSUFFICIENT_BALANCE"
  }
}
```

Example `403`:

```json
{
  "type": "error",
  "message": "IPv6 speed plans need your own API key. Create one in the dashboard under API keys.",
  "payload": {
    "code": "KEY_REQUIRED"
  }
}
```

Example `409`:

```json
{
  "type": "error",
  "message": "This speed is not sold. Available: 30 Mbps, 60 Mbps, 120 Mbps, 200 Mbps; 1000 Mbps on request.",
  "payload": {
    "code": "SPEED_UNAVAILABLE",
    "speeds": [
      30,
      60,
      120,
      200
    ]
  }
}
```

Example `422`:

```json
{
  "type": "error",
  "message": "The plan could not be delivered. You have not been charged: the amount is back on your balance.",
  "payload": {
    "code": "NOT_DELIVERED_REFUNDED",
    "refunded": true,
    "newCheckoutRequired": true,
    "orderId": "ord_7a1c",
    "invoiceId": "inv_3b9e"
  }
}
```

Example `429`:

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

Example `503`:

```json
{
  "type": "error",
  "message": "IPv6 speed plans are not available through the API yet. Use the dashboard to buy them.",
  "payload": {
    "code": "PRODUCT_DISABLED"
  }
}
```

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

### Get an IPv6 speed order

`GET /public/ipv6/orders/{orderId}`

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

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orderId` | path | string | yes | `id` of the order (from `POST /public/ipv6/orders` or `GET /public/ipv6/orders`). The same id goes to `POST /public/proxies/generate`. |

#### Examples

**curl**

```bash
curl -X GET 'https://api.quanticdata.io/v1/public/ipv6/orders/ORDERID' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'
```

**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"])
```

**Node (fetch)**

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

**PHP (curl)**

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

#### Responses

- `200` — The order.
- `400` — Malformed input. `message` names the parameter and the rule it broke.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `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.
- `404` — Unknown id — or an id that belongs to another account (ownership failures answer 404, never 403, so ids cannot be probed).
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `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.

Example `200` response:

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

Example `400`:

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

Example `401`:

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

Example `403`:

```json
{
  "type": "error",
  "message": "IPv6 speed plans need your own API key. Create one in the dashboard under API keys.",
  "payload": {
    "code": "KEY_REQUIRED"
  }
}
```

Example `404`:

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

Example `429`:

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

Example `503`:

```json
{
  "type": "error",
  "message": "IPv6 speed plans are not available through the API yet. Use the dashboard to buy them.",
  "payload": {
    "code": "PRODUCT_DISABLED"
  }
}
```

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

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

### List the plans you can buy

`GET /public/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)

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.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `planType` | query | string: `residentialbasic`, `residentialpremium`, `resiprivate`, `isp`, `isppremium`, `datacenter`, `datacentertraffic`, `ipv6`, `mobile`, `mobile_v2` | no | Only plans of this type. An unknown value returns an empty list. |

#### Examples

**curl**

```bash
curl -X GET 'https://api.quanticdata.io/v1/public/plans?planType=residentialpremium' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'
```

**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"])
```

**Node (fetch)**

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

**PHP (curl)**

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

#### Responses

- `200` — Plans on sale.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `500` — Unexpected error; retry.

Example `200` response:

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

Example `401`:

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

Example `429`:

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

Example `500`:

```json
{
  "type": "error",
  "message": "Internal server error"
}
```

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

### Buy a plan from the balance

`POST /public/purchase`

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

#### Request body (required)

`Content-Type: application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `planId` | string | yes | `id` of a plan from `GET /public/plans`. |
| `coupon` | string | no | Coupon code (optional; empty string or null = none). |

Example:

```json
{
  "planId": "pln_3e7a"
}
```

#### Examples

**curl**

```bash
curl -X POST 'https://api.quanticdata.io/v1/public/purchase' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"planId":"pln_3e7a"}'
```

**Python (requests)**

```python
import requests

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

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/public/purchase", {
  method: "POST",
  headers: {
    Authorization: "Bearer qd_live_YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "planId": "pln_3e7a"
  })
});
const data = await res.json();
if (data.type !== "response") throw new Error(data.message);
console.log(data.payload);
```

**PHP (curl)**

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

#### Responses

- `200` — Paid and active. Credentials in `payload.proxy`.
- `400` — Nothing was charged: invalid body (including a body that is not JSON), trial-only plan, invalid coupon, total below the minimum purchase, balance too low, balance payments switched off, or a payment that could not be confirmed.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `403` — Purchases need your own API key: keyless and pay-per-call access cannot spend a balance.
- `404` — No active plan with this `planId`.
- `409` — The plan was not activated and the automatic refund could not be confirmed. Do not buy again: contact support with the order and invoice ids.
- `422` — The plan could not be activated and the amount is back on your balance: you have not been charged. You can buy again.
- `429` — Ten or more unpaid invoices in the last 24 hours (`TOO_MANY_UNPAID_INVOICES`: pay or cancel one, or contact support), or the key rate limit (see TooManyRequests).
- `500` — Unexpected error. Check `GET /public/orders` before buying again.

Example `200` response:

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

Example `400`:

```json
{
  "type": "error",
  "message": "validation error",
  "payload": [
    {
      "message": "\"planId\" is required",
      "path": [
        "planId"
      ],
      "type": "any.required",
      "context": {
        "label": "planId",
        "key": "planId"
      }
    }
  ]
}
```

Example `401`:

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

Example `403`:

```json
{
  "type": "error",
  "message": "Purchases need your own API key. Create one in the dashboard under API keys.",
  "payload": {
    "code": "KEY_REQUIRED"
  }
}
```

Example `404`:

```json
{
  "type": "error",
  "message": "Plan not found or inactive"
}
```

Example `409`:

```json
{
  "type": "error",
  "message": "Proxy activation failed and the automatic refund could not be confirmed. Please contact support before purchasing again.",
  "payload": {
    "code": "PAYMENT_UNDER_REVIEW",
    "orderId": "ord_8c21",
    "invoiceId": "inv_4b90"
  }
}
```

Example `422`:

```json
{
  "type": "error",
  "message": "Proxy activation failed. You have not been charged — please try again or contact support.",
  "payload": {
    "code": "NOT_DELIVERED_REFUNDED",
    "refunded": true,
    "orderId": "ord_8c21",
    "invoiceId": "inv_4b90"
  }
}
```

Example `429`:

```json
{
  "type": "error",
  "message": "You have too many unpaid invoices. Please pay at least one invoice or contact customer support to continue.",
  "payload": {
    "code": "TOO_MANY_UNPAID_INVOICES",
    "count": 10
  }
}
```

Example `500`:

```json
{
  "type": "error",
  "message": "Internal server error"
}
```

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

### List your orders

`GET /public/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.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer | no |  Default `50`. |
| `offset` | query | integer | no |  Default `0`. |
| `type` | query | string: `PROXY`, `TOPUP` | no | Only proxy plans (`PROXY`) or balance top-ups (`TOPUP`); omit for every order. |

#### Examples

**curl**

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

**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"])
```

**Node (fetch)**

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

**PHP (curl)**

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

#### Responses

- `200` — Orders.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `500` — Unexpected error (also a non-numeric `limit` or `offset`); retry.

Example `200` response:

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

Example `401`:

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

Example `429`:

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

Example `500`:

```json
{
  "type": "error",
  "message": "Internal server error"
}
```

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

### Get the wallet balance

`GET /public/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.

#### Examples

**curl**

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

**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"])
```

**Node (fetch)**

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

**PHP (curl)**

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

#### Responses

- `200` — Balance.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `500` — Unexpected error; retry.

Example `200` response:

```json
{
  "type": "response",
  "message": "success",
  "payload": {
    "balance": 42.5,
    "balanceUSD": 42.5,
    "totalSpent": 120,
    "totalSpentUSD": 120
  },
  "pagination": {}
}
```

Example `401`:

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

Example `429`:

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

Example `500`:

```json
{
  "type": "error",
  "message": "Internal server error"
}
```

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

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

### List countries for a plan type

`GET /public/geo/countries`

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

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `planType` | query | string: `residentialbasic`, `residentialpremium`, `resiprivate`, `isp`, `isppremium`, `datacenter`, `datacentertraffic`, `ipv6`, `mobile`, `mobile_v2` | yes | Plan type whose countries you want. |

#### Examples

**curl**

```bash
curl -X GET 'https://api.quanticdata.io/v1/public/geo/countries?planType=residentialbasic' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'
```

**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"])
```

**Node (fetch)**

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

**PHP (curl)**

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

#### Responses

- `200` — Countries.
- `400` — Missing or unknown query parameter.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `500` — The countries could not be read right now; retry.

Example `200` response:

```json
{
  "type": "response",
  "message": "success",
  "payload": {
    "countries": [
      {
        "code": "us",
        "name": "United States"
      },
      {
        "code": "de",
        "name": "Germany"
      }
    ],
    "planType": "residentialbasic"
  },
  "pagination": {}
}
```

Example `400`:

```json
{
  "type": "error",
  "message": "planType query parameter is required"
}
```

Example `401`:

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

Example `429`:

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

Example `500`:

```json
{
  "type": "error",
  "message": "Failed to fetch countries. Please try again later."
}
```

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

### List states or regions of a country

`GET /public/geo/states`

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

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `planType` | query | string: `residentialbasic`, `residentialpremium`, `resiprivate`, `isp`, `isppremium`, `datacenter`, `datacentertraffic`, `ipv6`, `mobile`, `mobile_v2` | yes | Plan type. |
| `country` | query | string | yes | Country code, either case. |

#### Examples

**curl**

```bash
curl -X GET 'https://api.quanticdata.io/v1/public/geo/states?planType=residentialpremium&country=AL' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'
```

**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"])
```

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/public/geo/states?planType=residentialpremium&country=AL", {
  method: "GET",
  headers: {
    Authorization: "Bearer qd_live_YOUR_API_KEY"
  }
});
const data = await res.json();
if (data.type !== "response") throw new Error(data.message);
console.log(data.payload);
```

**PHP (curl)**

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

#### Responses

- `200` — States.
- `400` — Missing or unknown query parameter.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `404` — Residential Basic / traffic-based Datacenter: the account has no plan of these types, so there is no location list to read.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `500` — The states could not be read right now; retry.

Example `200` response:

```json
{
  "type": "response",
  "message": "success",
  "payload": {
    "states": [
      {
        "code": "durres",
        "state_code": "durres",
        "name": "Durres",
        "state": "Durres"
      }
    ],
    "country": "AL",
    "planType": "residentialpremium"
  },
  "pagination": {}
}
```

Example `400`:

```json
{
  "type": "error",
  "message": "planType query parameter is required"
}
```

Example `401`:

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

Example `404`:

```json
{
  "type": "error",
  "message": "No active proxy plan found. Purchase a residential basic or datacenter traffic plan to use geo-targeting."
}
```

Example `429`:

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

Example `500`:

```json
{
  "type": "error",
  "message": "Failed to fetch states. Please try again later."
}
```

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

### List cities of a country or state

`GET /public/geo/cities`

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

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `planType` | query | string: `residentialbasic`, `residentialpremium`, `resiprivate`, `isp`, `isppremium`, `datacenter`, `datacentertraffic`, `ipv6`, `mobile`, `mobile_v2` | yes | Plan type. |
| `country` | query | string | yes | Country code, either case. |
| `state` | query | string | no | State `code` from `GET /public/geo/states` (Residential Basic also accepts the name). |

#### Examples

**curl**

```bash
curl -X GET 'https://api.quanticdata.io/v1/public/geo/cities?planType=residentialpremium&country=AL&state=durres' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'
```

**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"])
```

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/public/geo/cities?planType=residentialpremium&country=AL&state=durres", {
  method: "GET",
  headers: {
    Authorization: "Bearer qd_live_YOUR_API_KEY"
  }
});
const data = await res.json();
if (data.type !== "response") throw new Error(data.message);
console.log(data.payload);
```

**PHP (curl)**

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

#### Responses

- `200` — Cities.
- `400` — Missing or unknown query parameter.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `404` — Residential Basic / traffic-based Datacenter: the account has no plan of these types, so there is no location list to read.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `500` — The cities could not be read right now; retry.

Example `200` response:

```json
{
  "type": "response",
  "message": "success",
  "payload": {
    "cities": [
      {
        "code": "durres",
        "name": "Durres"
      }
    ],
    "country": "AL",
    "state": "durres",
    "planType": "residentialpremium"
  },
  "pagination": {}
}
```

Example `400`:

```json
{
  "type": "error",
  "message": "planType query parameter is required"
}
```

Example `401`:

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

Example `404`:

```json
{
  "type": "error",
  "message": "No active proxy plan found. Purchase a residential basic or datacenter traffic plan to use geo-targeting."
}
```

Example `429`:

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

Example `500`:

```json
{
  "type": "error",
  "message": "Failed to fetch cities. Please try again later."
}
```

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

### List ASNs for Residential Basic and Datacenter

`GET /public/geo/asns`

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

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `planType` | query | string: `residentialbasic`, `residentialpremium`, `resiprivate`, `isp`, `isppremium`, `datacenter`, `datacentertraffic`, `ipv6`, `mobile`, `mobile_v2` | yes | `residentialbasic` or `datacentertraffic`. |
| `country` | query | string | no | Country code; omit for every country. |

#### Examples

**curl**

```bash
curl -X GET 'https://api.quanticdata.io/v1/public/geo/asns?planType=residentialbasic&country=US' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'
```

**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"])
```

**Node (fetch)**

```javascript
const res = await fetch("https://api.quanticdata.io/v1/public/geo/asns?planType=residentialbasic&country=US", {
  method: "GET",
  headers: {
    Authorization: "Bearer qd_live_YOUR_API_KEY"
  }
});
const data = await res.json();
if (data.type !== "response") throw new Error(data.message);
console.log(data.payload);
```

**PHP (curl)**

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

#### Responses

- `200` — ASNs.
- `400` — Missing or unknown query parameter.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `404` — The account has no Residential Basic or traffic-based Datacenter plan.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `500` — The ASNs could not be read right now; retry.

Example `200` response:

```json
{
  "type": "response",
  "message": "success",
  "payload": {
    "asns": [
      {
        "asn": "7922",
        "name": "Comcast Cable Communications, LLC"
      }
    ],
    "country": "US",
    "planType": "residentialbasic"
  },
  "pagination": {}
}
```

Example `400`:

```json
{
  "type": "error",
  "message": "planType query parameter is required"
}
```

Example `401`:

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

Example `404`:

```json
{
  "type": "error",
  "message": "No active plan found for this plan type. Purchase a residential basic or datacenter (traffic-based) plan."
}
```

Example `429`:

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

Example `500`:

```json
{
  "type": "error",
  "message": "Failed to fetch ASNs. Please try again later."
}
```

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

### Residential Premium location tree (geo)

`GET /public/geo/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 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.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `planType` | query | string: `residentialpremium` | no | Optional; only `residentialpremium` is accepted. |

#### Examples

**curl**

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

**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"])
```

**Node (fetch)**

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

**PHP (curl)**

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

#### Responses

- `200` — Location tree.
- `400` — `planType` other than `residentialpremium`.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.

Example `200` response:

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

Example `400`:

```json
{
  "type": "error",
  "message": "Only planType=residentialpremium is supported for locations"
}
```

Example `401`:

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

Example `429`:

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

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

### Residential Premium targeting options

`GET /public/generator/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.

#### Examples

**curl**

```bash
curl -X GET 'https://api.quanticdata.io/v1/public/generator/residential-premium/targeting-options' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'
```

**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"])
```

**Node (fetch)**

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

**PHP (curl)**

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

#### Responses

- `200` — Location tree.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.

Example `200` response:

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

Example `401`:

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

Example `429`:

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

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

### Mobile targeting options

`GET /public/generator/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.

#### Examples

**curl**

```bash
curl -X GET 'https://api.quanticdata.io/v1/public/generator/mobile/targeting-options' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'
```

**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"])
```

**Node (fetch)**

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

**PHP (curl)**

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

#### Responses

- `200` — Location tree.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.
- `502` — The tree could not be read right now; retry.

Example `200` response:

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

Example `401`:

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

Example `429`:

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

Example `502`:

```json
{
  "type": "error",
  "message": "Could not retrieve mobile targeting options. Please try again later."
}
```

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

### Datacenter gateway locations

`GET /public/generator/datacenter/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 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.

#### Examples

**curl**

```bash
curl -X GET 'https://api.quanticdata.io/v1/public/generator/datacenter/targeting-options' \
  -H 'Authorization: Bearer qd_live_YOUR_API_KEY'
```

**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"])
```

**Node (fetch)**

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

**PHP (curl)**

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

#### Responses

- `200` — Gateways.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `429` — Key rate limit (hourly window), plan per-minute budget, browser-render concurrency, or pool capacity. Back off on Retry-After.

Example `200` response:

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

Example `401`:

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

Example `429`:

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

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