Proxy Rotation API or Rotating Gateway: Which You Need

Two mechanisms answer to the phrase rotation API. One is an endpoint that rotates by itself; the other is a call that replaces an address you keep.

"Proxy rotation API" usually means one of two different things. A rotating gateway is an endpoint that picks an exit for every connection (every request, for plain HTTP) without you calling anything. An address-replacement API is a call that swaps the IP of a static proxy you hold. Decide which you need before writing code, because the two have opposite properties.

Side by side

	Rotating gateway	Address-replacement API
What you hold	one hostname and port	a specific proxy with its own address
When the IP changes	on every new connection, automatically	when you call `POST /proxies/refresh`
Control over the address	none; you cannot ask for a specific exit	full; the address stays until you replace it
Keeping one IP across requests	session id in the username, up to 30 minutes on Rotating Datacenter and Rotating Unmetered	the address is already stable
Cost of rotating	none; nothing to call or rate limit	uses the plan's monthly refresh allowance
Fits	independent requests: lookups, price checks, polling	stateful work: logins, carts, paginated crawls, plus an occasional fresh address

Ask what happens if two consecutive requests come from different addresses. If nothing, you want the gateway. If the second one breaks (a session, a cart, a login, a target that issues a cookie it expects to see again), you want a static proxy; rotating underneath state usually gets the session invalidated rather than the request blocked. Sticky versus rotating sessions covers where that line falls.

The middle case is what the replacement API is 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. A gateway cannot express that, because it never gave you an address to hold.

Using the gateway

Rotation is a property of the endpoint you connect to. On Rotating Datacenter:

curl -x http://USERNAME:PASSWORD@gw-rotating_datacenter.node4.io:8083 https://api.ipify.org
curl -x http://USERNAME:PASSWORD@gw-rotating_datacenter.node4.io:8083 https://api.ipify.org

Run that twice and the two responses will usually differ, because each curl run opens a new tunnel and each tunnel draws an exit. Inside one program the unit is the same: an HTTPS tunnel or SOCKS5 connection keeps its exit for as long as the client keeps it open, while a plain-HTTP request gets a new exit every time.

To hold an address, put a session id in the username rather than making a separate call:

curl -x http://USERNAME-session-cart42:PASSWORD@gw-rotating_datacenter.node4.io:8083 https://api.ipify.org

Every connection that carries -session-cart42 leaves from the same exit until the session window ends. The Sticky session switch on the Proxies page's Connect card builds that username for you.

There is no call to make, so there is nothing to rate limit, nothing to retry, and no failure mode where rotation itself breaks.

Using the replacement API

Static proxies are managed through the REST API, and 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, with how many replacements you have used and how many the plan allows. The key needs the write:proxies permission; a read-only key gets a 403.

Two properties shape how to use it. It draws on an allowance: every plan carries a monthly replacement count, and replacing an address on the first failed request spends it on transient problems that would have resolved themselves. It is a fresh start, not a repair: the new address's reputation is whatever it already was, and any session state held against the old one is gone. A reasonable policy: track failures per proxy, replace only after repeated failures against several targets, and never on a single non-200. The full surface, including the response shape and every error code, is at /openapi.json, which imports into Postman or generates a typed client.

Listing what you have

Both models use the same call to enumerate proxies:

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

It returns every proxy on the account, including suspended and expired ones, so an integration can see why its capacity dropped. /proxies/list is the compact form for feeding a pool into automation, with a plain-text variant that emits one host:port:username:password per line.

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

The mistake to avoid

Calling the replacement API on a schedule to imitate a gateway burns the allowance on a job that never needed specific addresses, makes your traffic depend on an API call succeeding, and produces worse diversity than the gateway, because you cycle through a few addresses slowly instead of drawing from a pool. If you find yourself building a scheduler around /proxies/refresh, you wanted the gateway. The reverse is rarer: holding a gateway session and treating it as a fixed address works until the session ends, and then there is no way to ask for the same address back.

Checking which one you are on

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

Addresses that change between runs mean a rotating endpoint. Three identical addresses mean a static proxy, where rotation is an API call rather than a property of the connection, or a gateway username that still carries a -session- segment. If you expected one and got the other, the connection string points at the wrong product, which is the most common cause of a rotation setup that appears to do nothing. If the addresses are identical and you expected them to be, the IP rotation guide covers what to do next.