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

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

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

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

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

Response · 200

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

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

Response · 200

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

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

Response · 200

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

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

Response · 200

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

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

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

Response · 200

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

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

Response · 200

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

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

Response · 200

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

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

Response · 200

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

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

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

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

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

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

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

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

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

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

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