Tools
Rotating proxies, and what ours actually rotates
You send a URL and a region to one endpoint. We fetch it from an egress address in that region and hand back what the target said. That is the whole product, and this page describes the parts that rotate as carefully as the parts that do not.
What we do not offer
There is no host:port proxy string to paste into your HTTP client and no SOCKS5. There are no residential or mobile addresses — every address we have belongs to an AWS range. There is no scheduler either: nothing here runs your fetches on a cron, and there is no managed job queue. If what you need is a residential pool or a hosted crawl schedule, we are not that product, and finding that out on this page is cheaper than finding it out after you integrate.
The call, in full
POST /v2/proxy/fetch?region=us-east with an x-api-key header and a JSON body of {"url": "https://example.com/page"}. Region is a query parameter rather than a body field, which is the one detail people get wrong on the first attempt. The valid values today are us-east, us-west and europe.
The response is a JSON envelope describing the fetch. It is not a raw passthrough: you get the target's body plus enough metadata to know what actually happened, which is the part a proxy string cannot give you.
result
The target's response body, decoded to text.
status
The target's own HTTP status. A 429 from the target arrives as 429 with its body, not as an error from us.
final_url and redirects
Where the fetch ended up, and how many hops it took to get there.
public_ip and region_used
The egress address the target saw, and the region that actually served the request.
content_type, bytes, elapsed_ms
What the target declared, how large the body was, and how long the node took.
What rotates
The region you name selects the node. One node serves each region today, so naming a region names an egress address rather than drawing from a set behind it. The user-agent string presented to the target is the User-Agent header on your call, which you can vary per request from the catalog we publish at GET /v2/user-agents/.
Naming a region is a request rather than a guarantee, and the two ways that plays out are worth knowing rather than discovering. A region with nothing in service is refused outright: you get a 503 carrying region_out_of_service, no fetch is made and nothing is billed. A region that is in service but whose node fails mid-request is the other case — the fetch fails over to another region rather than failing outright, it is served from there, and it is billed.
That second case is why region_used is in the envelope. It is the region that actually served, and it differs from the one you asked for exactly when a failover happened. Read it rather than assuming your query parameter was honoured. If the exit location genuinely matters to your work — a target that varies its answer by country, or an obligation about where a request originates — compare region_used against what you asked for and treat a mismatch as a failure in your own code, because as far as the fetch is concerned it succeeded.
What does not rotate
The address space. Egress is three nodes in our own AWS account, each with a stable Elastic IP. There is no pool of thousands of addresses to cycle through, and we are not going to describe one.
That matters for a specific class of target. If a site blocks cloud address ranges outright, rotating between three addresses in the same kind of range does not change the answer. For public APIs, documentation, feeds, listings and most catalogue pages, it is exactly the right tool. For a site that specifically refuses datacenter traffic, it is the wrong one.
Retries that are not billed twice
Send an Idempotency-Key header and a retry after a timeout is neither re-executed against the target nor billed a second time. The replay carries an Idempotency-Replayed: true header so your code can tell a fresh fetch from a returned one.
Reusing a key for a different URL or region is refused rather than quietly served, and a retry that arrives while the original is still running is refused too. Both refusals carry stable machine-readable codes, and the code vocabulary is pinned against the published API reference by a test, so a code you branch on cannot silently change meaning.
Ask the API which regions are live
GET /v2/proxy/regions is the authoritative list and it is health-gated on two conditions: a region is advertised only if it has at least one endpoint that is not administratively disabled, and only if the health cache does not have fresh evidence that every one of those endpoints is failing. A region with nothing in service at all drops off the list and is refused with region_out_of_service if you ask for it anyway. GET /v2/proxy/status reports the fetch path's own health, region by region.
Read those at start-up instead of hardcoding a region list from a marketing page. Prose goes stale; the endpoint does not.
Questions
- Do I configure this as a proxy in my HTTP client?
- No. There is no proxy host, port or proxy-auth username to set. You make an ordinary HTTPS request to our API with your key in a header and read the response envelope. The same call works identically from a script, a serverless function or a backend service.
- How many IP addresses are in the pool?
- Three, one per region, each a stable Elastic IP on a node we run. We do not have a large pool and we do not claim one. The tier before this one was 33 third-party endpoints whose source we did not have; when we re-probed them, none of the 33 answered. Three addresses we own and can account for is the honest replacement, and GET /v2/proxy/regions is where you read what is live rather than taking a number off a page.
- Can I pin a session to one address?
- There is no sticky-session token, and with one stable address per region the question largely answers itself: naming the same region twice gets you the same egress address.
- What happens on a redirect?
- The egress node walks the chain one hop at a time and re-runs its SSRF checks against the resolved address of every hop, rather than handing the chain to an HTTP library to follow internally. You get final_url and redirects in the envelope so you know where you landed.
Get a key
Create an account and mint an API key in the dashboard. The full endpoint reference — request shapes, parameters and error codes — is published at https://api.roamingproxy.com/v2/docs.