Python SDK

The official FreeProxyDB Python SDK (freeproxydb) wraps the REST APIs documented on this page. Use it to search proxies, fetch subscription feeds, run checker tools, call the server-side Web Crawler (HTTP / SOCKS / Xray pool routing), and send local HTTP requests with automatic HTTP/SOCKS proxy rotation — without hand-rolling request logic for every endpoint.

Requirements: Python 3.9+. Runtime dependency: httpx[socks].

Install

PyPI (coming soon): pip install freeproxydb is not available yet. Install from the GitHub repository for now:

git clone https://github.com/LoneKingCode/free-proxy-db.git
cd free-proxy-db/sdk
pip install -e .

Source & full README: github.com/LoneKingCode/free-proxy-db/sdk

Public API (no API key)

PublicClient covers public /proxy/* endpoints: search, subscribe, statistics, checker tools, and web crawler.

from freeproxydb import PublicClient

with PublicClient() as client:
    page = client.search(
        country="US",
        protocol=["http", "socks5"],
        page_size=10,
        order_by="check_success_count",
        order_dir="desc",
    )
    print(page["total_count"], len(page["data"]))

    feed = client.subscribe(country="US", count=50, subscribe_format="v2ray")
    stats = client.statistics()
    ip_info = client.ip_checker("8.8.8.8")

Filter parameters (country, protocol, …) accept a comma-separated string or a list of strings.

User API (API key required)

UserClient covers authenticated /user/* endpoints, including the high-quality valid_proxies pool and production web crawler quotas.

import os
from freeproxydb import UserClient

with UserClient(api_key=os.environ["FREEPROXYDB_API_KEY"]) as user:
    proxies = user.valid_proxies(
        count=20,
        country="US",
        protocol=["http", "socks5"],
        simple=True,
    )
    feed = user.subscribe(count=100, subscribe_format="original")

The SDK sends the key via the X-API-KEY header (recommended). The server also accepts api_key as a query parameter.

Web Crawler

Both PublicClient.web_crawler and UserClient.web_crawler call FreeProxyDB’s server-side crawler. You send a target URL; the API routes the request through HTTP, SOCKS, and/or the internal Xray pool and returns the response body text. See also the REST reference: Public Web Crawler and User Web Crawler.

Protocol modes

Basic GET

from freeproxydb import PublicClient

with PublicClient() as client:
    body = client.web_crawler(
        "https://httpbin.org/get",
        protocol="auto",
        timeout=30,
    )
    print(body[:200])

POST with headers, cookie, and body

Optional method, headers (dict or JSON string), cookie, and body customize the outbound request — same options as the Web Crawler tool Advanced settings.

from freeproxydb import PublicClient, UserClient

payload = '{"hello":"world"}'
headers = {
    "Content-Type": "application/json",
    "User-Agent": "MyBot/1.0",
}

# Public crawler (per-IP limits)
with PublicClient() as client:
    body = client.web_crawler(
        "https://httpbin.org/post",
        protocol="auto",
        method="POST",
        headers=headers,
        cookie="session=abc123",
        body=payload,
        timeout=30,
    )
    print(body)

# User crawler (production — per-key quotas)
with UserClient(api_key="YOUR_API_KEY") as user:
    body = user.web_crawler(
        "https://httpbin.org/post",
        protocol="auto",
        method="POST",
        headers='{"Content-Type":"application/json"}',
        body=payload,
        timeout=30,
    )

Web Crawler parameters

Hop-by-hop headers such as Host and Content-Length are rejected. Invalid combinations (e.g. body with GET) raise ValueError locally before the HTTP call.

Proxied HTTP Requests (auto switch HTTP/SOCKS)

ProxyHttpClient pulls proxies from the API, retries on failure, and skips bad proxies automatically. Runs requests from your machine through rotating HTTP / SOCKS4 / SOCKS5 proxies. Does not use the server-side crawler or Xray pool — for VMess/VLESS/Trojan routing, use web_crawler instead.

from freeproxydb import ProxyHttpClient

# Public pool (search API)
with ProxyHttpClient(
    country="US",
    protocol=["http", "socks5"],
    pool_size=20,
    max_retries=5,
) as client:
    result = client.get("https://httpbin.org/ip")
    print(result.proxy_url, result.response.text)

# High-quality pool (API key → valid_proxies)
with ProxyHttpClient(api_key="YOUR_API_KEY", protocol=["http", "socks5"]) as client:
    ok, body, msg, proxy = client.fetch("https://example.com")
    print(ok, msg)

SDK API Coverage

Error Handling

API errors inherit from FreeProxyDBError. Common types: RateLimitError, AuthenticationError, AuthorizationError, and ApiError. Local parameter validation in web_crawler raises ValueError.

from freeproxydb import PublicClient, RateLimitError, ApiError

client = PublicClient()
try:
    client.search(page_size=100)
except RateLimitError as exc:
    print(exc.status_code, exc.detail)
except ApiError as exc:
    print("API error:", exc)

try:
    client.web_crawler("https://example.com", "auto", method="GET", body="x")
except ValueError as exc:
    print("Invalid params:", exc)

Proxy Search Public · Free

This API allows you to search for proxies based on various criteria such as country, protocol, anonymity, speed, and HTTPS support. Requests are subject to rate limits per client IP, including limits on total records returned over time.

Endpoint

https://freeproxydb.com/api/proxy/search

Query Parameters

• country: Country code (two letters). Accepts multiple values separated by commas.
• protocol: Protocol type (http, socks5, socks4, mtproto, vmess, vless, trojan, hysteria2, ss, ssr). Accepts multiple values separated by commas.
• anonymity: Anonymity level (elite, anonymous, transparent). Accepts multiple values separated by commas.
• speed: Speed range (0-30). Accepts a range separated by a comma.
• https: HTTPS support (0 or 1).
• page_index: Page index for pagination. (default 1)
• page_size: Number of results per page. (default 10, max 100)
• order_by: Sort field — id, ip, port, protocol, country, asn, speed, anonymity, https, last_checked, check_success_count, check_error_count. (default id)
• order_dir: Sort direction — asc or desc. (default desc)
• fields: Optional. Set to connect_string to return plain text only — one connect string per line (no JSON wrapper).

https://freeproxydb.com/api/proxy/search?country=US,CA&protocol=http,socks4,socks5,vmess,vless&anonymity=elite&speed=0,17.9&https=1&page_index=1&page_size=10

https://freeproxydb.com/api/proxy/search?protocol=http,socks5&page_size=50&fields=connect_string

Python Example

import requests

API_BASE = "https://freeproxydb.com/api/proxy"
params = {
    "country": "US,CA",
    "protocol": "http,socks4,socks5,vmess,vless",
    "anonymity": "elite",
    "speed": "0,17.9",
    "https": 1,
    "page_index": 1,
    "page_size": 10,
}

response = requests.get(f"{API_BASE}/search", params=params, timeout=30)
response.raise_for_status()
data = response.json()
print(data["data"])

Response Data

{
    "status": 1,
    "message": "success",
    "data": {
        "total_count": 1234,
        "data": [
            {
                "anonymity": "transparent",
                "asn": "AS4134 CHINANET-BACKBONE",
                "check_success_count": 42,
                "city": "Shanghai",
                "connect_string": "http://120.71.144.31:8093",
                "country": "CN",
                "https": 0,
                "id": 1,
                "ip": "120.71.144.31",
                "is_valid": 1,
                "port": 8093,
                "protocol": "http",
                "site_protocol": "http",
                "speed": 2.35
            }
        ]
    }
}

Subscribe Public · Free

Returns a subscription feed of currently valid proxies as connect strings, one per line. Proxies are sorted by check success count (descending) and then speed (ascending). Use this for Clash, v2rayN, Shadowrocket, or any client that accepts a subscription URL.

No API Key required. Response is text/plain, not JSON. Rate limits apply per client IP (see below). For a higher count per request and the high-quality pool, use User Subscribe.

Endpoint

https://freeproxydb.com/api/proxy/subscribe

Query Parameters

• count: Number of proxies to return. Default 50, min 10, max 500.
• subscribe_format: Output format — v2ray (default, base64-encoded subscription) or original (plain connect strings, one per line).
• country: Country code (two letters). Multiple values separated by commas. (optional)
• protocol: Protocol type (http, socks5, socks4, mtproto, vmess, vless, trojan, hysteria2, ss, ssr). Multiple values separated by commas. (optional)
• anonymity: Anonymity level (elite, anonymous, transparent). Multiple values separated by commas. (optional)
• speed: Speed range in seconds, e.g. 0,17.9. (optional)
• https: Set to 1 to only return HTTPS-capable proxies. (optional)

Rate Limits

Per client IP: 3 requests / minute, 10 requests / hour.

Examples

curl "https://freeproxydb.com/api/proxy/subscribe?count=50&protocol=vmess,vless&subscribe_format=v2ray"

curl "https://freeproxydb.com/api/proxy/subscribe?count=10&country=US&protocol=http,socks5&subscribe_format=original"

Python Example

import requests

API_BASE = "https://freeproxydb.com/api/proxy"
params = {
    "count": 50,
    "protocol": "vmess,vless",
    "subscribe_format": "original",
}

response = requests.get(
    f"{API_BASE}/subscribe",
    params=params,
    timeout=30,
)
response.raise_for_status()
print(response.text)

Response

Returns plain text (text/plain), not JSON.

subscribe_format=original — one connect string per line:

vmess://eyJhZGQiOiIxLjIuMy40IiwicG9ydCI6NDQzLC...
vless://[email protected]:443?encryption=none&security=tls&type=ws
socks5://203.0.113.10:1080

subscribe_format=v2ray — the same lines joined with newlines, then base64-encoded (common Clash / v2rayN subscription format):

dm1lc3M6Ly9leUpBZGF5T2lKU1FVNUxRVTlQ...

Public vs User Subscribe

Statistics Public · Free

Pool overview endpoints for dashboards and monitoring. Both return JSON. No API Key required.

Pool Statistics

GET https://freeproxydb.com/api/proxy/statistics

Basic pool stats: total proxy count, country count, last check/crawl times, and per-protocol counts.

curl "https://freeproxydb.com/api/proxy/statistics"

{
    "status": 1,
    "message": "success",
    "data": {
        "total_count": 1234,
        "total_country_count": 86,
        "last_check_time": 1735689600000,
        "last_crawl_time": 1735689000000,
        "protocol_count": {
            "http": 320,
            "socks5": 280,
            "vmess": 150
        }
    }
}

Extended Statistics

GET https://freeproxydb.com/api/proxy/total_statistics

Extended breakdown: valid/invalid counts, daily new proxies, protocol ratios, and country/protocol distribution.

curl "https://freeproxydb.com/api/proxy/total_statistics"

{
    "status": 1,
    "message": "success",
    "data": {
        "total_proxies": 5000,
        "valid_proxies": 1234,
        "invalid_proxies": 3766,
        "daily_new_proxies": 120,
        "protocol_ratio": { "http": 0.26, "socks5": 0.23 }
    }
}

Python Example

import requests

API_BASE = "https://freeproxydb.com/api/proxy"

stats = requests.get(f"{API_BASE}/statistics", timeout=30).json()
total = requests.get(f"{API_BASE}/total_statistics", timeout=30).json()
print(stats["data"])
print(total["data"])

Client IP Public · Free

Returns the caller’s IP address as seen by the API, using request headers (e.g. X-Forwarded-For, X-Real-IP) when present. Useful for verifying proxy egress or debugging integrations.

Subject to tool rate limits per client IP (same as Web Crawler and checker tools).

Endpoint

GET https://freeproxydb.com/api/proxy/client_ip

Query Parameters

None.

Example

curl "https://freeproxydb.com/api/proxy/client_ip"

Python Example

import requests

response = requests.get(
    "https://freeproxydb.com/api/proxy/client_ip",
    timeout=30,
)
response.raise_for_status()
print(response.json()["data"])

Response

{
    "status": 1,
    "message": "success",
    "data": {
        "ip": "203.0.113.10"
    }
}

Web Crawler Public · Free

Fetch any URL through FreeProxyDB’s live proxy infrastructure — a continuously validated pool of 1,000+ nodes spanning HTTP, SOCKS, VMess, VLESS, Trojan, Shadowsocks, and more. You send a URL; we handle routing, retries, and egress selection server-side.

No API Key required. Ideal for testing and light automation. Requests are subject to rate limits per client IP. For production workloads, higher quotas, and dedicated per-key limits, use the User Web Crawler API (/api/user/web_crawler).

How routing works

Our crawler does not rely on a single proxy type. Depending on protocol, requests are routed through:

• Classic HTTP / SOCKS pool — top-validated proxies from the database, rotated automatically on failure.
• Xray connection pool — for share-link nodes (VMess, VLESS, Trojan, etc.), we spin up local Xray clients and expose a SOCKS hop. Your request exits through the node without you managing configs or clients.
• Automatic failover — failed routes are skipped; the service retries across the pool until a working path is found (or limits are reached).

Use protocol=auto to enable the full stack: Xray pool first, then HTTP and SOCKS from the high-quality pool — the same engine that powers our free Web Crawler tool.

Endpoint

https://freeproxydb.com/api/proxy/web_crawler

Query Parameters

• url (required): Full target URL.
• protocol (required): http, socks, or auto. See protocol modes below.
• timeout (optional): Per-request timeout, 1–60 seconds.

Advanced options

Optional request customization. Custom values merge on top of default browser-like headers. Forbidden hop-by-hop headers include Host and Content-Length.

• method (optional): GET (default) or POST.
• headers (optional): JSON object string, e.g. {"User-Agent":"MyBot/1.0","Referer":"https://example.com"}.
• cookie (optional): Shorthand for the Cookie header.
• body (optional): Raw POST body. Only with method=POST.

Also available in the free Web Crawler tool under Advanced settings.

Protocol modes

https://freeproxydb.com/api/proxy/web_crawler?url=https://httpbin.org/get&protocol=auto&timeout=30

curl -G \
  --data-urlencode "url=https://httpbin.org/post" \
  --data-urlencode "protocol=auto" \
  --data-urlencode "method=POST" \
  --data-urlencode 'headers={"Content-Type":"application/json"}' \
  --data-urlencode 'body={"hello":"world"}' \
  "https://freeproxydb.com/api/proxy/web_crawler"

Python Example

import requests

API_BASE = "https://freeproxydb.com/api/proxy"
params = {
    "url": "https://httpbin.org/post",
    "protocol": "auto",
    "method": "POST",
    "headers": '{"Content-Type":"application/json"}',
    "body": '{"hello":"world"}',
    "timeout": 30,
}

response = requests.get(f"{API_BASE}/web_crawler", params=params, timeout=90)
response.raise_for_status()
data = response.json()
print(data["data"])

Response Data

{
    "data": "{\\n  \\"args\\": {}, \\n  \\"headers\\": { ... }, \\n  \\"url\\": \\"https://httpbin.org/get\\"\\n}\\n",
    "message": "success",
    "status": 1
}

Upgrade to the User API

Need predictable throughput for scrapers, price monitors, or integrations? An API Key unlocks the same routing engine with per-key quotas, higher limits, and limits that are not tied to your IP — built for production use. See User Web Crawler or request a key via Telegram on our website footer.

Proxy Checker Public · Free

This API checks proxy availability and connection speed. Each server must be a full URL with scheme; the protocol is detected automatically — no separate protocol field is required. Requests are subject to rate limits per client IP.

Endpoint

https://freeproxydb.com/api/proxy/proxy_checker

Supported URL Schemes

Bare ip:port without a scheme is not accepted and returns reason: "invalid_url".

For share links (vmess, vless, ss, ssr, tg), use a timeout of at least 20 seconds.

Request Body

• servers (required): Array of full proxy URLs, one per entry. Max 100 items.
• timeout (optional): Per-proxy check timeout in seconds (1–60, default varies by protocol).

{
  "servers": [
    "http://8.8.8.8:8080",
    "socks5://user:[email protected]:1080",
    "vmess://eyJhZGQiOiIxLjIuMy40IiwicG9ydCI6NDQzLCJpZCI6Ii4uLiJ9",
    "tg://proxy?server=1.2.3.4&port=443&secret=ee..."
  ],
  "timeout": 20
}

Python Example

import requests

API_BASE = "https://freeproxydb.com/api/proxy"
payload = {
    "servers": [
        "http://8.8.8.8:8080",
        "socks5://user:[email protected]:1080",
        "vmess://eyJhZGQiOiIxLjIuMy40IiwicG9ydCI6NDQzLCJpZCI6Ii4uLiJ9",
        "vless://[email protected]:443?encryption=none&security=tls&type=ws",
        "ss://[email protected]:8388",
        "tg://proxy?server=1.2.3.4&port=443&secret=ee...",
    ],
    "timeout": 20,
}

response = requests.post(
    f"{API_BASE}/proxy_checker",
    json=payload,
    timeout=120,
)
response.raise_for_status()
data = response.json()
for item in data["data"]:
  status = "OK" if item["flag"] else item.get("reason", "fail")
  proto = item["proxy"].get("site_protocol", "?")
  print(item["server"], status, proto, item["proxy"].get("speed"))

Response Data

{
  "data": [
    {
      "flag": true,
      "server": "http://8.8.8.8:8080",
      "proxy": {
        "ip": "8.8.8.8",
        "port": "8080",
        "protocol": "http",
        "site_protocol": "http",
        "speed": 1.23,
        "https": false,
        "anonymity": "elite",
        "is_valid": true,
        "connect_string": "http://8.8.8.8:8080"
      }
    },
    {
      "flag": false,
      "server": "8.8.8.8:8080",
      "reason": "invalid_url",
      "proxy": {
        "ip": "",
        "port": -1,
        "protocol": "",
        "site_protocol": ""
      }
    }
  ],
  "message": "success",
  "status": 1
}

flag is true when the proxy passed validation. site_protocol reflects the detected type. Classic proxies (http, socks4, socks5) also include https and anonymity fields.

IP Checker Public · Free

This API checks the status and geolocation of an IP address. Requests are subject to rate limits per client IP.

Endpoint

https://freeproxydb.com/api/proxy/ip_checker

Query Parameters

• ip: The IP address to check.
• original_info: If true, returns original information about the IP.

https://freeproxydb.com/api/proxy/ip_checker?ip=120.71.144.31&original_info=true

Python Example

import requests

API_BASE = "https://freeproxydb.com/api/proxy"
params = {
    "ip": "120.71.144.31",
    "original_info": True,
}

response = requests.get(f"{API_BASE}/ip_checker", params=params, timeout=30)
response.raise_for_status()
data = response.json()
print(data["data"])

Response Data

{
    "data": {
        "ip": "120.71.144.31",
        "hostname": "120.71.144.31",
        "type": "ipv4",
        "continent_code": "AS",
        "continent_name": "Asia",
        "country_code": "CN",
        "country_name": "China",
        "region_code": "XJ",
        "region_name": "Xinjiang",
        "city": "Ürümqi",
        "zip": "830000",
        "latitude": 43.81999969482422,
        "longitude": 87.57305908203125,
        "msa": null,
        "dma": null,
        "radius": null,
        "ip_routing_type": "fixed",
        "connection_type": "tx",
        "location": {
            "geoname_id": 1529102,
            "capital": "Beijing",
            "languages": [
                {
                    "code": "zh",
                    "name": "Chinese",
                    "native": "中文"
                }
            ],
            "country_flag": "https://1.1.com/flags/cn.svg",
            "country_flag_emoji": "🇨🇳",
            "country_flag_emoji_unicode": "U+1F1E8 U+1F1F3",
            "calling_code": "86",
            "is_eu": false
        },
        "time_zone": {
            "id": "Asia/Urumqi",
            "current_time": "2025-01-17T12:40:48+06:00",
            "gmt_offset": 21600,
            "code": "+06",
            "is_daylight_saving": false
        },
        "currency": {
            "code": "CNY",
            "name": "Chinese Yuan",
            "plural": "Chinese yuan",
            "symbol": "CN¥",
            "symbol_native": "CN¥"
        },
        "connection": {
            "asn": 137695,
            "isp": "Chinatelecom Xinjiang Wulumuqi Man Network",
            "sld": null,
            "tld": null,
            "carrier": "chinatelecom xinjiang wulumuqi man network",
            "home": false,
            "organization_type": "Telecommunications",
            "isic_code": "J6100",
            "naics_code": "000517"
        },
        "security": {
            "is_proxy": false,
            "proxy_type": null,
            "is_crawler": false,
            "crawler_name": null,
            "crawler_type": null,
            "is_tor": false,
            "threat_level": "low",
            "threat_types": null,
            "proxy_last_detected": null,
            "proxy_level": null,
            "vpn_service": null,
            "anonymizer_status": null,
            "hosting_facility": false
        }
    },
    "message": "success",
    "status": 1
}
    

Port Checker Public · Free

This API checks whether ports are open on a given IP. Requests are subject to rate limits per client IP.

Endpoint

https://freeproxydb.com/api/proxy/port_checker

Query Parameters

• ip: The IP address to check.
• ports: A list of ports to check.
• timeout: Timeout for the request in seconds.

https://freeproxydb.com/api/proxy/port_checker?ip=120.71.144.31&ports=8093,8080&timeout=30

Python Example

import requests

API_BASE = "https://freeproxydb.com/api/proxy"
params = {
    "ip": "120.71.144.31",
    "ports": "8093,8080",
    "timeout": 30,
}

response = requests.get(f"{API_BASE}/port_checker", params=params, timeout=30)
response.raise_for_status()
data = response.json()
print(data["data"])

Response Data

{
    "data": {
        "ip": "8.8.8.8",
        "opened": [],
        "closed": [
            22,
            23
        ],
        "duration": 3
    },
    "message": "success",
    "status": 1
}
    

Anon Check Public · Free

This API reflects your current request headers and IP to help assess proxy anonymity. No query parameters. Requests are subject to rate limits per client IP.

Endpoint

https://freeproxydb.com/api/proxy/anon_check

Python Example

import requests

API_BASE = "https://freeproxydb.com/api/proxy"

response = requests.get(f"{API_BASE}/anon_check", timeout=30)
response.raise_for_status()
data = response.json()
print(data["data"]["ipInfo"]["AnonymityLevel"])

Response Data

{
    "data": {
        "headers": {
            "host": "freeproxydb.com",
            "x-real-ip": "162.158.88.1",
            "x-forwarded-for": "162.158.88.1",
            "connection": "close",
            "cf-ray": "90345c51cabd302b-SIN",
            "cookie": "_ga=GA1.1.1.1;",
            "accept-encoding": "gzip, br",
            "priority": "u=1, i",
            "x-forwarded-proto": "https",
            "accept-language": "en-US,en;q=0.9,zh-CN;q=0.8,zh;q=0.7",
            "referer": "https://freeproxydb.com/anonChecker",
            "cf-visitor": "{\"scheme\":\"https\"}",
            "cdn-loop": "cloudflare; loops=1",
            "sec-fetch-dest": "empty",
            "cf-connecting-ip": "1.30.61.50",
            "sec-fetch-mode": "cors",
            "sec-fetch-site": "same-origin",
            "cf-ipcountry": "SG",
            "sec-ch-ua-platform": "\"Windows\"",
            "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
            "accept": "application/json, text/plain, */*",
            "sec-ch-ua": "\"Google Chrome\";v=\"131\", \"Chromium\";v=\"131\", \"Not_A Brand\";v=\"24\"",
            "sec-ch-ua-mobile": "?0"
        },
        "ipInfo": {
            "ip": "1.30.61.50",
            "city": "Singapore",
            "country": "SG",
            "asn": "136744 Dream Power Technology Limited",
            "latitude": 1.287950038909912,
            "longitude": 103.8517837524414,
            "AnonymityLevel": "anonymous"
        }
    },
    "message": "success",
    "status": 1
}
    

Valid Proxies API Key Required

This API returns the top N currently valid proxies, sorted by check success count (descending) and then speed (ascending, faster first).

API Key is required. This endpoint is not publicly accessible without authentication. All requests must include a valid API Key.

Endpoint

https://freeproxydb.com/api/user/valid_proxies

Query Parameters

• count: Number of proxies to return. (default 10, max depends on your API Key configuration)
• country: Country code (two letters). Accepts multiple values separated by commas. (optional)
• protocol: Protocol type (http, socks5, socks4, mtproto, vmess, vless, trojan, hysteria2, ss, ssr). Accepts multiple values separated by commas. (optional)
• https: HTTPS support filter, set to 1 to only return HTTPS-capable proxies. (optional)
• simple: Set to 1 or true to return minimal fields only: ip, port, country, city. (optional, default false)

curl -H "X-API-KEY: YOUR_API_KEY" "https://freeproxydb.com/api/user/valid_proxies?count=20&country=US&protocol=http,socks5&https=1"

curl -H "X-API-KEY: YOUR_API_KEY" "https://freeproxydb.com/api/user/valid_proxies?count=20&country=US&simple=1"

curl "https://freeproxydb.com/api/user/valid_proxies?api_key=YOUR_API_KEY&count=20&country=US&simple=1"

Python Example

import requests

API_BASE = "https://freeproxydb.com/api/user"
headers = {"X-API-KEY": "YOUR_API_KEY"}
params = {
    "count": 20,
    "country": "US",
    "protocol": "http,socks5",
    "https": 1,
    "simple": 1,
}

response = requests.get(
    f"{API_BASE}/valid_proxies",
    headers=headers,
    params=params,
    timeout=30,
)
response.raise_for_status()
data = response.json()
print(data["data"])

Response Data

Full response (default):

{
    "data": [
        {
            "anonymity": "elite",
            "asn": "AS15169 GOOGLE",
            "available_site_info": null,
            "check_error_count": 1,
            "check_success_count": 128,
            "city": "Los Angeles",
            "connect_string": "http://203.0.113.10:8080",
            "country": "US",
            "https": 1,
            "id": 42,
            "ip": "203.0.113.10",
            "is_valid": 1,
            "last_checked": "2025-01-17 03:29:51",
            "port": 8080,
            "protocol": "http",
            "secret": null,
            "site_protocol": "http",
            "speed": 1.82
        }
    ],
    "message": "success",
    "status": 1
}
    

Simple response (simple=1):

{
    "data": [
        {
            "ip": "203.0.113.10",
            "port": 8080,
            "country": "US",
            "city": "Los Angeles"
        }
    ],
    "message": "success",
    "status": 1
}
    

Subscribe API Key Required

This API returns a subscription feed of currently valid proxies as connect strings, one per line. Proxies are sorted by check success count (descending) and then speed (ascending).

Use this endpoint when you want a base64-encoded subscription feed or a plain-text proxy list for clients such as Clash, v2rayN, or Shadowrocket. Filtering uses the same criteria as the website search and public subscribe URL.

API Key is required. Uses the high-quality proxy pool (same ranking as Valid Proxies). Compared with Public Subscribe, this endpoint supports up to count=1000 per request and per-key rate limits instead of IP limits.

Endpoint

https://freeproxydb.com/api/user/subscribe

Query Parameters

• count: Number of proxies to return. Default 50, min 10, max 1000.
• subscribe_format: Output format. v2ray (default, base64-encoded subscription) or original (plain connect strings, one per line). (optional)
• country: Country code (two letters). Accepts multiple values separated by commas. (optional)
• protocol: Protocol type (http, socks5, socks4, mtproto, vmess, vless, trojan, hysteria2, ss, ssr). Accepts multiple values separated by commas. (optional)
• anonymity: Anonymity level (elite, anonymous, transparent). Accepts multiple values separated by commas. (optional)
• speed: Speed range in seconds, e.g. 0,17.9. (optional)
• https: Set to 1 to only return HTTPS-capable proxies. (optional)

curl -H "X-API-KEY: YOUR_API_KEY" "https://freeproxydb.com/api/user/subscribe?count=100&protocol=vmess,vless&subscribe_format=v2ray"

curl -H "X-API-KEY: YOUR_API_KEY" "https://freeproxydb.com/api/user/subscribe?count=50&country=US&protocol=http,socks5&subscribe_format=original"

curl "https://freeproxydb.com/api/user/subscribe?api_key=YOUR_API_KEY&count=50&country=US&protocol=http,socks5&subscribe_format=original"

Python Example

import requests

API_BASE = "https://freeproxydb.com/api/user"
headers = {"X-API-KEY": "YOUR_API_KEY"}
params = {
    "count": 100,
    "protocol": "vmess,vless",
    "subscribe_format": "original",
}

response = requests.get(
    f"{API_BASE}/subscribe",
    headers=headers,
    params=params,
    timeout=30,
)
response.raise_for_status()
print(response.text)

Response

Returns plain text (text/plain), not JSON.

subscribe_format=original — one connect string per line:

vmess://eyJhZGQiOiIxLjIuMy40IiwicG9ydCI6NDQzLC...
vless://[email protected]:443?encryption=none&security=tls&type=ws
socks5://203.0.113.10:1080

subscribe_format=v2ray — the same lines joined with newlines, then base64-encoded (common Clash / v2rayN subscription format):

dm1lc3M6Ly9leUpBZGF5T2lKU1FVNUxRVTlQ...
    

Web Crawler API Key Required

Production-grade URL fetching through FreeProxyDB’s full proxy stack: thousands of daily-validated nodes, multi-protocol routing, and an internal Xray connection pool that turns VMess, VLESS, Trojan, and other share-link nodes into ready-to-use SOCKS egress — no client setup on your side.

Send a URL and protocol=auto; we select the route, retry across the pool, and return the response body. Same engine as our Web Crawler tool, optimized for programmatic scraping at scale.

Why use the User API

API Key is required. Limits (rate, daily quota, max timeout, etc.) are set per key. Contact us via Telegram in the website footer to request a key or upgrade limits for your use case.

Infrastructure overview

• Large validated pool — HTTP, SOCKS4/5, and share-link protocols from our database, ranked by check success and speed.
• Xray pool — VMess / VLESS / Trojan nodes are materialized as local Xray processes with SOCKS ports; failed slots are replaced automatically.
• Smart routing & retries — auto walks Xray → HTTP → SOCKS with failover; you get resilience without maintaining your own proxy rotation.
• One HTTP call — no need to download lists, parse share links, or run Xray yourself; ideal when proxy diversity matters more than a fixed egress IP.

Endpoint

https://freeproxydb.com/api/user/web_crawler

Query Parameters

• url (required): Full target URL, e.g. https://example.com/page.
• protocol (required): Proxy routing mode — http, socks, or auto. See Protocol modes below.
• timeout (optional): Per-request timeout in seconds (1–60). Server default applies if omitted.

Advanced options

Same as the Public Web Crawler: method, headers (JSON), cookie, and body (POST). User API adds higher quotas and per-key limits for production integrations.

• method (optional): GET (default) or POST.
• headers (optional): JSON object string, e.g. {"User-Agent":"MyBot/1.0","Referer":"https://example.com"}. Max 30 entries.
• cookie (optional): Shorthand for the Cookie header. Merged with headers if both are set.
• body (optional): Raw POST body string. Only allowed when method=POST. Set Content-Type in headers when needed (e.g. application/json).

Protocol modes

auto is not limited to classic HTTP/SOCKS — when the Xray pool is active, egress may use VMess, VLESS, Trojan, or other share-link protocols transparently via a local SOCKS hop. You get multi-protocol diversity from a single API parameter.

Examples

curl -H "X-API-KEY: YOUR_API_KEY" \
  "https://freeproxydb.com/api/user/web_crawler?url=https://httpbin.org/get&protocol=auto&timeout=30"

curl -G -H "X-API-KEY: YOUR_API_KEY" \
  --data-urlencode 'url=https://example.com/api' \
  --data-urlencode 'protocol=auto' \
  --data-urlencode 'method=POST' \
  --data-urlencode 'headers={"Referer":"https://example.com","Content-Type":"application/json"}' \
  --data-urlencode 'body={"page":1}' \
  "https://freeproxydb.com/api/user/web_crawler"

Python Example

import requests

API_BASE = "https://freeproxydb.com/api/user"
headers = {"X-API-KEY": "YOUR_API_KEY"}
params = {
    "url": "https://httpbin.org/post",
    "protocol": "auto",
    "method": "POST",
    "headers": '{"Content-Type":"application/json"}',
    "body": '{"hello":"world"}',
    "timeout": 30,
}

response = requests.get(
    f"{API_BASE}/web_crawler",
    headers=headers,
    params=params,
    timeout=90,
)
response.raise_for_status()
data = response.json()
print(data["data"])

Response

JSON wrapper; page body is in data (string).

{
  "status": 1,
  "message": "success",
  "data": "<html>...</html>"
}

Errors

• 400 — invalid URL, protocol, timeout, or fetch failed after retries
• 401 — missing API Key
• 403 — invalid or disabled API Key
• 429 — rate limit or quota exceeded