Rotating Gateway Proxies

Rotating gateway proxies are shared gateway endpoints that route traffic through upstream providers based on the options you send with the request. Use the exact rotating HTTP/SOCKS endpoints shown in your account.

Unlike assigned/static endpoints, rotating gateways support request-level routing controls through structured usernames and HTTP targeting headers. The exact endpoint values are account-specific and should be copied from Portal → Rotating Gateway IPs.

Supported today: Use your base username for default routed traffic, or append structured controls for session, duration, provider (dc or res), and geo-country. HTTP also supports routing headers. Charges are usage-based and deducted from your account balance.

Find your endpoint

1. Open Portal → Proxy IPs.
2. Find the Rotating Gateway IPs section.
3. Copy the HTTP and SOCKS5 endpoints shown for your account.

Authentication & control model

Default routed usage

Use your username and API key directly when you want the gateway defaults. With no extra controls, each request can take a different route.

http://USERNAME:API_KEY@<ROTATING_HTTP_ENDPOINT>

Structured username controls

Append structured controls to the username when you need to choose a sticky session, session lifetime, provider type, or country on either HTTP or SOCKS5.

USERNAME--session-SESSION_ID--duration-SECONDS--provider-dc|res--geo-country-CC:API_KEY

How to choose between base username, controls, and headers

• Use the base username only when you just want routed traffic and do not care which exit route the next request uses.
• Use structured username controls when you want one copyable auth string that works on both HTTP and SOCKS5.
• Use HTTP headers when your client already handles proxy auth separately and you need HTTP-only inputs such as city, ISP, or ASN targeting.

Common combinations

USERNAME--provider-dc:API_KEY

USERNAME--provider-res--geo-country-us:API_KEY

USERNAME--session-checkout-flow-42--duration-90--provider-res--geo-country-us:API_KEY

Legacy sticky suffix compatibility

The legacy sticky suffix still works for compatibility, but the structured v1 grammar is the preferred customer-facing format because it exposes all supported inputs explicitly.

USERNAME-sessioncheckout42:API_KEY

Username-control inputs and allowed values

• session accepts letters, numbers, _, and -, with a maximum of 64 characters.
• duration must be a positive integer in seconds.
• provider supports only dc and res in the structured username grammar. Mobile is not a valid structured provider value today.
• geo-country must be a 2-letter country code such as us, gb, or de.
• You can combine these controls in any order after the base username, but each control can only appear once.

Recommended pattern: Start with the smallest set of controls you need. If you only need country targeting, use --geo-country-CC; if you need sticky behavior too, add --session-... and --duration-....

HTTP header options and when to use them

HTTP requests can also use headers when that is more convenient for your client. This is also where city, ISP, and ASN targeting live today.

• Headers are for HTTP requests. SOCKS5 clients should use structured username controls instead.
• City, ISP, and ASN targeting are available in headers, not in the structured username grammar.
• Header provider values use the full words such as datacenter and residential, while username controls use the short forms dc and res.

Routing controls quick lookup

Code examples

curl

# Default routed usage
curl -x "http://<USERNAME>:<API_KEY>@<ROTATING_HTTP_ENDPOINT>"   "https://ip.ninjasproxy.com/"

# Country-only route
curl -x "http://<USERNAME>--geo-country-us:<API_KEY>@<ROTATING_HTTP_ENDPOINT>"   "https://ip.ninjasproxy.com/"

# Datacenter route
curl -x "http://<USERNAME>--provider-dc:<API_KEY>@<ROTATING_HTTP_ENDPOINT>"   "https://ip.ninjasproxy.com/"

# Sticky residential US route for 90 seconds
curl -x "http://<USERNAME>--session-checkout-flow-42--duration-90--provider-res--geo-country-us:<API_KEY>@<ROTATING_HTTP_ENDPOINT>"   "https://ip.ninjasproxy.com/"

# Header fallback on HTTP when you need city / ISP / ASN controls
curl -x "http://<USERNAME>:<API_KEY>@<ROTATING_HTTP_ENDPOINT>"   -H "X-Session-ID: checkout-flow-42"   -H "X-Session-Duration: 90"   -H "X-Provider-Type: residential"   -H "X-Target-Geo: US"   -H "X-Target-City: NewYork"   "https://ip.ninjasproxy.com/"

SOCKS5 sticky session

curl --socks5-hostname "<ROTATING_SOCKS_ENDPOINT>"   --proxy-user "<USERNAME>--session-checkout-flow-42--duration-90--provider-res--geo-country-us:<API_KEY>"   "https://ip.ninjasproxy.com/"

Python

import requests

proxy = "http://<USERNAME>--session-cart-1--duration-120--provider-res--geo-country-us:<API_KEY>@<ROTATING_HTTP_ENDPOINT>"

response = requests.get(
  "https://ip.ninjasproxy.com/",
  proxies={"http": proxy, "https": proxy},
  timeout=20,
)
print(response.text.strip())

Next Steps

• Authentication — credential and whitelist setup
• Rate limits — connection reuse, retries, and concurrency
• curl integration — fastest path for debugging gateway requests
• API Reference — account and endpoint APIs