API Reference

ProxyNests Documentation

Complete reference for all endpoints, parameters, and code examples. Base URL: https://api.proxynests.net

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

Base URL https://api.proxynests.net

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.

💡 All public endpoints at /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

Header
X-API-Key: px_your_key_here

Method 2 — Query Parameter

Query Param
?key=px_your_key_here
curl
# 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"
⚠️ Never expose your API key in client-side JavaScript or public repositories. Use environment variables or a backend proxy for production applications.

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

Upgrade your plan →

Public Endpoints

These endpoints require no authentication. Rate limited to 60 requests/minute per IP on the free tier.

GET /public/proxies List proxies with filters — up to 300 per request

Returns a filtered, sorted list of alive proxies. Supports rich query parameters for protocol, anonymity, type, country, score, latency, and speed filtering.

Query Parameters

ParameterTypeDefaultDescription
protocolenumallsocks5, socks4, http, https
countrystringallISO 3166-1 alpha-2 code, e.g. US, DE
anonymityenumallelite, anonymous, transparent
proxy_typeenumallresidential, datacenter, mobile, tor
sort_byenumscorescore, latency, random
min_scoreinteger0Minimum score 0–100
max_latency_msintegernoneMaximum latency in milliseconds
min_throughput_mbpsnumbernoneMinimum download speed in Mb/s
limitinteger50Results per page, max 300
offsetinteger0Pagination offset
formatenumjsonjson or text (plain host:port per line)

Response Example

JSON
{
  "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
}
GET /public/proxies/download Bulk download — no row limit

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

ParameterTypeDefaultDescription
formatenumtxttxt, csv, json, formatted
protocolenumallFilter by protocol
anonymityenumallFilter by anonymity level
min_scoreinteger0Minimum score threshold
GET /public/stats Live proxy statistics overview

Returns current counts broken down by protocol, anonymity, proxy type, plus average latency and speed metrics.

JSON
{
  "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
}
GET /public/countries Proxy count by country

Returns a list of countries with alive proxy counts, sorted by count descending. Useful for building geographic dashboards or selecting country-specific proxies.

GET /public/leaderboard Top 10 highest-scoring proxies

Returns the top 10 proxies sorted by composite score. Updated each time the checker completes a full run.

GET /public/isps Top ISPs / ASNs in the proxy pool

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.

GET /api/proxies/random Single random proxy — Pro / Enterprise

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

ParameterTypeDefaultDescription
protocolenumanyFilter by protocol
countrystringanyISO 3166-1 alpha-2 code
min_scoreinteger0Minimum score threshold
anonymityenumanyAnonymity level filter

Response Example

JSON
{
  "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.

txt Plain host:port one per line. The most common format — paste directly into tools like ProxyChecker, curl, or Python requests.
csv Comma-separated values: host,port,protocol,country,anonymity,score. One proxy per line with a header row. Import into spreadsheets or databases.
json Full JSON array of proxy objects with all fields: host, port, protocol, country_code, anonymity, proxy_type, score, latency_ms, download_mbps, upload_mbps, last_checked.
formatted Protocol-prefixed format: socks5://host:port one per line. Ready to use as proxy URLs in many tools and libraries.
curl — download examples
# 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.

ParameterTypeApplies ToDescriptionExample
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).

Free
60
requests / minute
Pro
500
requests / minute
Enterprise
5,000
requests / minute

When you exceed the rate limit the API returns HTTP 429 Too Many Requests:

JSON — 429 response
{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Limit: 60/min. Retry after 12s.",
  "retry_after": 12
}
💡 The 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.

400 Bad Request — Invalid query parameter value or type. Check the error message for the specific field that failed validation.
401 Unauthorized — No API key provided for an authenticated endpoint. Include X-API-Key header or ?key= query parameter.
403 Forbidden — Your API key is valid but does not have access to this endpoint. Upgrade your tier or contact support.
404 Not Found — The endpoint path does not exist. Check the URL for typos.
429 Too Many Requests — Rate limit exceeded. See the Retry-After header for when you can retry. Consider upgrading your tier for higher limits.
500 Internal Server Error — Unexpected server-side error. These are rare and automatically monitored. If persistent, check status page.

Error Response Format

JSON
{
  "error": "invalid_parameter",
  "message": "'min_score' must be an integer between 0 and 100",
  "param": "min_score"
}

Changelog

API version history and breaking changes.

v2.0

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/download endpoint with csv, json, formatted formats
  • New /api/proxies/random for Pro and Enterprise tiers
  • New /public/leaderboard and /public/isps endpoints
  • New /public/api-stats endpoint with uptime, request counts, incidents
v1.2

Proxy Type & Throughput Data

  • Added proxy_type field: residential, datacenter, mobile, tor
  • Added download_mbps and upload_mbps fields to all proxy responses
  • New proxy_type and min_throughput_mbps filter parameters
  • Throughput testing via Cloudflare speed endpoints
v1.1

Format & Sort Improvements

  • Added format=text to /public/proxies for plain host:port output
  • Added sort_by=random for shuffled proxy lists
  • Added /public/countries endpoint
  • Added offset parameter for pagination
v1.0

Initial API Release

  • Public /public/proxies endpoint with protocol, country, anonymity filters
  • Public /public/stats endpoint
  • Composite scoring: latency 30%, reliability 30%, throughput 25%, freshness 10%, anonymity 5%
  • JSON response format with full proxy metadata