Targeting & Username Syntax

Everything you control on a Proxio Residential proxy (the exit country, the state, the city, whether you hold one IP or rotate every request, how aggressively a connection retries) is expressed in one place: the username. There are no extra headers, no query strings, and no separate API to call. You build a username, send it as normal proxy Basic auth, and the gateway does the rest.

The connection string

Every request is routed through a standard proxy URL:

http://USERNAME:[email protected]:16666

It breaks down into five parts:

The simplest possible request uses the bare username with no targeting, so you get a fresh residential IP from the global pool on every request:

curl -x http://abcxyz123def:[email protected]:16666 https://ipinfo.io

The username grammar

To target a location or hold a session, you append hyphen-delimited segments to your base username. The full grammar is:

{base}[-region-{country}][-st-{state}][-city-{city}][-sessid-{sessionId}-sesstime-{minutes}[-retry-{N}[-retryrotate-1]]]

Every segment in square brackets is optional. The gateway reads them as key/value pairs, so their order does not technically matter; still, write them in the order above so usernames stay readable and match every example in these docs. What does matter is the geo hierarchy (country before state, state before city) and pairing sessid with sesstime.

Watch out at these points

Worked examples

Each example builds on the one before it. abcxyz123def is the base username and PASSWORD is the credential password.

1. Bare, a fresh IP every request (auto rotation).

http://abcxyz123def:[email protected]:16666

2. Add a country to exit from the United States.

http://abcxyz123def-region-us:[email protected]:16666

3. Add state and city to exit from Los Angeles, California.

http://abcxyz123def-region-us-st-california-city-losangeles:[email protected]:16666

4. Hold a sticky session: the same Los Angeles IP for 15 minutes.

http://abcxyz123def-region-us-st-california-city-losangeles-sessid-myapp_9k2p7qz1m4vb1-sesstime-15:[email protected]:16666

5. Smart rotation: sticky, plus up to 3 connection retries that each rotate the IP.

http://abcxyz123def-region-us-sessid-myapp_9k2p7qz1m4vb1-sesstime-15-retry-3-retryrotate-1:[email protected]:16666

Putting it in a request

Drop the full username into any HTTP client. This example targets the United States and verifies the exit IP against ipinfo.io:

curl -x "http://abcxyz123def-region-us:[email protected]:16666" https://ipinfo.io

import requests

proxy = "http://abcxyz123def-region-us:[email protected]:16666"
r = requests.get("https://ipinfo.io", proxies={"http": proxy, "https": proxy})
print(r.json())

import { ProxyAgent } from "undici";

const proxyAuth = Buffer.from("abcxyz123def-region-us:PASSWORD").toString("base64");
const dispatcher = new ProxyAgent({
  uri: "http://geo.proxio.cc:16666",
  token: `Basic ${proxyAuth}`,
});
const res = await fetch("https://ipinfo.io", { dispatcher });
console.log(await res.json());

Keep going