Developer API

API Documentation

Check proxies, read job results, and pull verified proxy lists programmatically. The API-key endpoints are rate limited per account tier; the free proxy list can also be read without a key, limited per IP address.

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. Request access

Programmatic API access and curated pools are free on request: email [email protected].

base url

https://proxycheck.app/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. ttfb_ms is the latency: ms from sending the request through the proxy to the first byte of the response. connect_ms is the same number as ttfb_ms unless tunnel timing is enabled for the check; then it is only the part until the proxy has opened the tunnel.

api.proxies.readapi_read

Parameter	Type	Description
protocol	string	http, https, socks4 or socks5, any case; any other value returns 400
country	string	Two-letter ISO code, e.g. US, any case; any other value returns 400
anonymity	string	elite for all protocols: HTTP/HTTPS are checked through an HTTPS (CONNECT) tunnel, where a proxy cannot add headers
fresh_minutes	int	Only proxies checked within N minutes; 1–1440 (default 1440, other values use 1440)
max_latency_ms	int	Maximum latency (ttfb_ms) 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://proxycheck.app/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": "socks5://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. txt lists one proxy URL per line, each once; in csv the proxy column is the URL to connect to. Proxies labelled https are HTTP proxies that tunnel HTTPS via CONNECT, so both formats write them as http://host:port. json keeps proxy_norm.

api.proxies.readapi_export

Parameter	Type	Description
format	string	txt (default), csv or json
max_rows	int	Rows to export, 1–500 (default 500; other values use 500)
…filters	—	Same filters and rules as /api/proxies (results are always newest-first); fresh_minutes is clamped to 1–1440 as on the list

curl

curl -o proxies.txt "https://proxycheck.app/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, ip:port:user:pass or user:pass@ip:port, optionally prefixed with http://, https://, socks4:// or socks5://. IPv6 goes in brackets, e.g. socks5://[2606:4700:4700::1111]:1080. Private and reserved addresses, and other prefixes such as socks5h://, are rejected. Request body is limited to 2 MB.

api.check.writeapi_check

Parameter	Type	Description
proxies_text	string	Newline-separated proxies (required)
include_anonymity	bool	Accepted for compatibility; anonymity is not measured
default_protocol	string	http (default), https, socks4 or socks5, for lines without a protocol:// prefix; other values return 400

curl

curl -X POST "https://proxycheck.app/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 latency (ttfb_ms) 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": "socks5://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://proxycheck.app/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 — and platforms: the last verdict per platform (Google Search, YouTube, Facebook, Instagram, Threads, TikTok), checked from our server through the proxy with a current Chrome fingerprint. status is ok (normal anonymous page), blocked (bot gate, captcha, /sorry, challenge, 403/429; reason says which), login_wall, region_unavailable, unreachable, or stale (older than 2 × its check interval: Google hourly, YouTube every 2 h, the others every 6 h); a platform not checked yet has no key, and a proxy with no verdict yet has no platforms field. While the check is on the response also has platform_filter: true. 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, in any case. Any other value returns 400
country	string	Two-letter ISO code in any case (us matches US). Any other value returns 400
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
platform	string	Comma list of google, youtube, facebook, instagram, threads, tiktok: only proxies with a fresh ok verdict on every listed platform. protocol_counts apply it too. An unknown name returns 400
facets	string	1 or true adds facets: counts per protocol, tier and country under every other filter in the request (the facet’s own filter is ignored; country sorted by count, proxies without a two-letter country code left out), and per platform the proxies that match every filter and have a fresh ok on it (only while platform_filter is true). Every key is present, zero included; if the counts cannot be read, facets is left out and the list is still returned

curl

curl "https://proxycheck.app/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 },
  "platform_filter": true,
  "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",
      "platforms": {
        "google": { "status": "blocked", "reason": "sorry", "checked_at": "2026-06-19T07:31:02Z" },
        "youtube": { "status": "ok", "checked_at": "2026-06-19T06:58:40Z" },
        "tiktok": { "status": "ok", "checked_at": "2026-06-19T03:12:09Z" }
      }
    }
  ]
}

GET/api/stable-proxies

List premium proxies by uptime over the last 1–7 days (Premium and Admin only; the permission follows an active Premium on any account, and an admin can grant it per user). Uptime is the share of complete UTC hours in the window whose last check passed; an hour without a check counts as down, and the current hour is not counted. A proxy is listed when its history covers the whole window, its uptime reaches min_uptime over every window ending now (the last day, the last 2 days and so on up to the whole window, so a bad recent day is never hidden by older good days and the N-day list is a subset of the shorter ones), it is tier A or B and not quarantined, its host:port has no TLS-interception mark and, with live_now=true, its newest hour (at most 2 hours old) ended alive. checks, live_checks and live_ratio are informational. proxy is the URL to connect to: https-labelled proxies are written as http://, and user:pass@ is kept. Rows with the same URL (the http and https labels of one host:port) are merged into the best one, and total counts the merged list; protocol filters the label before the merge. tier is 1 (A) or 2 (B). There is no public list: premium imports the public pool and rechecks it far more often; pool=public returns 400. Any other parameter value returns 400; responses are cached for 60 seconds. JSON counts as api_read, format=txt as api_export.

proxies.stable.readapi_read · txt: api_export

Parameter	Type	Description
pool	string	premium (optional; the only list)
days	int	Window in days, 1–7 (default 1)
min_uptime	number	Minimum uptime 0.5–1.0 (default 0.8), required of every window ending now, from the last day up to the whole window
protocol	string	http, https, socks4 or socks5 (the label), in any case
country	string	Two-letter ISO code in any case, e.g. US
live_now	bool	true (default) or false
sort	string	uptime (default), checks or latency
limit	int	Page size 1–500 (default 100)
offset	int	Rows to skip, 0–10000 (default 0)
format	string	json (default) or txt (one URL per line, same filters, order and page)
platform	string	While the platform check is on: comma list of google, youtube, facebook, instagram, threads, tiktok; only proxies with a fresh ok on every listed platform (before the merge, like protocol). Items then carry platforms (as on the premium list) and the response has platform_filter: true. An unknown name returns 400
facets	string	1 or true adds facets, each count equal to the total with that option picked: protocol (rows per label before the merge; protocol_all = the total with no protocol picked), country (URLs per country, two-letter codes only) and platform (URLs with a fresh ok); every protocol and platform key is present

curl

curl "https://proxycheck.app/api/v1/api/stable-proxies?days=3&min_uptime=0.9&protocol=socks5" \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

response

{
  "pool": "premium",
  "days": 3,
  "min_uptime": 0.9,
  "window_start": "2026-10-05T09:00:00Z",
  "window_end": "2026-10-08T09:00:00Z",
  "generated_at": "2026-10-08T09:41:12Z",
  "total": 123,
  "items": [
    {
      "proxy": "socks5://user:[email protected]:1080",
      "protocol": "socks5",
      "country": "US",
      "uptime": 0.9583,
      "hours_live": 69,
      "window_hours": 72,
      "live_ratio": 0.9295,
      "checks": 312,
      "live_checks": 290,
      "tracked_since": "2026-10-04T18:00:00Z",
      "last_checked_at": "2026-10-08T09:35:02Z",
      "latency_ms": 850,
      "live_now": true,
      "tier": 1
    }
  ]
}

Free list API (no key)

The free proxy list behind /free-proxies can be read by scripts without an API key or an account. These read-only endpoints use the same base URL and are limited per IP address, not per account.

Machine-readable spec for code generators and AI agents: /openapi.json (OpenAPI 3.1, these four endpoints only).

The list, stats and countries endpoints share one bucket of 120 requests per minute per IP; export allows 6 files per hour per IP, each of at most 500 proxies. Answers are cached on the server for 30 seconds (export: 60 seconds), and cached answers count toward the limit too.

Over the limit the API returns 429 with {"error": "rate limit exceeded", "retry_at": "…"}; wait until retry_at. For higher limits use the API-key endpoints above.

GET/public-proxies

List live public proxies: the same data, filters and response as /api/proxies. Only proxies that passed the server's quality gate are listed unless quality says otherwise.

no API key120 / min per IP (shared)

Parameter	Type	Description
protocol	string	http, https, socks4 or socks5, any case; any other value returns 400
country	string	Two-letter ISO code, e.g. US, any case (us = US); any other value returns 400
anonymity	string	elite for all protocols: HTTP/HTTPS are checked through an HTTPS (CONNECT) tunnel, where a proxy cannot add headers
fresh_minutes	int	Only proxies checked within N minutes; 1–1440 (default 1440, other values use 1440)
max_latency_ms	int	Maximum latency (ttfb_ms) in ms
min_uptime	int	Minimum uptime as a percentage 0–100 (100 = at least 99.5%)
proxy	string	Substring match on the proxy or its exit IP (not cached)
sort	string	checked_desc (default), checked_asc, latency_asc, latency_desc, uptime_desc, uptime_asc
page / limit	int	page ≥ 1 (pages past 1000 return page 1000); limit 1–200, default 50 (other values use 50)
quality	string	full (default), quick or none

curl

curl "https://proxycheck.app/api/v1/public-proxies?protocol=socks5&country=US&limit=20"

response

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

GET/public-proxies/stats

Count live proxies by protocol and anonymity. Takes the list filters, without sort or paging.

no API key120 / min per IP (shared)

Parameter	Type	Description
…filters	—	protocol, country, anonymity, fresh_minutes, max_latency_ms, min_uptime, proxy and quality, as on /public-proxies

curl

curl "https://proxycheck.app/api/v1/public-proxies/stats?country=US"

response

{
  "total": 371,
  "protocols": { "http": 30, "https": 12, "socks4": 17, "socks5": 312 },
  "anonymity": { "transparent": 0, "anonymous": 0, "elite": 371 }
}

GET/public-proxies/countries

Every country with at least one live proxy checked within fresh_minutes, largest first. code is the stored country, normally an upper-case ISO 3166-1 alpha-2 code; total counts its live proxies and protocols splits them per protocol (all four keys present, zero included). No quality gate is applied (every live proxy currently passes it); countries and stats are cached separately for 30 s, so their totals can differ by a few rows.

no API key120 / min per IP (shared)

Parameter	Type	Description
fresh_minutes	int	1–1440 (default 1440, other values use 1440)

curl

curl "https://proxycheck.app/api/v1/public-proxies/countries"

response

{
  "countries": [
    {
      "code": "US",
      "total": 370,
      "protocols": { "http": 30, "https": 12, "socks4": 17, "socks5": 311 }
    }
  ]
}

GET/public-proxies/export

Download the filtered list as a file, newest checks first (sort is ignored). txt lists one proxy URL per line, each once: https-labelled proxies are written as http://host:port, so 500 rows can give fewer lines. In csv the proxy column is the URL to connect to. json is an array of proxy objects (as in the list, without city).

no API key6 / hour per IP

Parameter	Type	Description
format	string	txt (default), csv or json; any other value returns 400
max_rows	int	Rows to export, 1–500 (default 500; other values use 500)
…filters	—	Same filters and rules as /public-proxies, except sort and paging; fresh_minutes is clamped to 1–1440 as on the list

curl

curl -o proxies.txt "https://proxycheck.app/api/v1/public-proxies/export?format=txt&protocol=socks5"

Rate limits

Limits are applied per account — every key you own shares the same bucket per category. 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 (incl. stable proxies as txt)	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://proxycheck.app/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://proxycheck.app/api/v1/api/jobs/<JOB_ID>" \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

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