How to connect

Open the service in the dashboard and copy the Connection host and ports shown at the top of its page. The Username and password tab lists the same host and ports with your username and proxy password. Copy the host rather than reusing one from another service or product.

Connection host and ports

Every product uses the same three ports on its connection host:

Protocol	Port	Encrypted to the proxy
HTTP / CONNECT	8080	No
HTTPS (HTTP / CONNECT over TLS)	8443	Yes
SOCKS5	1080	No

The three ports carry the same traffic to the same exits. The difference is only the hop between you and us. SOCKS5 over TLS is not offered.

Tip

The HTTPS port is worth using where your client supports it. HTTPS to the destination site is end-to-end either way, but on the plain ports your proxy username — including any targeting — travels in clear text on the network you are connecting from.

HTTP

curl -x http://YOUR_HOST:YOUR_HTTP_PORT \
  -U "YOUR_USERNAME:YOUR_PASSWORD" \
  https://httpbin.org/ip

HTTPS

curl -x https://YOUR_HOST:YOUR_HTTPS_PORT \
  --proxy-user "YOUR_USERNAME:YOUR_PASSWORD" \
  https://httpbin.org/ip

SOCKS5

curl --socks5-hostname YOUR_HOST:YOUR_SOCKS_PORT \
  --proxy-user "YOUR_USERNAME:YOUR_PASSWORD" \
  https://httpbin.org/ip

Use --socks5-hostname (or the socks5h:// scheme) rather than socks5://, so hostnames are resolved at the exit rather than on your own machine.

Residential IPv4 exits cannot reach IPv6-only destinations. Use an IPv6 product when the target has no reachable IPv4 address.

Datacenter IPv6 connections

Datacenter IPv6 uses its own connection host for the city you bought. Copy the host and credentials from that service in the dashboard; the ports are the same 8080, 8443 and 1080. Do not construct an endpoint by assuming :443.

Targeting

Controls depend on the Residential IPv4 product:

• Unlimited: country and city targeting and sticky sessions.
• GB-based: country, city, region, and ASN targeting, and sticky sessions.

Both Residential IPv4 products accept a caller-set session lifetime on a sticky session; the options table gives the accepted range.

The Endpoints tab shows only the controls your service supports.

Targeting rides on the username only: add each option and its value after your username, separated by hyphens, as in YOUR_USERNAME-country-de. The password is always your plain proxy password.

Combine only options supported by your product. This advanced-targeting example is for GB-based:

curl -x http://YOUR_HOST:YOUR_HTTP_PORT \
  -U "YOUR_USERNAME-country-de-city-berlin-session-ab12cd:YOUR_PASSWORD" \
  https://httpbin.org/ip

Options

Option	Availability	Value
country	Unlimited and GB-based	Two-letter ISO 3166-1 code, e.g. de
city	Unlimited and GB-based	City name, ASCII, no spaces. Send country with it
region	GB-based only	ISO 3166-2 subdivision code, e.g. NY — not the name
asn	GB-based only	Digits only, e.g. 7922 — not AS7922
session	Unlimited and GB-based	1–32 letters or digits. Same value requests the same exit IP
lifetime	Unlimited and GB-based, with session	How long a session holds its IP, in seconds. GB-based: 1 to 86400. Unlimited: whole minutes, 60 to 86400 (1800 on some services)
rotate	Unlimited and GB-based	Asks for a new IP per connection. This is the default, so it is accepted and changes nothing

No other option names are accepted.

Username forms

These are common username shapes. Replace the capital placeholders with real values:

• base_username
• base_username-country-XX
• base_username-rotate
• base_username-rotate-country-XX
• base_username-session-ID
• base_username-session-ID-country-XX

Rotating and sticky

Send no session and each new connection exits from a new IP. This is per connection, not per request — a client reusing a keep-alive connection or a connection pool keeps the same IP for every request on it.

Send a session and requests carrying that value ask for the same exit. Add lifetime, in seconds, to set how long the session holds its IP; the accepted range for each product is in the options table. The Endpoints tab offers Set session lifetime where your service accepts one and shows its limit.

Session IDs are letters and digits only, up to 32 characters. Without lifetime, a session holds its IP for 10 minutes; lifetime is in seconds, up to 86400.

# Same IP for up to ten minutes
curl -x http://YOUR_HOST:YOUR_HTTP_PORT \
  -U "YOUR_USERNAME-session-ab12cd-lifetime-600:YOUR_PASSWORD" \
  https://httpbin.org/ip

Sessions are held on a best-effort basis. A held IP can drop early if the underlying residential connection goes away.

Options this product does not accept

latency, fraudscore, device, activesince, http3, localdns, udp and extended are not available on Residential IPv4. Sending one is refused with the same answer as any invalid targeting option (see How a refused request answers); the message does not name the option. Remove it and the request works.

Caution

Wrong values are refused rather than ignored. country-usa is not a two-letter country code, so the request is refused with the targeting answer, which does not name the option. It does not quietly fall back to an untargeted exit, so a typo can never bill you for traffic from somewhere you did not ask for.

How a refused request answers

A rejected option is answered where the request is read, before any exit is chosen, so it comes back in milliseconds and never consumes traffic:

Transport	Answer
HTTP and HTTPS CONNECT	407 Proxy Authentication Required, with the reason in the response body and in the X-Proxy-Reason header
SOCKS5	The username and password step fails, the same way a wrong password does

This covers a value that is malformed (country-usa), one that is well formed but names nothing (country-zz — zz is not assigned in ISO 3166-1), and an option repeated in the same username. The reason reads: “The targeting options in your username are not valid for this service. Check spelling, and do not repeat an option.”

Every refusal uses 407, so read the reason before you change your password. A wrong password, an unknown username and a bad targeting option each carry their own sentence. A CONNECT client such as a browser never shows the body, so log the X-Proxy-Reason header. SOCKS5 has no field for a reason: to see which part was refused, send the same username once over HTTP, for example with curl -v. Proxy errors and refusal reasons lists every reason and what to do about it.

A country that is a real ISO 3166-1 code but has no exit free right now is a different answer: a coverage miss, not a bad request, and it can succeed later without you changing anything.

Generating a list

The service’s Endpoints tab has a list generator: pick rotation or a session, the targeting controls supported by that service, quantity, and an output format (host:port:user:pass, user:pass@host:port, a URL, a curl command, or your own template), then copy or download it.

Trusted IPs

A service can authenticate by source address instead of by password. See Trusted IPs.