Free Proxy API: A Simple Endpoint for Developers

A free proxy API is an HTTP endpoint that returns a fresh list of working proxies to your code, filterable by country, protocol, and anonymity, as plain text or JSON. Instead of copy-pasting IPs off a web page, you send one GET request and get the current pool back, which is exactly what the HProxy free proxy API does at GET /api/proxy-list with no key and no signup. This post covers what a free proxy API is, how to pull from ours with curl and Python, the quality and rate limits you have to design around, and the point where a paid residential API becomes the honest answer.

What a free proxy API actually is

A free proxy list is a web page built for humans. A free proxy API is the same data built for code. You hit a URL, you get back a machine-readable list, and your script decides what to do with it. If you have used ProxyScrape or a similar service, the shape is familiar: a base URL plus query parameters like protocol, country, and timeout, and a response of ip:port lines. The endpoint below follows that same convention.

The whole point is automation. A scraper can refresh its proxy pool every few minutes on its own, a CI job can grab a country-specific exit before a test, and a monitoring script can pull a batch, run its checks, and move on. No browser, no manual copying, no stale list pasted into a config file a week ago.

The catch, which the rest of this post is honest about, is that a free proxy API is only as good as the list behind it. The endpoint is trivial. Keeping that list fresh and actually checked is the hard part, and it is where most free sources fall down. Ours is re-checked every few minutes across 100-plus countries and four protocols (HTTP, HTTPS, SOCKS4, SOCKS5), which is the only reason the API is worth calling at all.

The HProxy free proxy API

One GET request returns the live list. No API key, no account, and CORS is enabled so you can call it from a browser as well as a server.

GET https://hproxy.com/api/proxy-list

It reads from the same pool that powers our free proxy list, so what you get in code is exactly what the page shows. You shape the response with query parameters:

Two things worth knowing before your first call. Pass recent=true unless you have a reason not to: it trims the list down to proxies confirmed alive in the last 48 hours, which is a much higher hit rate than the full historical pool. And every response carries an X-Total-Count header with the number of proxies returned, so you can log how big a batch you pulled without parsing the body first.

There is a fair-use rate limit of about 60 requests per minute per IP. Cross it and you get a 429 with a Retry-After header. That limit is generous on purpose, because the correct usage pattern almost never hits it, as covered further down. Full parameter reference and response schema live in the free proxy API docs.

Pull the list with curl

The simplest possible call returns the freshest proxies as plain ip:port lines:

curl "https://hproxy.com/api/proxy-list?format=txt&recent=true"

Filter it down to what you need. Say you want SOCKS5 proxies exiting in the US:

curl "https://hproxy.com/api/proxy-list?format=txt&recent=true&protocol=socks5&country=US"

Save the batch to a file your other tools can read:

curl -s "https://hproxy.com/api/proxy-list?format=txt&recent=true" -o proxies.txt

If you want to see the X-Total-Count header alongside the body, dump the response headers with -D -:

curl -sD - "https://hproxy.com/api/proxy-list?format=txt&recent=true&protocol=http" -o proxies.txt

From here you can pipe proxies.txt straight into whatever you are running. For a deeper look at routing an actual request through one of these proxies with curl, including SOCKS5 and header checks, see our guide on using proxies with curl.

Pull the list with Python

For anything beyond a one-off, JSON is easier to work with than text, because you get the metadata (latency, anonymity, network) alongside each ip:port. Here is the full pull with requests:

import requests

resp = requests.get(
    "https://hproxy.com/api/proxy-list",
    params={
        "format": "json",
        "protocol": "https",
        "country": "US",
        "recent": "true",
        "limit": 50,
    },
    timeout=15,
)
resp.raise_for_status()
proxies = resp.json()

print(len(proxies), "proxies")
print(proxies[0])

Each object in the JSON array carries the fields you need to make decisions: ip, port, protocols, country, network (the ASN, so you can tell datacenter from residential), anonymity, latency, uptime, and when it was last checked. You do not have to guess whether a proxy is fast or elite, the data is right there.

Now route a real request through one of them. The proxies dict in requests is keyed by the scheme of the target URL, so set both http and https to the same value:

p = proxies[0]
proxy_url = f"http://{p['ip']}:{p['port']}"

r = requests.get(
    "https://httpbin.org/ip",
    proxies={"http": proxy_url, "https": proxy_url},
    timeout=10,
)
print(r.json())  # shows the proxy's IP, not yours

That single-proxy call is the easy part. The dict keys, SOCKS5 handling, sessions, and the timeout tuples that keep a scraper from hanging are all covered in using proxies with Python requests.

Rotate, because any one proxy can die mid-run

A free proxy API is only useful if you treat the list as disposable. Any single free proxy can be dead by your next request, so you never rely on one. You pull a batch and rotate through it, moving to the next the moment one fails:

def fetch_through_pool(url, proxies):
    for p in proxies:
        proxy_url = f"http://{p['ip']}:{p['port']}"
        try:
            r = requests.get(
                url,
                proxies={"http": proxy_url, "https": proxy_url},
                timeout=8,
            )
            if r.ok:
                return r
        except requests.RequestException:
            continue  # dead or slow proxy, try the next one
    return None

Short timeout, catch the failure, move on. That loop is the difference between a job that finishes and one that stalls on the first dead IP. The full pattern (retry budgets, backoff, avoiding bans, and picking exit countries) is in our guide on proxies for web scraping.

The caveats nobody selling a free API mentions

Here is the honest part, because a free proxy API is a real tool with real limits and pretending otherwise wastes your time.

Free proxies die fast. Most are datacenter IPs on shared cloud servers, and they go offline within minutes to hours. Any list, ours included, is a snapshot of a moving target. That is precisely why recent=true exists and why you should verify a proxy right before you use it rather than trusting it from when you pulled it. Our proxy checker grades a single proxy for liveness, speed, and anonymity in one pass, and there is a matching checker API if you want that step automated too.

Only a small fraction of any free pool is alive at once. This is not a knock on the source, it is the nature of free proxies. In our study of 47 million checks, lifetimes run in minutes and hours because these IPs are shared, overloaded, and rotated constantly. Pull a big batch and expect to discard a lot of it. Build for failure with timeouts, retries, and rotation, as shown above, and the loss stops mattering.

Respect the rate limit by caching. The 60-requests-per-minute ceiling trips people who call the API once per proxy in a tight loop. Do not. Pull the whole list in one request, cache it for a minute (we cache it server-side for 60 seconds anyway, and the list only refreshes every few minutes), and rotate through your local copy. One call gives you thousands of proxies, so there is no reason to hammer the endpoint. If you do see a 429, read the Retry-After header and wait exactly that long.

A free API has no SLA. It is best-effort by definition. That makes it great for testing, learning, geo-checks, and low-stakes scraping, and a bad foundation for anything a business depends on. Knowing which side of that line your project sits on is the whole decision, and it leads straight to the next section. If you want the fuller version of that judgment call, we wrote when free proxies are fine.

When to move to a paid residential API

The moment a target site has real bot defenses, free datacenter proxies stop working, not because the API failed but because the IPs are wrong. Any site worth scraping can read the network behind an IP, and a cloud-server address announces "I am a datacenter, not a person" before the request finishes. For protected targets, account work, ad verification, or anything where the exit has to look like a real home connection, you need residential IPs, and residential is paid because home IPs are scarce.

Here is the honest comparison:

The rule that falls out of that table is simple. Use the free proxy API for throwaway work, learning, and anything where a flagged IP costs you nothing. Move to residential when the IP has to pass as a person and the job actually matters. There is no shame in either choice, they are just different tools. Our residential proxies are pay-as-you-go from $0.99/GB with no KYC and no contract, so the jump up is a config change, not a sales call.

Start pulling

The fastest way to see what the free proxy API gives you is to run one line right now:

curl "https://hproxy.com/api/proxy-list?format=txt&recent=true"

That returns the freshest slice of a list we re-check every few minutes across 100-plus countries and four protocols, and it costs nothing. Browse the same pool as a table on the free proxy list, grade any single proxy with the proxy checker, or read the full free proxy API docs for every parameter and response field. When free proxies stop cutting it and you need IPs that actually hold up, our residential proxies start at $0.99/GB, pay as you go. Build for failure, cache your pulls, and a free proxy API will carry you a lot further than most people expect.