📚Complete API Reference

Free Proxy DatabaseAPI Documentation

Comprehensive API reference for accessing our 1000+ verified proxies programmatically. Build powerful applications with our RESTful APIs.

⚡

Valid Proxies API

📡

User Subscribe API

🔍

Proxy Search API

🕷️

Web Crawler API

✅

Proxy Checker API

🌐

IP Checker API

🔌

Port Checker API

👁️

Anon Check API

API Reference

Explore our comprehensive API endpoints for proxy management and web crawling capabilities.

Valid Proxies API

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/proxy/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, v2ray, ssr, ss). 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/proxy/valid_proxies?count=20&country=US&protocol=http,socks5&https=1"

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

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
}

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 v2ray-compatible subscription URL 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. Compared with the public /proxy/subscribe endpoint, this API supports a higher count (up to 1000) and is authenticated by your API Key instead of IP-based rate limits.

Endpoint

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

Query Parameters

count: Number of valid proxies to return. (default 50, min 10, max 1000)
subscribe_format: Output format. v2ray (default, base64-encoded text) 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, v2ray, ssr, ss). Accepts multiple values separated by commas. (optional)
link_type: Filter by connect-string prefix. Accepts multiple values separated by commas: vmess, vless, trojan, ss, ssr, tg, socks4, socks5, http. Useful for narrowing v2ray proxies to vmess or vless. (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/proxy/user_subscribe?count=100&protocol=v2ray&link_type=vmess,vless&subscribe_format=v2ray"

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

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 (compatible with common v2ray subscription clients):

dm1lc3M6Ly9leUpBZGF5T2lKU1FVNUxRVTlQ...

Proxy Search API

This API allows you to search for proxies based on various criteria such as country, protocol, anonymity, speed, and HTTPS support.

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, v2ray, ssr, ss). Accepts multiple values separated by commas.
link_type: Filter by connect-string prefix. Accepts multiple values separated by commas: vmess, vless, trojan, ss, ssr, tg, socks4, socks5, http. (optional)
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)

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

Response Data


{
    "data": [
        {
            "anonymity": "transparent",
            "asn": "AS4134 CHINANET-BACKBONE",
            "available_site_info": null,
            "check_error_count": 0,
            "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,
            "last_checked": "Fri, 03 Jan 2025 09:59:42 GMT",
            "port": 8093,
            "protocol": "http",
            "secret": null,
            "site_protocol": "http",
            "speed": 2.35
        }
    ]
}

Web Crawler API

This API allows you to scrape websites using a specified proxy.

Endpoint

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

Query Parameters

url: The URL of the website to crawl.
protocol: The proxy protocol to use (http, socks5, etc.).
timeout: The timeout for the request in seconds.

https://freeproxydb.com/api/proxy/web_crawler?url=http://example.com&protocol=http&timeout=30

Response Data


{
    "data": "{\n  \"args\": {}, \n  \"headers\": {\n    \"Accept\": \"text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8\", \n    \"Accept-Encoding\": \"gzip, deflate\", \n    \"Accept-Language\": \"en-US,en;q=0.5\", \n    \"Cookie\": \"\", \n    \"Host\": \"httpbin.org\", \n    \"User-Agent\": \"Mozilla/5.0 (Macintosh; Intel Mac OS X 14.0; rv:120.0) Gecko/20100101 Firefox/120.0\", \n    \"X-Amzn-Trace-Id\": \"Root=1-6789faa8-01ccb24979c6769f4a942d54\"\n  }, \n  \"origin\": \"138.199.29.136\", \n  \"url\": \"http://httpbin.org/get\"\n}\n",
    "message": "success",
    "status": 1
}

Proxy Checker API

This API checks the status of proxies.

Endpoint

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

Request Body


{"protocol":"http","servers":["8.8.8.8:80","8.8.4.4:80","user:[email protected]:80"],"timeout":10}

Response Data


{
    "data": [
        {
            "flag": false,
            "server": "8.8.8.8:80",
            "proxy": {
                "id": null,
                "ip": "8.8.8.8",
                "asn": "",
                "speed": 0,
                "port": "80",
                "protocol": "http",
                "anonymity": "",
                "is_valid": false,
                "https": false,
                "check_success_count": 0,
                "check_error_count": 0,
                "country": "",
                "city": "",
                "connect_string": "",
                "available_site_info": "",
                "site_protocol": "http",
                "secret": "",
                "source": "",
                "username": "",
                "password": "",
                "last_checked": "2025-01-17 03:29:51",
                "created_at": null
            }
        },
        {
            "flag": false,
            "server": "8.8.4.4:80",
            "proxy": {
                "id": null,
                "ip": "8.8.4.4",
                "asn": "",
                "speed": 0,
                "port": "80",
                "protocol": "http",
                "anonymity": "",
                "is_valid": false,
                "https": false,
                "check_success_count": 0,
                "check_error_count": 0,
                "country": "",
                "city": "",
                "connect_string": "",
                "available_site_info": "",
                "site_protocol": "http",
                "secret": "",
                "source": "",
                "username": "",
                "password": "",
                "last_checked": "2025-01-17 03:29:51",
                "created_at": null
            }
        },
        {
            "flag": false,
            "server": "user:[email protected]:80",
            "proxy": {
                "id": null,
                "ip": "8.8.8.8",
                "asn": "",
                "speed": 0,
                "port": "80",
                "protocol": "http",
                "anonymity": "",
                "is_valid": false,
                "https": false,
                "check_success_count": 0,
                "check_error_count": 0,
                "country": "",
                "city": "",
                "connect_string": "",
                "available_site_info": "",
                "site_protocol": "http",
                "secret": "",
                "source": "",
                "username": "user",
                "password": "123",
                "last_checked": "2025-01-17 03:29:51",
                "created_at": null
            }
        }
    ],
    "message": "success",
    "status": 1
}

IP Checker API

This API checks the status and anonymity of an IP address.

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

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 API

This API checks the status of open ports on a given 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

Response Data


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

Anon Check API

This API checks the anonymity level of a proxy.

Endpoint

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

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
}