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

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 (default 1440)
max_latency_ms	int	Maximum connect latency
min_uptime	float	Minimum uptime score (0–1)
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",
      "protocol": "socks5",
      "country": "US",
      "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
…filters	—	Same filters as /api/proxies

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

{ "job_id": "9f1c…", "status": "queued", "total": 2 }

GET/api/jobs/{jobId}

Read job status and progress.

api.jobs.readapi_read

response

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

GET/api/jobs/{jobId}/items

Read per-proxy results of a job (paginated with page / limit).

api.jobs.readapi_read

response

{
  "page": 1,
  "limit": 50,
  "total": 2,
  "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"
    }
  ]
}

GET/api/jobs/{jobId}/export

Export job results as a file (format: txt, csv or json).

api.jobs.readapi_export

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. Requires an active premium subscription in addition to the permission.

api.premium.proxies.readapi_read

curl

curl "https://your-domain/api/v1/api/premium/proxies" \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

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

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 — retry later
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 "completed"
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"