# Proxies — QuantumProxies.io API

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

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

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

## Proxies

List your proxy plans, generate endpoint strings, manage IP whitelists.

### 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.quantumproxies.io/data-api/playground) · [Markdown for this group](https://quantumproxies.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.

#### 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.quantumproxies.io/v1/public/proxies' \
  -H 'Authorization: Bearer qp_live_YOUR_API_KEY'
```

**Python (requests)**

```python
import requests

r = requests.get(
    'https://api.quantumproxies.io/v1/public/proxies',
    headers={"Authorization": "Bearer qp_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.quantumproxies.io/v1/public/proxies", {
  method: "GET",
  headers: {
    Authorization: "Bearer qp_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.quantumproxies.io/v1/public/proxies');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer qp_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",
        "proxyId": "sub_19a",
        "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 qp_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.quantumproxies.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.quantumproxies.io/data-api/playground) · [Markdown for this group](https://quantumproxies.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`. Which parameters apply depends on the plan type — unsupported ones are ignored, not rejected. 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`. |
| `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`. |
| `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. Default `"ww"`. |

Example:

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

#### Examples

**curl**

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

**Python (requests)**

```python
import requests

r = requests.post(
    'https://api.quantumproxies.io/v1/public/proxies/generate',
    headers={"Authorization": "Bearer qp_live_YOUR_API_KEY"},
    json={
        "orderId": "ord_8c21",
        "protocol": "http",
        "format": "user:pass@host:port",
        "quantity": 5,
        "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.quantumproxies.io/v1/public/proxies/generate", {
  method: "POST",
  headers: {
    Authorization: "Bearer qp_live_YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "orderId": "ord_8c21",
    "protocol": "http",
    "format": "user:pass@host:port",
    "quantity": 5,
    "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.quantumproxies.io/v1/public/proxies/generate');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer qp_live_YOUR_API_KEY', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode([
    'orderId' => 'ord_8c21',
    'protocol' => 'http',
    'format' => 'user:pass@host:port',
    'quantity' => 5,
    '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.
- `202` — Premium ISP order still being provisioned.
- `400` — Missing orderId, expired plan, inactive sub-user, or a plan type that cannot generate.
- `401` — Missing, malformed, unknown, disabled or expired API key; or the account is not active.
- `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": 5,
    "protocol": "http",
    "format": "user:pass@host:port",
    "rotation": "sticky",
    "sessionTime": 10,
    "geoTargeting": {
      "country": "us",
      "state": null,
      "city": null
    },
    "proxies": [
      "user_8c21-country-us-session-a1b2c3-time-10:p4ssw0rd@residential-ww.quantumproxies.io:9999",
      "user_8c21-country-us-session-d4e5f6-time-10:p4ssw0rd@residential-ww.quantumproxies.io:9999"
    ],
    "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 qp_live_YOUR_API_KEY"
}
```

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.quantumproxies.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.quantumproxies.io/data-api/playground) · [Markdown for this group](https://quantumproxies.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.quantumproxies.io/v1/public/proxies/ip-info?ip=203.0.113.7' \
  -H 'Authorization: Bearer qp_live_YOUR_API_KEY'
```

**Python (requests)**

```python
import requests

r = requests.get(
    'https://api.quantumproxies.io/v1/public/proxies/ip-info?ip=203.0.113.7',
    headers={"Authorization": "Bearer qp_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.quantumproxies.io/v1/public/proxies/ip-info?ip=203.0.113.7", {
  method: "GET",
  headers: {
    Authorization: "Bearer qp_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.quantumproxies.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 qp_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 qp_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.quantumproxies.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.quantumproxies.io/data-api/playground) · [Markdown for this group](https://quantumproxies.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.quantumproxies.io/v1/public/proxies/whitelist-ip?orderId=ORDERID' \
  -H 'Authorization: Bearer qp_live_YOUR_API_KEY'
```

**Python (requests)**

```python
import requests

r = requests.get(
    'https://api.quantumproxies.io/v1/public/proxies/whitelist-ip?orderId=ORDERID',
    headers={"Authorization": "Bearer qp_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.quantumproxies.io/v1/public/proxies/whitelist-ip?orderId=ORDERID", {
  method: "GET",
  headers: {
    Authorization: "Bearer qp_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.quantumproxies.io/v1/public/proxies/whitelist-ip?orderId=ORDERID');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer qp_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.
- `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 qp_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.quantumproxies.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.quantumproxies.io/data-api/playground) · [Markdown for this group](https://quantumproxies.io/docs/proxies.md)

Allows an IPv4 address to use the plan by IP authentication. Supported on Residential Basic, Datacenter (both kinds), ISP, IPv6 and Mobile V2; Residential Premium/Private authenticate by user:pass and answer 200 with `whitelisted: false`. 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.quantumproxies.io/v1/public/proxies/whitelist-ip' \
  -H 'Authorization: Bearer qp_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.quantumproxies.io/v1/public/proxies/whitelist-ip',
    headers={"Authorization": "Bearer qp_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.quantumproxies.io/v1/public/proxies/whitelist-ip", {
  method: "POST",
  headers: {
    Authorization: "Bearer qp_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.quantumproxies.io/v1/public/proxies/whitelist-ip');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer qp_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.
- `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 qp_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.quantumproxies.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.quantumproxies.io/data-api/playground) · [Markdown for this group](https://quantumproxies.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 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.quantumproxies.io/v1/public/proxies/whitelist-ip' \
  -H 'Authorization: Bearer qp_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.quantumproxies.io/v1/public/proxies/whitelist-ip',
    headers={"Authorization": "Bearer qp_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.quantumproxies.io/v1/public/proxies/whitelist-ip", {
  method: "DELETE",
  headers: {
    Authorization: "Bearer qp_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.quantumproxies.io/v1/public/proxies/whitelist-ip');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'DELETE',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer qp_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.
- `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 qp_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.quantumproxies.io/data-api/playground