ScrapingProxies

Scrape Any Site in 20 Lines with Residential Proxies (Node.js & Python)

TM
Scraping Specialist
Published
July 18, 2026
Updated
September 28, 2026
Reviewed by
Read Time
5 min read
The SDK builds the username so you don't assemble it: pass country, session, and ttl, get a residential exit

Most "how to use a proxy" tutorials spend 800 words on theory before they show you a single line of code. This one won't. If you have a terminal and five minutes, you'll have a working scraper routing through real residential IPs by the end of this page.

We'll use the official Aethyn SDK (proxy-builder-sdk), which is a thin wrapper around the proxy.aethyn.io gateway. It builds the right proxy URL for you — country, city, sticky sessions, protocol — so you don't have to hand-assemble username strings.

1. Install

# Node.js
npm install proxy-builder-sdk

# Python
pip install proxy-builder-sdk

2. Authenticate

Grab your username (aethyn-XXXXX) and password from the dashboard. You can pass them directly, or set AETHYN_USERNAME / AETHYN_PASSWORD in your environment and let the client pick them up.

# Python
from proxy_builder_sdk import AethynClient

client = AethynClient(username="aethyn-XXXXX", password="PASSWORD")
# or just AethynClient() if the env vars are set

// Node.js
import { AethynClient } from "proxy-builder-sdk";

const client = new AethynClient({ username: "aethyn-XXXXX", password: "PASSWORD" });
// or new AethynClient() if AETHYN_USERNAME / AETHYN_PASSWORD are set

3. Your first proxied request

Let's prove the IP is real by hitting ipify through the proxy. If the returned IP isn't yours, it's working.

# Python
import requests

p = client.proxy(country="us")
r = requests.get("https://api.ipify.org?format=json", proxies=p.proxies)
print(r.json())   # -> some residential US IP, not your server's

// Node.js — bring any HTTP client; here's undici (npm i undici). axios/got work too.
import { ProxyAgent, request } from "undici";

const p = client.proxy({ country: "us" });
const res = await request("https://api.ipify.org?format=json", {
  dispatcher: new ProxyAgent(p.url),
});
console.log(await res.body.json());

That's the whole game. client.proxy() gives you a rotating IP — a fresh residential address on every request — which is what you want for high-volume, stateless scraping like price checks or SERP snapshots. If you would rather configure Requests by hand, the Python Requests proxy guide has the raw proxies dict, SOCKS5, and 407 handling.

proxy() is a fresh household IP on every request
Each proxy() call is a new household exit. Use it for price checks and SERP snapshots, not for a login flow.

4. When you need the same IP: sticky sessions

Some jobs break if your IP changes mid-task — logging in, walking through a cart, paginating behind a session cookie. For those, pin one IP for a set number of minutes with session():

# Python — same German IP for 10 minutes
p = client.session(country="de", session="cart42", ttl=10)

// Node.js — same German IP for 10 minutes
const p = client.session({ country: "de", session: "cart42", ttl: 10 });

The session label is yours to name; reuse the same label to land on the same exit IP again. When ttl expires (or you switch labels), you get a fresh one.

session() holds one rotating-pool IP for the flow
session() holds one rotating-pool IP for the flow. Default 30 minutes, range 1–1440 — not a dedicated IP.

5. Precise targeting (Elite)

Need a specific city or ISP for fingerprint-sensitive targets? That's the Elite tier:

# Python
p = client.session(
    country="us", city="chicago", isp="comcast",
    session="run1", ttl=30, tier="elite",
)

// Node.js
const p = client.session({
  country: "us", city: "chicago", isp: "comcast",
  session: "run1", ttl: 30, tier: "elite",
});
City and ISP are Elite username suffixes, not a static product
Premium is country. Elite adds city and ISP as username suffixes on the same residential pool, not a static product.

6. JavaScript-heavy sites: drive Playwright

If the data only appears after the page's JS runs (most React/Next.js sites), point a real browser through the proxy. The SDK hands Playwright the proxy config directly:

# Python
from playwright.sync_api import sync_playwright

p = client.session(country="fr", session="s1", ttl=15, tier="elite")
with sync_playwright() as pw:
    browser = pw.chromium.launch(proxy=p.for_playwright())
    page = browser.new_page()
    page.goto("https://example.com")
    print(page.title())
    browser.close()

// Node.js
import { chromium } from "playwright";

const p = client.session({ country: "fr", session: "s1", ttl: 15, tier: "elite" });
const browser = await chromium.launch({ proxy: p.forPlaywright() });
const page = await browser.newPage();
await page.goto("https://example.com");
console.log(await page.title());
await browser.close();

For an agent-driven version of this — where the AI picks the country and holds one sticky identity per task — see the Aethyn Browser MCP, which wraps the same gateway behind Model Context Protocol tools.

7. Prefer SOCKS5?

One flag:

p = client.proxy(country="jp", protocol="socks5")   # -> socks5://...@proxy.aethyn.io:1099

const p = client.proxy({ country: "jp", protocol: "socks5" });

A real mini-example: one product, three countries

Prices and availability change by region. Here's the whole thing — check a page from the US, Germany, and Japan, each through a local residential IP:

import requests
from proxy_builder_sdk import AethynClient

client = AethynClient()  # env vars set
url = "https://api.ipify.org?format=json"  # swap for your target

for cc in ["us", "de", "jp"]:
    p = client.proxy(country=cc)
    r = requests.get(url, proxies=p.proxies, timeout=30)
    print(cc, "->", r.json())

A few things that will save you time

Rotating vs sticky is the decision that trips people up most: use proxy() (rotating) for stateless, high-volume reads; use session() (sticky) the moment a cookie, login, or multi-step flow is involved. When you hit a 403 or 429, don't hammer — rotate. With a rotating proxy that's automatic on the next request; with a sticky one, change the session label to jump to a fresh IP. And always verify your exit IP landed where you asked before you trust the page, especially for geo-specific data.

One responsible-use note, because it matters: scrape public data only, and respect each site's robots.txt, rate limits, and terms. Clean, well-behaved scraping is also more reliable scraping — you get blocked far less when you're not acting like a firehose.

Try it

New accounts get a bandwidth allowance to test both the Premium and Elite tiers — no credit card required. Grab your aethyn-XXXXX credentials, drop them into one of the snippets above, and you'll see a real residential IP come back on the first run.

→ SDK docs and reference · Start the free trial

Aethyn runs an 87M+ IP residential pool across 195 countries and 2,400+ cities, with a 99.8% success rate over the last 7 days. Premium is €2.00/GB, Elite €4.50/GB, pay-as-you-go or monthly.

FAQ

Common questions about this article

Do I actually need residential proxies to scrape?
For open APIs or lightly-defended pages, datacenter IPs are cheaper and fine. For sites that block by IP reputation or serve different content by country, residential IPs — real consumer connections — are what get through and let you sample the right geography.
Rotating or sticky — which should I use?
Use client.proxy() (rotating, a fresh IP per request) for stateless high-volume reads like price checks or SERP snapshots. Use client.session() (sticky, one pinned IP for a set number of minutes) the moment a login, cart, cookie, or multi-step flow is involved.
Does the SDK work with my HTTP client?
Yes. It returns .proxies for requests and httpx, .url for undici, axios, or got, and .for_playwright() / .forPlaywright() for Playwright. It is a thin URL builder, so it stays out of your HTTP stack's way.
What is the difference between the Premium and Elite tiers?
Premium targets by country. Elite adds city and ISP targeting for fingerprint-sensitive work — pass tier='elite' on the call when you need that precision.
Is web scraping legal?
Scraping public data is broadly permissible, but you must respect each site's robots.txt, rate limits, and terms of service, and avoid personal or copyrighted data you do not have rights to. See our guide on web scraping ethics and best practices.
Share this article

Guides, integrations & docs

Continue reading

Scrape with real residential IPs

Install proxy-builder-sdk, drop in your credentials, and route Node or Python through country-targeted residential proxies in minutes. New accounts get a free bandwidth allowance — no card.

Back to all articles