Proxy Rotation API or Rotating Gateway: Which You Need

Two different mechanisms answer to the same phrase. One rotates without you calling anything; the other is an API call that replaces an address you keep.

"Proxy rotation API" is asked for far more often than it is defined, and the people asking usually want one of two quite different things. Deciding which before you write any code saves a rewrite, because the two mechanisms have opposite properties: one rotates continuously and gives you no control over individual addresses, and the other gives you total control and rotates only when you say so.

The two mechanisms

A rotating gateway is an endpoint, not an address. You point your client at one host and port, authenticate as normal, and every request that leaves it exits from a different address out of a pool. There is no API call involved in the rotation itself. You do not learn which address you got, you cannot ask for a specific one, and you cannot keep one beyond the session controls the gateway offers. The rotation is a property of the endpoint, and your code does nothing to trigger it.

An address-replacement API is the opposite. You hold a static proxy: a specific host and port that is yours, that you can name, and that stays the same across every request until you decide otherwise. When you want a different address, you call an endpoint and the proxy is issued a new one. Rotation is an explicit act with a request, a response and a moment you can log.

Almost everyone searching for a rotation API is describing one of those two, and the phrase does not distinguish them.

Which one your job wants

Ask what happens if two consecutive requests come from different addresses.

If the answer is "nothing, they are independent", you want the gateway. Independent lookups against a public endpoint, price checks across many targets, availability polling, anything where each request stands alone. The gateway gives you diversity for free, with no state to manage and no code to write beyond a connection string. You will spend less effort and get more address variety than you could sensibly manage yourself.

If the answer is "the second one breaks", you want a static proxy. Anything with a session, a cart, a login, a paginated crawl that the target ties to a visitor, or a target that issues a cookie it expects to see again. Rotating underneath state is worse than not rotating at all: an account or a session that appears from several addresses in quick succession is a far stronger signal than any single address, and the usual outcome is the session being invalidated rather than the request being blocked. Sticky versus rotating sessions sets out where that line falls in practice.

There is a middle case, and it is the one the replacement API exists for: work that needs a stable address most of the time and a fresh one occasionally. You hold an address, use it until it stops performing, replace it deliberately, and carry on. That pattern is not expressible through a gateway, because the gateway never gave you an address to hold.

Using the gateway

Nothing about the gateway is API-shaped. It is a connection string, and rotation happens because of which endpoint you connected to:

curl -x http://USERNAME:PASSWORD@GATEWAY_HOST:PORT https://api.ipify.org
curl -x http://USERNAME:PASSWORD@GATEWAY_HOST:PORT https://api.ipify.org

Run those twice and the two responses will usually differ, because each connection draws a new exit. Where a rotating product supports sticky sessions, the session identifier travels in the username rather than in a separate call, so holding an address is also not an API operation. The exact syntax for each product is on the rotating proxies page, and the connection string builder will assemble it for you.

The consequence worth internalising: there is no call to make, so there is nothing to rate limit, nothing to retry, and no failure mode where rotation itself breaks. That simplicity is the main argument for the gateway whenever your work permits it.

Using the replacement API

Static proxies are managed through the REST API, and address replacement is one call:

curl -X POST https://node4.io/api/v1/proxies/refresh \
  -H "Authorization: Bearer n4k_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"proxyId": 12345}'

The response returns the old address, the new address, the port and the credentials, along with how many replacements you have used and how many the plan allows. The key needs the write:proxies permission; a read-only key will be refused with a 403 rather than silently doing nothing.

Two properties of this endpoint shape how you should use it.

It is not free. Every plan carries a replacement allowance, and the response tells you where you are against it on every call. Treat the allowance as the scarce resource it is: replacing an address on the first failed request will exhaust it against transient problems that would have resolved themselves.

It is not instant from the target's point of view. You get a new address immediately, but the reputation of that address is whatever it already was, and any session state you held against the old one is gone. Replacement is a fresh start, not a repair.

A reasonable policy looks like: track failures per proxy, replace only after repeated failures against multiple targets rather than one, and never replace in response to a single non-200. The complete surface, including the exact response shape and every error code, is documented at /openapi.json, which you can import directly into Postman or generate a typed client from.

Listing what you have

Both models need a way to enumerate current proxies, and that is the same call either way:

curl https://node4.io/api/v1/proxies \
  -H "Authorization: Bearer n4k_YOUR_KEY"

This returns every proxy on the account including suspended and expired ones, which is deliberate: an integration that only saw active proxies could not tell you why its capacity had dropped. There is a compact form at /proxies/list intended for feeding a pool straight into automation, and a plain-text variant of it that emits one host:port:username:password per line for tools that expect that format.

Rate limits apply to the API as a whole at 60 requests per minute per key. That is generous for management operations and deliberately not sized for per-request use: the API manages proxies, it does not sit in the path of your traffic.

The mistake to avoid

The costly error is calling the replacement API on a schedule to imitate a gateway. It looks reasonable, and it is wrong in three ways at once.

It burns the replacement allowance on a job that never needed specific addresses. It introduces a failure mode, because now your traffic depends on an API call succeeding. And it produces worse diversity than the gateway would have, because you are cycling through a small number of addresses slowly rather than drawing from a pool.

If you find yourself building a scheduler around /proxies/refresh, the thing you actually wanted was the gateway. Going the other way is rarer but equally wasteful: holding a gateway session open and treating it as a fixed address works until it does not, and when it stops you have no way to ask for the same address back.

Checking which one you are actually on

The confirmation is the same in both cases, and worth doing before you build anything on top:

for i in 1 2 3; do
  curl -s -x http://USERNAME:PASSWORD@HOST:PORT https://api.ipify.org
  echo
done

Three different addresses means you are on a rotating endpoint. Three identical addresses means you hold a static proxy, and rotation for you is an API call rather than a property of the connection. If you expected one and got the other, the connection string is pointing at the wrong product, which is the most common cause of a rotation setup that appears to do nothing at all. If the addresses are identical and you expected them to be, the IP rotation guide covers what to do next.