# FlashProxy API reference

Check your balance and plans, read usage, generate proxies and extend plans from your own scripts. Every endpoint returns JSON and only reads data from your own account.

Base URL: `https://www.flashproxy.com`

Create an API key in your dashboard at https://www.flashproxy.com/dashboard/api. The full key is shown only once, so store it safely.

Using an AI agent? Give it this whole reference as one Markdown file: https://www.flashproxy.com/api-reference.md. An OpenAPI 3.1 spec is at https://www.flashproxy.com/openapi.json.

## Quickstart

List your plans, then use a plan_id from the answer in the other endpoints.

**cURL**

```bash
curl "https://www.flashproxy.com/api/v1/plans?status=active&limit=10" \
  -H "Authorization: Bearer fpk_live_YOUR_KEY"
```

**Python**

```python
import requests

response = requests.get(
    "https://www.flashproxy.com/api/v1/plans?status=active&limit=10",
    headers={
        "Authorization": "Bearer fpk_live_YOUR_KEY",
    },
    timeout=30,
)
print(response.json())
```

**Node.js**

```javascript
const response = await fetch("https://www.flashproxy.com/api/v1/plans?status=active&limit=10", {
  headers: {
    "Authorization": "Bearer fpk_live_YOUR_KEY",
  },
});
console.log(await response.json());
```

## Authentication

Send your key in the `Authorization` header as `Bearer fpk_live_…`, or in the `X-API-Key` header.

Every key can read usage. Generating proxies and extending plans each need their own permission, which you choose when you create the key. Treat a key like a password and revoke it if it leaks.

**Key permissions**

| Permission | Allows |
| --- | --- |
| `usage` | Read data used, data left and current speed. Every key has it. |
| `proxies` | Generate proxy lists. Responses contain your proxy username and password. |
| `extend` | Extend plans. Each call is paid from your account balance. |

## Account

### Current key

`GET /api/v1/key`

Returns the key you are calling with: its name, prefix and permissions. Useful when a call answers 403 FORBIDDEN.

Permission: `usage`

**Request**

```bash
curl "https://www.flashproxy.com/api/v1/key" \
  -H "Authorization: Bearer fpk_live_YOUR_KEY"
```

**Response · 200**

```json
{
  "success": true,
  "data": {
    "key_id": "7d1c2b4e-…",
    "name": "Monitoring server",
    "key_prefix": "fpk_live_k3x9q2ma",
    "permissions": [
      "usage",
      "proxies",
      "extend"
    ],
    "created_at": "2026-09-29T12:00:00.000Z",
    "last_used_at": "2026-10-13T12:00:00.000Z"
  }
}
```

### Account balance

`GET /api/v1/balance`

Returns your available account balance, the money extensions are paid from.

Permission: `usage`

**Request**

```bash
curl "https://www.flashproxy.com/api/v1/balance" \
  -H "Authorization: Bearer fpk_live_YOUR_KEY"
```

**Response · 200**

```json
{
  "success": true,
  "data": {
    "balance_usd": 42.18,
    "balance_cents": 4218,
    "currency": "USD"
  }
}
```

### List plans

`GET /api/v1/plans`

Returns your plans, newest first, with their status, expiry, data cap and whether they are extended by gb or days. Never returns proxy credentials.

Permission: `usage`

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `status` | query |  | all (default), active or expired. |
| `limit` | query |  | How many plans to return, up to 100. Defaults to 50. |
| `offset` | query |  | How many plans to skip, for paging. Defaults to 0. |

**Request**

```bash
curl "https://www.flashproxy.com/api/v1/plans?status=active&limit=10" \
  -H "Authorization: Bearer fpk_live_YOUR_KEY"
```

**Response · 200**

```json
{
  "success": true,
  "data": {
    "plans": [
      {
        "plan_id": "YOUR_PLAN_ID",
        "product": "residential",
        "name": "Residential Proxies",
        "status": "active",
        "billed_by": "data",
        "created_at": "2026-09-13T12:00:00.000Z",
        "expires_at": "2027-03-12T12:00:00.000Z",
        "max_bytes": 10737418240,
        "bytes_used": 4294967296,
        "speed_mbps": null,
        "extend_with": "gb"
      }
    ],
    "total": 1,
    "limit": 10,
    "offset": 0
  }
}
```

### List transactions

`GET /api/v1/transactions`

Returns your payments, top-ups and balance purchases, newest first, for bookkeeping.

Permission: `usage`

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `limit` | query |  | How many transactions to return, up to 100. Defaults to 50. |
| `offset` | query |  | How many transactions to skip, for paging. Defaults to 0. |

**Request**

```bash
curl "https://www.flashproxy.com/api/v1/transactions?limit=10" \
  -H "Authorization: Bearer fpk_live_YOUR_KEY"
```

**Response · 200**

```json
{
  "success": true,
  "data": {
    "transactions": [
      {
        "transaction_id": "FP-1791900000000-a1b2c3d4e",
        "type": "PURCHASE",
        "status": "COMPLETED",
        "amount_usd": 29.8,
        "payment_method": "BALANCE",
        "description": "Purchase of 1 item",
        "created_at": "2026-10-11T12:00:00.000Z",
        "completed_at": "2026-10-11T12:00:00.000Z"
      }
    ],
    "total": 1,
    "limit": 10,
    "offset": 0,
    "currency": "USD"
  }
}
```,## Usage

### Usage of all active plans

`GET /api/v1/usage`

Returns a usage record for every active plan on your account.

Permission: `usage`

**Request**

```bash
curl "https://www.flashproxy.com/api/v1/usage" \
  -H "Authorization: Bearer fpk_live_YOUR_KEY"
```

**Response · 200**

```json
{
  "success": true,
  "data": {
    "plans": [
      {
        "plan_id": "YOUR_PLAN_ID",
        "product": "ipv6-datacenter",
        "name": "IPv6 Datacenter Proxies",
        "status": "active",
        "expires_at": "2026-11-01T12:00:00.000Z",
        "usage": {
          "bytes_used": 2639963,
          "max_bytes": null,
          "remaining_bytes": null,
          "percentage_used": null
        },
        "throughput_status": "ok",
        "throughput": {
          "source": "per_minute",
          "current_mbps": 412.5,
          "avg_mbps_5m": 380.1,
          "peak_mbps_1h": 955,
          "sampled_at": "2026-10-13T11:59:15.000Z",
          "data_delay_seconds": 45,
          "limit_mbps": 1000,
          "utilization_pct": 41.25
        },
        "generated_at": "2026-10-13T12:00:00.000Z"
      }
    ]
  }
}
```

### Usage of one plan

`GET /api/v1/plans/{plan_id}/usage`

Returns the usage record of one of your plans, whatever its status.

Permission: `usage`

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `plan_id` | path | required | The plan ID, as returned in plan_id by List plans. |

**Request**

```bash
curl "https://www.flashproxy.com/api/v1/plans/YOUR_PLAN_ID/usage" \
  -H "Authorization: Bearer fpk_live_YOUR_KEY"
```

**Response · 200**

```json
{
  "success": true,
  "data": {
    "plan_id": "YOUR_PLAN_ID",
    "product": "ipv6-datacenter",
    "name": "IPv6 Datacenter Proxies",
    "status": "active",
    "expires_at": "2026-11-01T12:00:00.000Z",
    "usage": {
      "bytes_used": 2639963,
      "max_bytes": null,
      "remaining_bytes": null,
      "percentage_used": null
    },
    "throughput_status": "ok",
    "throughput": {
      "source": "per_minute",
      "current_mbps": 412.5,
      "avg_mbps_5m": 380.1,
      "peak_mbps_1h": 955,
      "sampled_at": "2026-10-13T11:59:15.000Z",
      "data_delay_seconds": 45,
      "limit_mbps": 1000,
      "utilization_pct": 41.25
    },
    "generated_at": "2026-10-13T12:00:00.000Z"
  }
}
```

### Usage history

`GET /api/v1/plans/{plan_id}/usage/history`

Returns a plan's traffic and speed over time, in fixed buckets (1 minute for 1h up to 4 hours for 30d), with totals, success rate and peaks. Timestamps are UTC. Available for ISP, ISP EU, Datacenter, IPv6 and Premium Unlimited plans.

Permission: `usage`

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `plan_id` | path | required | The plan ID, as returned in plan_id by List plans. |
| `range` | query |  | Time window: 1h, 24h, 7d, 30d. Defaults to 24h. |

**Request**

```bash
curl "https://www.flashproxy.com/api/v1/plans/YOUR_PLAN_ID/usage/history?range=24h" \
  -H "Authorization: Bearer fpk_live_YOUR_KEY"
```

**Response · 200**

```json
{
  "success": true,
  "data": {
    "plan_id": "YOUR_PLAN_ID",
    "range": "24h",
    "bucket_seconds": 900,
    "generated_at": "2026-10-13T12:00:00.000Z",
    "totals": {
      "bytes": 3221225472,
      "bytes_up": 214748364.8,
      "bytes_down": 3006477107.2,
      "connections": 48210,
      "success_pct": 99.2,
      "peak_mbps": 412.5,
      "peak_concurrent": 37
    },
    "series": [
      {
        "t": "2026-10-13T11:30:00.000Z",
        "bytes": 41943040,
        "bytes_up": 2097152,
        "bytes_down": 39845888,
        "mbps": 0.37,
        "connections_per_sec": 0.62,
        "concurrent": 12
      },
      {
        "t": "2026-10-13T11:45:00.000Z",
        "bytes": 52428800,
        "bytes_up": 3145728,
        "bytes_down": 49283072,
        "mbps": 0.47,
        "connections_per_sec": 0.71,
        "concurrent": 15
      }
    ]
  }
}
```

### Top destinations

`GET /api/v1/plans/{plan_id}/destinations`

Returns the sites a plan connected to most over a time range, with traffic, connections and success rate per host (top 100).

Permission: `usage`

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `plan_id` | path | required | The plan ID, as returned in plan_id by List plans. |
| `range` | query |  | Time window: 1h, 24h, 7d, 30d. Defaults to 24h. |

**Request**

```bash
curl "https://www.flashproxy.com/api/v1/plans/YOUR_PLAN_ID/destinations?range=24h" \
  -H "Authorization: Bearer fpk_live_YOUR_KEY"
```

**Response · 200**

```json
{
  "success": true,
  "data": {
    "plan_id": "YOUR_PLAN_ID",
    "range": "24h",
    "generated_at": "2026-10-13T12:00:00.000Z",
    "destinations": [
      {
        "host": "example.com",
        "bytes_down": 1288490188.8,
        "bytes_up": 107374182.4,
        "connections": 18240,
        "failed": 96,
        "success_pct": 99.5
      }
    ]
  }
}
```

### Error breakdown

`GET /api/v1/plans/{plan_id}/errors`

Returns what went wrong over a time range, grouped by category, each with a readable label and a hint on what to check.

Permission: `usage`

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `plan_id` | path | required | The plan ID, as returned in plan_id by List plans. |
| `range` | query |  | Time window: 1h, 24h, 7d, 30d. Defaults to 24h. |

**Request**

```bash
curl "https://www.flashproxy.com/api/v1/plans/YOUR_PLAN_ID/errors?range=24h" \
  -H "Authorization: Bearer fpk_live_YOUR_KEY"
```

**Response · 200**

```json
{
  "success": true,
  "data": {
    "plan_id": "YOUR_PLAN_ID",
    "range": "24h",
    "generated_at": "2026-10-13T12:00:00.000Z",
    "errors": [
      {
        "category": "timeout",
        "label": "Connection timed out",
        "hint": "The destination did not answer in time. Usually a slow or overloaded target site; retry with a longer client timeout, and check whether one destination dominates.",
        "count": 214
      }
    ]
  }
}
```,## Proxies

### Plan locations

`GET /api/v1/plans/{plan_id}/locations`

Returns the countries a plan can target with the country field when you generate proxies. When any_country is true, any two-letter code is accepted and there is no list.

Permission: `usage`

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `plan_id` | path | required | The plan ID, as returned in plan_id by List plans. |

**Request**

```bash
curl "https://www.flashproxy.com/api/v1/plans/YOUR_PLAN_ID/locations" \
  -H "Authorization: Bearer fpk_live_YOUR_KEY"
```

**Response · 200**

```json
{
  "success": true,
  "data": {
    "plan_id": "YOUR_PLAN_ID",
    "product": "ipv6-datacenter",
    "any_country": false,
    "countries": [
      {
        "code": "CA",
        "name": "Canada"
      },
      {
        "code": "FR",
        "name": "France"
      },
      {
        "code": "US",
        "name": "United States"
      }
    ]
  }
}
```

### Generate proxies

`POST /api/v1/plans/{plan_id}/proxies`

Builds ready-to-use proxy lines for one of your active plans, the same way the dashboard generator does.

Permission: `proxies`

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `plan_id` | path | required | The plan ID, as returned in plan_id by List plans. |
| `count` | body |  | How many lines to return, 1 to 1000. Defaults to 10. |
| `country` | body |  | Two-letter country code to target, for example US. Leave it out for any country. |
| `session` | body |  | rotating for a new IP on every request (default), or sticky to keep the same IP. |
| `sticky_minutes` | body |  | How long a sticky IP is kept, 1 to 1000 minutes. Residential and mobile cap it at 120. Defaults to 30. |
| `protocol` | body |  | http (default) or socks5. |
| `format` | body |  | hostport for host:port:user:pass (default), or url for scheme://user:pass@host:port. |

**Request**

```bash
curl -X POST "https://www.flashproxy.com/api/v1/plans/YOUR_PLAN_ID/proxies" \
  -H "Authorization: Bearer fpk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"count":2,"country":"US","session":"sticky","sticky_minutes":30,"protocol":"http","format":"hostport"}'
```

**Response · 200**

```json
{
  "success": true,
  "data": {
    "plan_id": "YOUR_PLAN_ID",
    "count": 2,
    "protocol": "http",
    "format": "hostport",
    "proxies": [
      "adam.flashproxy.io:8080:USERNAME-country-US-session-k3x9q2ma-time-30:PASSWORD",
      "adam.flashproxy.io:8080:USERNAME-country-US-session-p7d1v8tc-time-30:PASSWORD"
    ]
  }
}
```

### Fixed IP list

`GET /api/v1/plans/{plan_id}/ips`

Returns the plan's fixed IPs with its login: live exit IPs for Datacenter plans, or the leased IPs for Dedicated ISP plans. Rotating-gateway plans use Generate proxies instead.

Permission: `proxies`

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `plan_id` | path | required | The plan ID, as returned in plan_id by List plans. |
| `protocol` | query |  | http (default) or socks5. Dedicated ISP v2 plans support http only. |
| `format` | query |  | hostport for host:port:user:pass (default), or url for scheme://user:pass@host:port. |
| `limit` | query |  | How many IPs to return, up to 10000. Defaults to 1000. total always shows the full count. |

**Request**

```bash
curl "https://www.flashproxy.com/api/v1/plans/YOUR_PLAN_ID/ips?protocol=http&limit=2" \
  -H "Authorization: Bearer fpk_live_YOUR_KEY"
```

**Response · 200**

```json
{
  "success": true,
  "data": {
    "plan_id": "YOUR_PLAN_ID",
    "product": "datacenter",
    "source": "live",
    "protocol": "http",
    "format": "hostport",
    "total": 2048,
    "count": 2,
    "proxies": [
      "203.0.113.10:777:USERNAME:PASSWORD",
      "203.0.113.11:777:USERNAME:PASSWORD"
    ]
  }
}
```,## Extensions

### Quote an extension

`GET /api/v1/plans/{plan_id}/extend/quote`

Returns what an extension would cost, running the same checks as Extend a plan, without buying anything.

Permission: `usage`

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `plan_id` | path | required | The plan ID, as returned in plan_id by List plans. |
| `gb` | query |  | GB to quote, for plans billed by data. |
| `days` | query |  | Days to quote, for plans billed by time. Send gb or days, not both. |

**Request**

```bash
curl "https://www.flashproxy.com/api/v1/plans/YOUR_PLAN_ID/extend/quote?gb=10" \
  -H "Authorization: Bearer fpk_live_YOUR_KEY"
```

**Response · 200**

```json
{
  "success": true,
  "data": {
    "plan_id": "YOUR_PLAN_ID",
    "added": {
      "gb": 10
    },
    "price_usd": 35,
    "currency": "USD"
  }
}
```

### Extend a plan

`POST /api/v1/plans/{plan_id}/extend`

Adds data (gb) or time (days) to one of your plans and pays from your account balance, at the same price as the dashboard.

Permission: `extend`

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `plan_id` | path | required | The plan ID, as returned in plan_id by List plans. |
| `Idempotency-Key` | header | required | A unique string for this extension. See Idempotency below. |
| `gb` | body |  | GB to add, for plans billed by data. A whole number from 1 to 2,000,000. |
| `days` | body |  | Days to add, for plans billed by time: 1 to 365, or 1, 7, 30, 60 for Premium Unlimited Residential. Send gb or days, not both. |

**Request**

```bash
curl -X POST "https://www.flashproxy.com/api/v1/plans/YOUR_PLAN_ID/extend" \
  -H "Authorization: Bearer fpk_live_YOUR_KEY" \
  -H "Idempotency-Key: extend-2026-10-13-001" \
  -H "Content-Type: application/json" \
  -d '{"gb":10}'
```

**Response · 200**

```json
{
  "success": true,
  "data": {
    "plan_id": "YOUR_PLAN_ID",
    "charged_usd": 35,
    "added": {
      "gb": 10
    },
    "plan": {
      "status": "active",
      "expires_at": "2027-04-11T12:00:00.000Z",
      "max_bytes": 21474836480
    },
    "replayed": false
  }
}
```,## Products & prices

### Products and prices

`GET /api/v1/products`

Returns every product with its per-GB tiers (the whole amount is billed at the rate of the tier it falls in) and its speed-and-days prices. Use Quote an extension for the exact price of a specific plan.

Permission: `usage`

**Request**

```bash
curl "https://www.flashproxy.com/api/v1/products" \
  -H "Authorization: Bearer fpk_live_YOUR_KEY"
```

**Response · 200**

```json
{
  "success": true,
  "data": {
    "products": [
      {
        "product": "datacenter",
        "name": "Datacenter Proxies",
        "billed_by": [
          "data",
          "time"
        ],
        "data_pricing": [
          {
            "up_to_gb": 1,
            "per_gb_usd": 0.7
          },
          {
            "up_to_gb": 5,
            "per_gb_usd": 0.65
          }
        ],
        "time_pricing": [
          {
            "mbps": 10,
            "days": 1,
            "price_usd": 1
          },
          {
            "mbps": 10,
            "days": 30,
            "price_usd": 18
          }
        ]
      }
    ],
    "currency": "USD"
  }
}
```

## Idempotency

Extending a plan spends your balance, so every extend call needs an `Idempotency-Key` header.

- Use a new key for every extension you mean to buy: 8 to 128 letters, digits, `-` or `_`.
- If a call times out or returns a 5xx error, send it again with the same key. You are charged at most once, and a finished extension comes back with `replayed: true`.
- The same key with a different plan or amount returns `409 IDEMPOTENCY_KEY_REUSED`.
- While the first call is still running, a second call with the same key returns `409 REQUEST_IN_PROGRESS`.

## Response fields

Each plan in a usage response carries the same record.

| Field | Meaning |
| --- | --- |
| `usage.*` | `bytes_used`, `max_bytes`, `remaining_bytes` and `percentage_used`. `max_bytes` and `remaining_bytes` are null on plans without a data cap. `bytes_used` is null on Unlimited Residential, which is billed by time and speed. |
| `throughput.current_mbps` | The latest speed measurement: the last complete minute for most products, 0 when there was no recent traffic. |
| `throughput.avg_mbps_5m / peak_mbps_1h` | The 5-minute average and the 1-hour peak speed. |
| `throughput.limit_mbps` | Your plan's speed limit. `utilization_pct` is the current speed divided by this limit. |
| `throughput.sampled_at` | When the latest measurement was taken. `data_delay_seconds` tells you how old it is. |

**Values of `throughput_status`**

| Value | Meaning |
| --- | --- |
| `ok` | throughput is filled in. |
| `pending` | Speed is still being collected. For Unlimited Residential the first reading can take up to 10 minutes; keep polling as usual. |
| `unavailable` | Speed is temporarily unavailable. Retry later. |
| `not_supported` | This product has no speed metrics yet. The usage counters still work. |

## Limits

- 60 requests a minute per key
- All keys of one account share a limit of 120 requests a minute.
- Over the limit you get `429` with a `Retry-After: 60` header.
- Extend calls also count toward the limit of 6 balance purchases a minute per account, shared with the dashboard.
- Speed is measured per minute, so polling every 15 to 30 seconds is plenty.
- Usage answers can be up to 15 seconds old and product prices up to 5 minutes old.

## Errors

Errors share one shape: success is false and error holds a code and a readable message.

```json
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}
```

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `INVALID_REQUEST` | The body or a parameter is invalid. The message says which. |
| 400 | `IDEMPOTENCY_KEY_REQUIRED` | An extend call without a valid Idempotency-Key header. |
| 400 | `PAYMENT_REFUSED` | The balance payment was refused. Contact support. |
| 401 | `UNAUTHORIZED` | Missing, invalid or revoked key. |
| 402 | `INSUFFICIENT_BALANCE` | Your balance is too low for this extension. Top up and retry. |
| 403 | `FORBIDDEN` | The key doesn't have the permission this endpoint needs. |
| 404 | `NOT_FOUND` | No such plan on your account. |
| 409 | `PLAN_NOT_ACTIVE` | Proxies can only be generated for an active plan. |
| 409 | `PLAN_NOT_READY` | The plan has no proxy credentials yet. Try again shortly. |
| 409 | `IDEMPOTENCY_KEY_REUSED` | This Idempotency-Key was already used for a different extension. |
| 409 | `REQUEST_IN_PROGRESS` | An extension with this Idempotency-Key is still running. Retry in a moment. |
| 409 | `PRICE_MISMATCH` | The price changed while processing. Retry with a new Idempotency-Key. |
| 422 | `EXTENSION_NOT_SUPPORTED` | This plan can't be extended through the API. Extend it in the dashboard. |
| 422 | `PROXIES_NOT_SUPPORTED` | Dedicated plans have a fixed IP list. Download it from the dashboard. |
| 422 | `USAGE_HISTORY_NOT_SUPPORTED` | This product has no usage history. Use the usage endpoints for its counters. |
| 422 | `IPS_NOT_SUPPORTED` | This plan uses a rotating gateway, not a fixed IP list. Use Generate proxies. |
| 422 | `CUSTOM_PLAN_EXTEND_VIA_SUPPORT` | Custom plans are extended by support only. |
| 429 | `RATE_LIMITED` | Too many requests. Wait for Retry-After, then retry. |
| 500 | `INTERNAL_ERROR` | Temporary error. Try again. |
| 502 | `EXTENSION_FAILED` | The extension didn't complete. Retry with the same Idempotency-Key only if the message says nothing was charged; otherwise contact support. |
| 503 | `IPS_UNAVAILABLE` | The IP list could not be loaded right now. Retry in a minute. |