DEVELOPER DOCUMENTATION
Use an expiring API key to retrieve application-verified public free proxy records. Your subscription pays for collection, verification, and API delivery; the API returns proxy metadata, not fetched page content or an open proxy relay.
GET /api/v1/proxies
Returns a snapshot of verified proxy records that are still within their validity window.
protocol=http: supports http, socks4, socks5; https is an HTTP CONNECT alias.limit=20: defaults to up to 20 records; maximum 10000 per request.Country and anonymity metadata are not yet populated; avoid filtering by those fields.
GET /api/v1/proxy
Returns one matching record using the same filters. If no record matches, the API returns 404.
Both endpoints require X-API-Key and also accept Authorization: Bearer ….
curl -H "X-API-Key: fp_live_..." \
"https://proxylistapi.xyz/api/v1/proxies?protocol=http&limit=20"RESPONSE CONTRACT
List responses include snapshot and verification metadata. Rotate a proxy when a real request fails and check the expiry fields.
snapshotVersion: version of the filtered result, useful for caching.generatedAt: time when the snapshot was generated.validUntil: earliest expiry among the returned records.count, proxies: record count and data array.protocol, ip, port: connection details.verified, validated_at, expires_at: verification state and timestamps.validation_target, validation_latency_ms: validation evidence.source, sources, capabilities: source and capability metadata.ACCESS LIFECYCLE
Successful renewal extends access without changing your key. Cancel automatic renewal to keep access until the paid period ends. Failed payments or an inactive subscription return 401. Access is checked against the subscription item's current_period_end.
Set FREEPROXY_API_KEY in your server environment. This standard-library example fetches connection records; configure your HTTP client's proxy setting separately to use one.
import json, os, urllib.request
request = urllib.request.Request(
"https://proxylistapi.xyz/api/v1/proxies?protocol=http&limit=20",
headers={"X-API-Key": os.environ["FREEPROXY_API_KEY"]},
)
with urllib.request.urlopen(request, timeout=15) as response:
snapshot = json.load(response)
for proxy in snapshot["proxies"]:
print(proxy["proxy"], proxy["expires_at"])Each API key is limited to 3 requests per second with a burst of 3; each client IP is limited to 1 request per second with a burst of 1. Shared network exits share the IP allowance. Request only the records you need; the maximum is 10000 per call.
| Response | What to do |
|---|---|
| 200, count: 0 | No matching list records. Remove filters or try later. |
| 304 | Your ETag matches. Reuse your cached snapshot, respecting each record's expires_at. |
| 401 | Check the key and subscription payment status. |
| 404 on /proxy | No matching proxy. Retry later rather than looping immediately. |
| 429 | Wait at least the Retry-After header duration; use exponential backoff and jitter. |
| 5xx | Temporary server failure. Retry with backoff. |
A published endpoint passed an application-level reachability check and has not reached its expires_at timestamp. validation_target identifies the validation target, validated_at records the check time, and validation_latency_ms measures that check's duration. It is not a download-speed measurement or a guarantee that a different target will accept the proxy.
The https filter selects HTTP CONNECT proxies; it does not mean TLS to the proxy itself. SOCKS4 and SOCKS5 require a client that supports that protocol. Keep a small local list, discard expired endpoints, and select another on a connection failure.
Save the list response ETag and send it as If-None-Match on subsequent requests with the same filters. Auth and expiry are checked before a 304 response. Keep the API key in the request header, never the URL.
No signup; claim it from the success page after payment.