Developer API

API Documentation

Check proxies, read job results, and pull verified proxy lists programmatically. All endpoints are authenticated with an API key and rate limited per account tier.

Getting started

1. Create a key

Generate an API key at Account → API Keys. The full key is shown only once.

2. Call the API

Send the key in the Authorization header on every request.

3. Go premium

Premium accounts get higher rate limits and access to the premium proxy pool.

base url

https://your-domain/api/v1

Authentication

Every request must include your API key as a Bearer token. Keys start with pk_live_ and are tied to your account's role and permissions.

Authorization: Bearer pk_live_YOUR_KEY

Treat keys like passwords: never commit them, never expose them in client-side code. Revoking a key at Account → API Keys blocks it immediately.

Endpoints

Holding an API key does not unlock every endpoint. Each one is gated by a permission that an admin assigns per role, so your key reaches only the subset your plan allows. The badges below reflect your own access.

GET/api/proxies

List verified public proxies with filters and pagination.

api.proxies.readapi_read

Parameter	Type	Description
protocol	string	http, https, socks4 or socks5
country	string	ISO country code, e.g. US
anonymity	string	transparent, anonymous or elite
fresh_minutes	int	Only proxies checked within N minutes; 1–1440 (default 1440)
max_latency_ms	int	Maximum connect latency in ms
min_uptime	int	Minimum uptime as a percentage 0–100 (e.g. 90 = at least 90%; 100 = perfect)
proxy	string	Substring match on the proxy (ip:port)
sort	string	checked_desc (default), checked_asc, latency_asc, latency_desc, uptime_desc, uptime_asc
page / limit	int	Pagination; limit 1–200 (default 50)

curl

curl "https://your-domain/api/v1/api/proxies?protocol=socks5&country=US&limit=20" \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

response

{
  "page": 1,
  "limit": 20,
  "total": 1342,
  "refreshed_at": "2026-06-10T08:00:00Z",
  "items": [
    {
      "proxy_norm": "1.2.3.4:1080",
      "status": "live",
      "protocol": "socks5",
      "connect_ms": 230,
      "ttfb_ms": 510,
      "exit_ip": "1.2.3.4",
      "country": "US",
      "city": "Ashburn",
      "asn": "AS14061",
      "anonymity": "elite",
      "uptime_score": 0.98,
      "checked_at": "2026-06-10T07:59:12Z"
    }
  ]
}

GET/api/proxies/export

Export the filtered proxy list as a file.

api.proxies.readapi_export

Parameter	Type	Description
format	string	txt (default), csv or json
max_rows	int	Cap on exported rows (default and maximum 300)
…filters	—	Same filters as /api/proxies (results are always newest-first)

curl

curl -o proxies.txt "https://your-domain/api/v1/api/proxies/export?format=txt&protocol=http" \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

POST/api/check

Submit your own proxies for checking. Returns a job you can poll. One proxy per line; ip:port or ip:port:user:pass. Request body is limited to 2 MB.

api.check.writeapi_check

Parameter	Type	Description
proxies_text	string	Newline-separated proxies (required)
include_anonymity	bool	Also detect anonymity level (slower)

curl

curl -X POST "https://your-domain/api/v1/api/check" \
  -H "Authorization: Bearer pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"proxies_text": "1.2.3.4:1080\n5.6.7.8:8080"}'

response

// 201 Created
{ "job_id": "9f1c…" }
// Poll GET /api/jobs/{job_id} for status (queued → running → done).

GET/api/jobs/{jobId}

Read job status and progress. status is one of queued, running, done or failed. started_at / finished_at appear once the job reaches those stages.

api.jobs.readapi_read

response

{
  "job_id": "9f1c…",
  "status": "done",
  "total": 2,
  "done": 2,
  "created_at": "2026-06-10T08:00:00Z",
  "started_at": "2026-06-10T08:00:02Z",
  "finished_at": "2026-06-10T08:00:21Z"
}

GET/api/jobs/{jobId}/items

Read per-proxy results of a job. Each item status is one of live, dead, timeout, blocked, auth_failed, handshake_failed or unknown.

api.jobs.readapi_read

Parameter	Type	Description
status	string	Filter by result status, e.g. live or dead
protocol	string	http, https, socks4 or socks5
country	string	ISO country code, e.g. US
max_latency_ms	int	Maximum connect latency in ms
sort	string	input, latency (= latency_desc), latency_asc, status; defaults to input order
page / limit	int	Pagination; limit 1–200 (default 50)

response

{
  "page": 1,
  "limit": 50,
  "total": 2,
  "items": [
    {
      "input_index": 0,
      "proxy_norm": "1.2.3.4:1080",
      "status": "live",
      "protocol": "socks5",
      "connect_ms": 230,
      "ttfb_ms": 510,
      "exit_ip": "1.2.3.4",
      "country": "US",
      "city": "Ashburn",
      "asn": "AS14061",
      "anonymity": "elite",
      "checked_at": "2026-06-10T08:00:20Z"
    }
  ]
}

GET/api/jobs/{jobId}/export

Export job results as a file. csv and json include any proxy credentials (username / password) that were submitted; txt is one proxy per line.

api.jobs.readapi_export

Parameter	Type	Description
format	string	txt (default), csv or json
…filters	—	Same status / protocol / country / max_latency_ms / sort filters as the items endpoint

curl

curl -o results.csv "https://your-domain/api/v1/api/jobs/<JOB_ID>/export?format=csv" \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

GET/api/premium/proxies

Read the premium proxy pool (Tier A & B only). Returns richer per-proxy quality data than the public pool — reliability, a composite score, latency, tier and ASN. Requires BOTH the api.premium.proxies.read permission AND an active premium subscription; missing either returns 403.

api.premium.proxies.readapi_read

Parameter	Type	Description
protocol	string	http, https, socks4 or socks5
country	string	ISO country code, e.g. US
tier	string	A (Hot — freshest, most reliable) or B (Warm). Omit to return both
search	string	Substring match on the proxy or host
sort_by	string	score (default), reliability, latency or last_check_at
sort_order	string	asc or desc (latency defaults to asc, the rest to desc)
limit	int	Page size 1–200 (default 50)
offset	int	Rows to skip (default 0). Premium paginates by offset, not page

curl

curl "https://your-domain/api/v1/api/premium/proxies?tier=A&protocol=socks5&sort_by=reliability&limit=20" \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

response

{
  "total": 1342,
  "limit": 20,
  "offset": 0,
  "protocol_counts": { "http": 800, "socks5": 542 },
  "proxies": [
    {
      "id": "12345",
      "proxy_norm": "socks5://1.2.3.4:1080",
      "host": "1.2.3.4",
      "port": 1080,
      "protocol": "socks5",
      "country": "US",
      "city": "Ashburn",
      "anonymity": "elite",
      "latency_ms": 230.5,
      "reliability": 0.9871,
      "score": 642.7,
      "tier": "A",
      "asn": "AS14061",
      "last_check_at": "2026-06-19T07:59:12Z"
    }
  ]
}

Rate limits

Limits are applied per API key. When a limit is exceeded the API returns 429 Too Many Requests — back off and retry after the window resets. Default limits:

Category	Applies to	Free	Premium
api_read	Proxy lists, job status & results	60 / min	300 / min
api_check	Submitting check jobs	20 / hour	200 / hour
api_export	File exports	10 / hour	60 / hour

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers so you can pace requests. A 429 adds a Retry-After header and a retry_at field in the body.

Errors

Errors are returned as JSON: {"error": "message"}

Status	Meaning
400	Invalid request — bad parameters or no valid proxies in proxies_text
401	Missing or invalid API key
403	Key is valid but your role lacks the required permission, account is not active, or premium is required
429	Rate limit exceeded for this category — body includes retry_at; honor the Retry-After header
5xx	Server error — safe to retry with backoff

Code examples

Full check-and-poll workflow: submit proxies, wait for the job, read results.

bash

# 1. Submit proxies for checking
curl -X POST "https://your-domain/api/v1/api/check" \
  -H "Authorization: Bearer pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"proxies_text": "1.2.3.4:1080\n5.6.7.8:8080"}'

# -> {"job_id":"<JOB_ID>", ...}

# 2. Poll job status until "done"
curl "https://your-domain/api/v1/api/jobs/<JOB_ID>" \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

# 3. Fetch results
curl "https://your-domain/api/v1/api/jobs/<JOB_ID>/items" \
  -H "Authorization: Bearer pk_live_YOUR_KEY"