How to Use Residential Proxies

A residential proxy routes your request through a real home internet connection, so the target site sees a consumer ISP address instead of your server's datacenter IP. This guide covers the whole path: where the credentials come from, how targeting is encoded in the username, working code for five stacks, and what to check when a request fails. Every snippet below runs as written — replace the host, port, account and password with the values from your console.

What you need before you start

• An account with traffic on it. Residential is billed by traffic, so a small top-up is enough to test.
• Gateway host, port and credentials from the console (Proxy → Residential → Generate).
• A machine with an outbound connection. Residential gateways are reached over the public internet; no local agent or browser extension is required.

Step 1 — Read the username, because that is where targeting lives

IPLight uses a single endpoint for the whole pool. Country, region, city and session behaviour are all encoded in the username as hyphen-joined key-value pairs. This is why you never need a different port per country.

A typical username looks like this:

# sticky session: United States, New York, hold the same IP for 30 minutes
ACCOUNT-country-us-state-ny-city-newyork-sid-AbCdEfGhIjKl-stime-30

# rotating: United Kingdom, new IP on every request
ACCOUNT-country-gb-sid-ZzYyXxWwVvUu

Two things trip people up. First, codes are lowercase ISO-3166 alpha-2 for countries and the region codes listed in the console for states. Second, once you set sid, the gateway pins that session to one exit IP for stime minutes — if you want a fresh IP, change the sid, do not just wait.

Step 2 — Verify the exit before you write any code

One curl call tells you whether the credential, the endpoint and your network are all correct. Run this first; if it fails, nothing downstream will work.

# replace ACCOUNT, PASSWORD, GATEWAY_HOST and PORT
curl -x "http://ACCOUNT-country-us-sid-Test01-stime-10:PASSWORD@GATEWAY_HOST:PORT" \
     https://ipinfo.io/json

A correct response contains a US city, a consumer ISP in org, and an ip that is not your server. If you see your own datacenter IP, the proxy was not applied: on Linux and macOS check that no HTTP_PROXY / HTTPS_PROXY variable is overriding it, and on Windows check the system proxy settings.

Step 3 — Python with requests

The same credential string works for both schemes. Rotating and sticky behave identically in code; only the username changes.

import requests

USER = "ACCOUNT-country-us-sid-PyTest01-stime-10"
PWD  = "PASSWORD"
PROXY = "http://%s:%s@GATEWAY_HOST:PORT" % (USER, PWD)

session = requests.Session()
session.proxies = {"http": PROXY, "https": PROXY}

r = session.get("https://ipinfo.io/json", timeout=30)
print(r.status_code, r.json())

# rotate: build a new sid per request, reuse the TCP connection pool
import uuid
for i in range(5):
    user = "ACCOUNT-country-de-sid-%s" % uuid.uuid4().hex[:12]
    p = "http://%s:%s@GATEWAY_HOST:PORT" % (user, PWD)
    print(requests.get("https://ipinfo.io/ip", proxies={"http": p, "https": p}, timeout=30).text)

Step 4 — Node.js

// npm i undici
import { ProxyAgent, request } from "undici";

const user = "ACCOUNT-country-us-sid-Node01-stime-10";
const agent = new ProxyAgent(`http://${user}:PASSWORD@GATEWAY_HOST:PORT`);

const res = await request("https://ipinfo.io/json", { dispatcher: agent });
console.log(res.statusCode, await res.body.json());

If your project is on axios, pass httpsAgent and httpAgent built with https-proxy-agent instead — do not rely on the deprecated proxy option, which drops credentials on HTTPS.

Step 5 — Playwright and Puppeteer

Browser automation is where credentials usually break: Chromium's --proxy-server flag has no way to carry a username and password. Playwright and Puppeteer solve it in the API, which is why they are the pragmatic choice for headless work behind an authenticated gateway.

# Playwright (Python) — proxy auth is native
from playwright.sync_api import sync_playwright

USER = "ACCOUNT-country-us-city-newyork-sid-Pw01-stime-30"
with sync_playwright() as p:
    browser = p.chromium.launch(proxy={
        "server":   "http://GATEWAY_HOST:PORT",
        "username": USER,
        "password": "PASSWORD",
    })
    page = browser.new_page()
    page.goto("https://ipinfo.io/json", timeout=60000)
    print(page.inner_text("body"))
    browser.close()

// Puppeteer — authenticate the page, not the launch flag
const browser = await puppeteer.launch({
  headless: true,
  args: ["--proxy-server=http://GATEWAY_HOST:PORT"],
});
const page = await browser.newPage();
await page.authenticate({ username: USER, password: "PASSWORD" });
await page.goto("https://ipinfo.io/json", { waitUntil: "domcontentloaded" });

Step 6 — Scrapy

# settings.py
DOWNLOADER_MIDDLEWARES = {
    "scrapy.downloadermiddlewares.httpproxy.HttpProxyMiddleware": None,
    "myproject.middlewares.RotatingProxy": 543,
}

# myproject/middlewares.py
import uuid

class RotatingProxy:
    def __init__(self, settings):
        self.pwd = settings.get("PROXY_PASSWORD")

    @classmethod
    def from_crawler(cls, crawler):
        return cls(crawler.settings)

    def process_request(self, request, spider):
        user = "ACCOUNT-country-us-sid-%s" % uuid.uuid4().hex[:12]
        request.meta["proxy"] = "http://%s:%s@GATEWAY_HOST:PORT" % (user, self.pwd)

Rotating per request at the middleware level is the cheapest way to spread load: each item gets a fresh exit, and retries naturally land on a different IP.

Choosing rotating versus sticky

Troubleshooting, in the order you should check

Use it responsibly

Proxies change where a request comes from; they do not change what you are allowed to do. Collect only public data you have a right to access, respect the target's terms of service and robots directives, keep request rates at a level a human could plausibly generate, and never use a residential exit for fraud, credential stuffing or evading a ban you have already been given. In most jurisdictions the lawful basis for collection is your responsibility, not your proxy provider's.

Frequently asked questions