Getting Started
ProxyNests provides a free, high-performance REST API for accessing our live proxy list. Proxies are scraped from 25+ sources, verified every 30 minutes with 100 concurrent workers, and scored 0–100 based on latency, reliability, throughput, freshness, and anonymity.
Public endpoints require no API key and are suitable for most use cases. Authenticated endpoints unlock advanced features like random proxy rotation, higher rate limits, and bulk access.
Base URL
How to Get an API Key
Create a free account at /dashboard to get your API key.
Keys start with px_ followed by a unique token.
Free-tier keys are issued immediately with no credit card required.
/public/* work without any key. Only /api/* routes require authentication.
Authentication
Authenticated requests must include your API key either as a request header or as a query parameter. The header method is preferred for security.
Method 1 — Request Header
X-API-Key: px_your_key_here
Method 2 — Query Parameter
?key=px_your_key_here
# Header method (recommended)
curl -H "X-API-Key: px_your_key_here" \
"https://api.proxynests.net/api/proxies/random?protocol=socks5"
# Query param method
curl "https://api.proxynests.net/api/proxies/random?protocol=socks5&key=px_your_key_here"
Tiers & Pricing
ProxyNests offers three access tiers. All tiers include full access to the public endpoints.
| Feature | Free | Pro | Enterprise |
|---|---|---|---|
| Public endpoints | ✓ | ✓ | ✓ |
| API key | ✓ | ✓ | ✓ |
| Random proxy endpoint | ✗ | ✓ | ✓ |
| Requests / minute | 60 | 500 | 5,000 |
| Max proxies per request | 300 | 500 | 1,000 |
| Bulk download (no limit) | ✓ | ✓ | ✓ |
| Priority support | ✗ | ✓ | ✓ |
| SLA uptime guarantee | ✗ | ✗ | ✓ |
| Price | Free | $9 / mo | Contact us |
Public Endpoints
These endpoints require no authentication. Rate limited to 60 requests/minute per IP on the free tier.
Returns a filtered, sorted list of alive proxies. Supports rich query parameters for protocol, anonymity, type, country, score, latency, and speed filtering.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| protocol | enum | all | socks5, socks4, http, https |
| country | string | all | ISO 3166-1 alpha-2 code, e.g. US, DE |
| anonymity | enum | all | elite, anonymous, transparent |
| proxy_type | enum | all | residential, datacenter, mobile, tor |
| sort_by | enum | score | score, latency, random |
| min_score | integer | 0 | Minimum score 0–100 |
| max_latency_ms | integer | none | Maximum latency in milliseconds |
| min_throughput_mbps | number | none | Minimum download speed in Mb/s |
| limit | integer | 50 | Results per page, max 300 |
| offset | integer | 0 | Pagination offset |
| format | enum | json | json or text (plain host:port per line) |
Response Example
{
"proxies": [
{
"host": "192.0.2.10",
"port": 1080,
"protocol": "socks5",
"country_code": "US",
"anonymity": "elite",
"proxy_type": "datacenter",
"score": 87,
"latency_ms": 312,
"download_mbps": 4.21,
"upload_mbps": 3.87,
"status": "alive",
"last_checked": "2026-07-26T10:30:00Z"
}
],
"total": 8423,
"limit": 50,
"offset": 0
}
Downloads the full proxy list matching your filters with no per-request row cap. Use this for importing into tools, scripts, or rotating proxy pools.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| format | enum | txt | txt, csv, json, formatted |
| protocol | enum | all | Filter by protocol |
| anonymity | enum | all | Filter by anonymity level |
| min_score | integer | 0 | Minimum score threshold |
Returns current counts broken down by protocol, anonymity, proxy type, plus average latency and speed metrics.
{
"alive": 9214,
"dead": 1783,
"total": 10997,
"by_protocol": { "socks5": 4102, "socks4": 2318, "http": 1934, "https": 860 },
"by_anonymity": { "elite": 5221, "anonymous": 2810, "transparent": 1183 },
"by_type": { "datacenter": 7040, "residential": 1620, "tor": 312, "mobile": 242 },
"avg_latency_ms": 748,
"avg_download_mbps": 2.14
}
Returns a list of countries with alive proxy counts, sorted by count descending. Useful for building geographic dashboards or selecting country-specific proxies.
Returns the top 10 proxies sorted by composite score. Updated each time the checker completes a full run.
Returns a breakdown of alive proxies by ISP or ASN name, sorted by count. Useful for understanding the diversity of the proxy pool.
Authenticated Endpoints
These endpoints require an API key sent via X-API-Key header or ?key= query parameter.
Returns exactly one random alive proxy matching your filters. Ideal for building rotating proxy pools where you need a fresh proxy on every request.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| protocol | enum | any | Filter by protocol |
| country | string | any | ISO 3166-1 alpha-2 code |
| min_score | integer | 0 | Minimum score threshold |
| anonymity | enum | any | Anonymity level filter |
Response Example
{
"host": "203.0.113.42",
"port": 4145,
"protocol": "socks5",
"country_code": "DE",
"anonymity": "elite",
"score": 91,
"latency_ms": 198,
"download_mbps": 6.73
}
Download Formats
The /public/proxies/download endpoint supports four output formats via the format parameter.
host:port one per line. The most common format — paste directly into tools like ProxyChecker, curl, or Python requests.
host,port,protocol,country,anonymity,score. One proxy per line with a header row. Import into spreadsheets or databases.
socks5://host:port one per line. Ready to use as proxy URLs in many tools and libraries.
# Plain text (host:port per line)
curl "https://api.proxynests.net/public/proxies/download?protocol=socks5&min_score=50" -o socks5.txt
# CSV
curl "https://api.proxynests.net/public/proxies/download?format=csv&min_score=60" -o proxies.csv
# Formatted (protocol://host:port)
curl "https://api.proxynests.net/public/proxies/download?format=formatted&protocol=socks5" -o socks5_formatted.txt
Parameters Reference
All query parameters that can be used across public and authenticated endpoints.
| Parameter | Type | Applies To | Description | Example |
|---|---|---|---|---|
| protocol | enum | proxies, download, random | Filter by proxy protocol. | socks5 |
| country | string | proxies, download, random | ISO 3166-1 alpha-2 country code (case-insensitive). | US |
| anonymity | enum | proxies, download, random | Filter by detected anonymity level. | elite |
| proxy_type | enum | proxies, download | IP classification: residential, datacenter, mobile, tor. | residential |
| min_score | integer | proxies, download, random | Minimum composite score (0–100). | 60 |
| max_latency_ms | integer | proxies, download | Maximum response latency in milliseconds. | 1000 |
| min_throughput_mbps | number | proxies, download | Minimum download speed in Mb/s. | 2.5 |
| sort_by | enum | proxies | score (default), latency, or random. |
random |
| limit | integer | proxies | Results per request. Max 300 (public), 500 (auth). | 100 |
| offset | integer | proxies | Skip this many results for pagination. | 50 |
| format | enum | proxies, download | Response format: json, text, csv, formatted. |
text |
Code Examples
Complete examples for fetching, downloading, and using proxies in common languages.
Fetch Proxy List
curl "https://api.proxynests.net/public/proxies?protocol=socks5&min_score=60&limit=100&format=text"
import requests
res = requests.get("https://api.proxynests.net/public/proxies", params={
"protocol": "socks5",
"min_score": 60,
"limit": 100,
"sort_by": "score",
})
data = res.json()
for proxy in data["proxies"]:
print(f"{proxy['host']}:{proxy['port']} score={proxy['score']}")
const url = new URL("https://api.proxynests.net/public/proxies");
url.searchParams.set("protocol", "socks5");
url.searchParams.set("min_score", "60");
url.searchParams.set("limit", "100");
const res = await fetch(url);
const data = await res.json();
for (const proxy of data.proxies) {
console.log(`${proxy.host}:${proxy.port} score=${proxy.score}`);
}
package main
import (
"encoding/json"
"fmt"
"net/http"
)
type Proxy struct {
Host string `json:"host"`
Port int `json:"port"`
Protocol string `json:"protocol"`
Score int `json:"score"`
}
func main() {
url := "https://api.proxynests.net/public/proxies?protocol=socks5&min_score=60&limit=100"
resp, _ := http.Get(url)
defer resp.Body.Close()
var result struct { Proxies []Proxy `json:"proxies"` }
json.NewDecoder(resp.Body).Decode(&result)
for _, p := range result.Proxies {
fmt.Printf("%s:%d score=%d\n", p.Host, p.Port, p.Score)
}
}
Download Full List
# Download all socks5 proxies with score >= 50 as plain text
curl "https://api.proxynests.net/public/proxies/download?protocol=socks5&min_score=50" -o socks5.txt
# Download as formatted URLs (socks5://host:port)
curl "https://api.proxynests.net/public/proxies/download?format=formatted&protocol=socks5&min_score=50" -o socks5_urls.txt
import requests
res = requests.get("https://api.proxynests.net/public/proxies/download", params={
"protocol": "socks5",
"min_score": 50,
})
proxies = res.text.strip().splitlines()
print(f"Downloaded {len(proxies)} proxies")
with open("socks5.txt", "w") as f:
f.write(res.text)
import { writeFileSync } from 'fs';
const res = await fetch(
"https://api.proxynests.net/public/proxies/download?protocol=socks5&min_score=50"
);
const text = await res.text();
writeFileSync("socks5.txt", text);
console.log(`Saved ${text.trim().split('\n').length} proxies`);
Random Proxy (Authenticated)
curl -H "X-API-Key: px_your_key" \
"https://api.proxynests.net/api/proxies/random?protocol=socks5&anonymity=elite&min_score=70"
import requests
res = requests.get(
"https://api.proxynests.net/api/proxies/random",
headers={"X-API-Key": "px_your_key"},
params={"protocol": "socks5", "anonymity": "elite", "min_score": 70},
)
proxy = res.json()
proxy_url = f"socks5://{proxy['host']}:{proxy['port']}"
print("Using proxy:", proxy_url)
const res = await fetch(
"https://api.proxynests.net/api/proxies/random?protocol=socks5&min_score=70",
{ headers: { "X-API-Key": process.env.PROXYNESTS_KEY } }
);
const proxy = await res.json();
console.log(`socks5://${proxy.host}:${proxy.port}`);
req, _ := http.NewRequest("GET",
"https://api.proxynests.net/api/proxies/random?protocol=socks5&min_score=70",
nil)
req.Header.Set("X-API-Key", os.Getenv("PROXYNESTS_KEY"))
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
var proxy Proxy
json.NewDecoder(resp.Body).Decode(&proxy)
fmt.Printf("socks5://%s:%d\n", proxy.Host, proxy.Port)
Rate Limits
Rate limits are enforced per API key (for authenticated requests) or per IP address (for public endpoints).
When you exceed the rate limit the API returns HTTP 429 Too Many Requests:
{
"error": "rate_limit_exceeded",
"message": "Too many requests. Limit: 60/min. Retry after 12s.",
"retry_after": 12
}
Retry-After response header also contains the number of seconds to wait before retrying.
Error Codes
All error responses follow a consistent JSON format with error and message fields.
X-API-Key header or ?key= query parameter.
Retry-After header for when you can retry. Consider upgrading your tier for higher limits.
Error Response Format
{
"error": "invalid_parameter",
"message": "'min_score' must be an integer between 0 and 100",
"param": "min_score"
}
Changelog
API version history and breaking changes.
User Accounts, Tiered Keys & Download Formats
- User accounts with dashboard at
/dashboard - Tiered API keys: Free, Pro, Enterprise with per-key rate limits
- New
/public/proxies/downloadendpoint with csv, json, formatted formats - New
/api/proxies/randomfor Pro and Enterprise tiers - New
/public/leaderboardand/public/ispsendpoints - New
/public/api-statsendpoint with uptime, request counts, incidents
Proxy Type & Throughput Data
- Added
proxy_typefield: residential, datacenter, mobile, tor - Added
download_mbpsandupload_mbpsfields to all proxy responses - New
proxy_typeandmin_throughput_mbpsfilter parameters - Throughput testing via Cloudflare speed endpoints
Format & Sort Improvements
- Added
format=textto/public/proxiesfor plain host:port output - Added
sort_by=randomfor shuffled proxy lists - Added
/public/countriesendpoint - Added
offsetparameter for pagination
Initial API Release
- Public
/public/proxiesendpoint with protocol, country, anonymity filters - Public
/public/statsendpoint - Composite scoring: latency 30%, reliability 30%, throughput 25%, freshness 10%, anonymity 5%
- JSON response format with full proxy metadata