API reference: GET /api/getProxy

Quick start

Get a proxy with a single request. No signup or API key needed for free requests.

$ curl 'https://gimmeproxy.com/api/getProxy?curl=true'

>>> import requests
>>> requests.get('https://gimmeproxy.com/api/getProxy?curl=true').text

> const res = await fetch('https://gimmeproxy.com/api/getProxy?curl=true')
> await res.text()

Sample response

http://192.0.2.24:8080

HTTPS checked

Filter parameters

Filter the pool of proxies to get a random match.

Parameter	Example	Behavior
`country`	`BR,AR`	Include ISO country codes
`notCountry`	`US`	Exclude ISO country codes
`protocol`	`socks5`	http, socks4 or socks5
`port`	`8080`	Match an exact port
`minSpeed`	`100`	Minimum speed in KB/s
`maxCheckPeriod`	`3600`	Seconds since verification (default 3600)
`anonymityLevel`	`0 or 1`	Filter by recorded level
`websites`	`google`	Paid API key required

Website options: example, google, amazon, yelp.

Response modes

Choose the response format that works for your project.

JSON

Default record with proxy details.

GET /api/getProxy

curl=true

Returns a proxy URL.

GET /api/getProxy?curl=true

ipPort=true

Returns IP and port only.

GET /api/getProxy?ipPort=true

Capability filters

Filter by proxy capabilities. Only the value true applies these filters.

get, post, cookies, referer, user-agent, supportsHttps

Paid access

Add your paid key for plan-specific limits and website filtering.

GET /api/getProxy?api_key=YOUR_API_KEY

Errors & limits

Common response codes and their meaning.

Code	Meaning
`200`	A result, or no matching proxy
`401`	Malformed or unknown key
`403`	Ended key or paid filter without a key
`429`	Quota or rate exceeded
`503`	API keys not enabled on this server

No match uses HTTP 200 with an error body.

{ "error": "no more proxies left" }

Free requests: 240 per IP per day, reported in Rate-Limit-Total, Rate-Limit-Remaining and Rate-Limit-Reset. Keys report X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a 429 carries Retry-After.

Recipes

Get a proxy and send one request through it, retrying with a new proxy when one fails.

cURL

p=$(curl -s 'https://gimmeproxy.com/api/getProxy?curl=true&protocol=http')
curl -sS --connect-timeout 5 -m 30 -x "$p" https://example.com/

Python

import requests

def fetch(url, attempts=4):
    for _ in range(attempts):
        proxy = requests.get("https://gimmeproxy.com/api/getProxy",
                             params={"curl": "true", "protocol": "http"}, timeout=10).text
        if proxy.startswith("{"):        # {"error": ...}: nothing matched
            continue
        try:
            return requests.get(url, proxies={"http": proxy, "https": proxy}, timeout=(5, 30))
        except requests.RequestException:
            pass                         # dead proxy: try another
    raise RuntimeError("no working proxy")

Node.js

// npm install undici
import { ProxyAgent, fetch } from "undici";

const proxy = await (await fetch("https://gimmeproxy.com/api/getProxy?curl=true&protocol=http")).text();
const res = await fetch("https://example.com/", {
  dispatcher: new ProxyAgent(proxy),
  signal: AbortSignal.timeout(30_000),
});
console.log(res.status);

Public proxies can stop working. Handle timeouts and retry in your client.

One endpoint.Plenty of control.