Proxy API Documentation: Retrieve Proxy Lists via REST API

What can I do with the API?

Use APIs when programs need fresh proxy lists - fetching at crawler startup or auto-updating after plan changes. API and dashboard downloads contain identical data.

The API is read-only. It supports balance checks, plan lists, and proxy listings. Purchases are made in the dashboard. Responses use UTF-8 encoding and ISO 8601 UTC dates.

How do I create and send API keys?

Generate API keys in the dashboard's API key section. Keys start with spx_, are 44 characters long, and are only shown once upon creation. Servers store only key fingerprints (hashes) - if lost, create a new key; new keys immediately invalidate previous ones.

Include your Bearer API key in the Authorization header for each request. We don't accept keys in URL queries. Missing/invalid keys return 401 unauthorized.

curl -H "Authorization: Bearer spx_your_api_key" https://socks5proxy.io/api/v1/account

Check balance & account: GET /account

Returns the account code, balance, number of active plans, and number of proxies. The balance is displayed up to two decimal places (USD).

curl -H "Authorization: Bearer spx_your_api_key" https://socks5proxy.io/api/v1/account

{
  "code": "S5-7KQ2-M8PX-4HDA",
  "balance": "125.40",
  "currency": "USD",
  "active_plans": 2,
  "proxies": 125,
  "created_at": "2026-10-22T08:15:02.114Z"
}

List pricing plans: GET /plans

Returns your purchased plans sorted by most recent. Status can be active (in use), expired (period ended), or canceled (terminated). The ID (starting with P-) is your plan code and can be used as the 'plan' value in /proxies.

{
  "plans": [
    {
      "id": "P-8WQ4C-NM2KT",
      "product": "dc-private",
      "product_name": "Private Datacenter Proxy",
      "ips": 100,
      "months": 1,
      "country": "us",
      "status": "active",
      "amount": "49.40",
      "created_at": "2026-10-22T08:20:11.002Z",
      "expires_at": "2026-11-22T08:20:11.002Z"
    }
  ]
}

Proxy List Query: GET /proxies

Returns the proxies of the active plan in JSON format. Each proxy includes the address, HTTP port, SOCKS5 port, username, password, country, city, plan code, and expiration time.

Filter by country (2-letter code, e.g., us) and plan (pricing code). The protocol field shows in responses, with both ports included in JSON.

curl -H "Authorization: Bearer spx_your_api_key" \
  "https://socks5proxy.io/api/v1/proxies?country=us&protocol=socks5"

{
  "count": 1,
  "protocol": "socks5",
  "proxies": [
    {
      "host": "198.51.100.23",
      "http_port": 8231,
      "socks5_port": 1080,
      "username": "spx_k2m8qa",
      "password": "q7rbx2wd9n",
      "country": "us",
      "city": "New York",
      "plan": "P-8WQ4C-NM2KT",
      "product": "dc-private",
      "product_name": "Private Datacenter Proxy",
      "expires_at": "2026-11-22T08:20:11.002Z"
    }
  ]
}

Download List: GET /proxies/download

For program readability, return one proxy per line. Include SOCKS5 ports for protocol=socks5 and HTTP ports for protocol=http. format=url prefixes addresses with socks5:// or http:// based on the protocol.

Servers with IP authorization enabled accept ip:port format without usernames. CSV files include column headers and both ports.

curl -H "Authorization: Bearer spx_your_api_key" \
  "https://socks5proxy.io/api/v1/proxies/download?format=url&protocol=socks5" -o proxies.txt

Code examples: Python, Node.js, PHP

Below example sends requests using the first proxy from the list. Python requires requests[socks] for SOCKS5 support. Using socks5h routes DNS lookups through the proxy.

import requests

API = "https://socks5proxy.io/api/v1"
H = {"Authorization": "Bearer spx_your_api_key"}

proxies = requests.get(f"{API}/proxies", headers=H, params={"country": "us"}).json()["proxies"]
p = proxies[0]
url = f"socks5h://{p['username']}:{p['password']}@{p['host']}:{p['socks5_port']}"
r = requests.get("https://api.ipify.org?format=json", proxies={"http": url, "https": url}, timeout=30)
print(r.json())

import { ProxyAgent, fetch } from "undici";

const API = "https://socks5proxy.io/api/v1";
const H = { Authorization: "Bearer spx_your_api_key" };

const { proxies } = await (await fetch(`${API}/proxies?country=us`, { headers: H })).json();
const p = proxies[0];
const agent = new ProxyAgent(`http://${p.username}:${p.password}@${p.host}:${p.http_port}`);
const r = await fetch("https://api.ipify.org?format=json", { dispatcher: agent });
console.log(await r.json());

<?php
$ch = curl_init("https://socks5proxy.io/api/v1/proxies/download?format=ip:port:user:pass&protocol=http");
curl_setopt_array($ch, [
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spx_your_api_key"],
  CURLOPT_RETURNTRANSFER => true,
]);
$lines = explode("\n", trim(curl_exec($ch)));
[$host, $port, $user, $pass] = explode(":", $lines[0]);
echo "$host:$port\n";

Error codes and call limits

Errors are returned with HTTP status codes in the format { "error": { "code", "message" } }. Each key can be called up to 300 times per minute; exceeding this limit results in a 429 response for 1 minute. Since lists only change upon purchase or expiration, we recommend fetching them once every few minutes and reusing them within your program.

API calls are free. Your balance is only deducted when purchasing plans in the dashboard.