Proxies

Sites often block or limit addresses that send many requests, and show different content per country. Route the request through a proxy with options.proxy:

"options": { "proxy": { "country": "GB" } }

See it workCopy Anchor Link

api.ipify.org answers with the address the request came from. Without a proxy, you see the API server's address:

With a proxy in the United Kingdom or the United States, you see the proxy's address, and the response says where it was:

{
  "status": 200,
  "proxy": { "source": "pool", "country": "GB", "city": "London" },
  "data": ["45.38.107.97"]
}

Available locationsCopy Anchor Link

GET /proxies/countries returns the same list, for your code.

RotationCopy Anchor Link

The API picks a new proxy, at random among those that match, for every attempt. With retries, a request blocked from one address is retried from another:

"options": { "proxy": true, "retry": 3 }

Your own proxiesCopy Anchor Link

Already paying for proxies? Pass them in list, and the API uses them instead of its pool:

"options": {
  "proxy": {
    "list": [
      "http://alice:[email protected]:8080",
      "203.0.113.8:8080:alice:s3cret",
      "socks5://alice:[email protected]:1080",
      "198.51.100.5:3128"
    ]
  }
}

• list is an array, or a single string with one proxy per line, up to 100.
• Each line can be scheme://user:password@host:port, user:password@host:port, host:port:user:password or host:port without authentication.
• Passwords can contain any character, : and @ included, in the host:port:user:password form. In the URL forms, percent-encode them (@ as %40).
• Proxies on private or local addresses (127.0.0.1, 10.x, 192.168.x…) are refused.

Saved proxiesCopy Anchor Link

Save your list once in Dashboard → Developers → Proxies, then use "saved" instead of the list in any request:

"proxy": { "list": "saved", "country": "FR" }

The saved list uses the syntax above, one proxy per line. Its passwords are encrypted, only added to the request at the last moment, and never shown again: the dashboard shows them masked, and editing replaces the whole list. Without a saved list, the request fails with NO_SAVED_PROXIES.

Proxy typesCopy Anchor Link

With every SOCKS type, the proxy resolves the target's hostname, so DNS lookups don't leak from the API's location. Fingerprints can't go through SOCKS4: those proxies are skipped when fingerprint is set.

Target a country, region or cityCopy Anchor Link

Tell the API where each proxy is, and target a location like with our pool. Add it after the proxy, separated by |: country code, then region, then city, each optional:

"list": [
  "203.0.113.7:8080:alice:s3cret | FR | Île-de-France | Paris",
  "203.0.113.8:8080:alice:s3cret | FR | Auvergne-Rhône-Alpes | Lyon",
  "socks5://alice:[email protected]:1080 | DE | | Berlin"
]

Or, in an array, as objects:

"list": [
  {
    "url": "203.0.113.7:8080:alice:s3cret",
    "country": "FR",
    "region": "Île-de-France",
    "city": "Paris"
  }
]

Then filter with country, region and city next to list. Each accepts one value or an array, and region and city names match regardless of case and accents ("ile-de-france" matches Île-de-France):

"proxy": {
  "list": ["…"],
  "region": ["Île-de-France", "Auvergne-Rhône-Alpes"]
}

If no proxy matches, the API answers 503 PROXY_UNAVAILABLE without contacting the site.

In the responseCopy Anchor Link

The response tells you which line was used, and its location if you gave one, never its address or credentials:

"proxy": {
  "source": "custom",
  "index": 0,
  "country": "FR",
  "region": "Île-de-France",
  "city": "Paris"
}

A proxy that refuses the connection, for example because of wrong credentials, is a NETWORK_ERROR. With retry, the next attempt picks another line.

Proxies and fallbacksCopy Anchor Link

A fallback strategy can turn the proxy on, change countries, switch to your own proxies, or turn it off with "proxy": false.

A common pattern: try without a proxy first, which is faster, and use one only if the site refuses:

"options": {
  "fallback": [
    { "proxy": true, "retry": 2 }
  ]
}

Note where retry goes: it's an option of the strategy, next to proxy, not inside it. Inside proxy it would be ignored.

You can chain strategies to widen the net step by step. Here the API tries a US proxy first, because the site shows US prices, then any country if no US proxy works, with up to 2 retries:

"options": {
  "proxy": { "country": "US" },
  "fallback": [
    { "proxy": true, "retry": 2 }
  ]
}

When no proxy is availableCopy Anchor Link

If no proxy is available in the requested countries, the API answers 503 PROXY_UNAVAILABLE without contacting the site. A fallback strategy can then try other countries or no proxy at all.

CachingCopy Anchor Link

Pages fetched through a proxy are cached separately per location filter, and per list of your own proxies, since a site can show different content to each.