Sticky vs rotating proxy sessions in Playwright and how to set them up
Playwright can run dozens of separate browser identities from one process, each behind its own proxy. That's powerful. It's also where most setups go wrong, because the proxy decides whether a "user" keeps the same IP or gets a new one halfway through a task.
This guide covers how sticky and rotating sessions work, how to configure each one, and the Playwright proxy rotation patterns that hold up on real sites.
How sticky and rotating sessions differ
Most residential and mobile proxy services give you one gateway address instead of a list of IPs. You connect to that endpoint, and the gateway picks an exit IP from its pool. What you put in the username tells it how long to keep that IP.
-
Rotating session: no session ID in the username. The gateway can assign a fresh IP whenever a new connection opens.
-
Sticky session: you add a session ID, such as USERNAME-session-abc123. Every connection using that ID leaves through the same IP until the session expires.
The exact syntax varies by provider, so check your dashboard. Lifetimes vary too, from a few minutes to several hours.
Here's the part many guides skip. Rotation happens per connection, not per request. Browsers reuse connections heavily, so a "rotating" proxy won't give you clean per-request rotation inside Playwright. More on that below.
|
Sticky session |
Rotating session |
|
|---|---|---|
|
IP lifetime |
Fixed for the session window |
Changes on new connections |
|
Best for |
Logins, carts, checkouts, account work |
Independent public pages, large crawls |
|
Main risk |
One flagged IP affects the whole session |
IP can change mid-task and break state |
|
Typical config |
Session ID in the username |
Plain username |
Setting a proxy at browser vs context level
Playwright accepts a proxy in two places. According to the Playwright network docs, you can set it for the entire browser or for each browser context individually. HTTP(S) and SOCKS5 proxies both work.
The browser-level setup is the simplest:
const { chromium } = require('playwright');
const browser = await chromium.launch({
proxy: {
server: 'http://gateway.example.com:8000',
username: 'USERNAME',
password: 'PASSWORD',
},
});
Every context and page in that browser shares the proxy. That's fine for a single identity, but it's limiting.
Context-level proxies are where Playwright shines. A browser context is an isolated session with its own cookies, storage, and cache. Treat each context as one user, and give each user its own proxy:
const context = await browser.newContext({
proxy: {
server: 'http://gateway.example.com:8000',
username: 'USERNAME-session-user01',
password: 'PASSWORD',
},
});
One gotcha: some setups, notably Chromium on Windows, have ignored context proxies unless the browser was launched with a placeholder. The current Browser API docs don't list this requirement. Still, if every context shows the same IP, launch with proxy: { server: 'per-context' } and set the real proxy on each context.
Configuring sticky sessions for stateful flows
Use sticky sessions whenever the site remembers you between pages. Logins, carts, multi-step forms, and checkouts all qualify. So does running multiple accounts, where each account should keep a consistent IP over time.
The pattern is simple. One context, one session ID, one IP.
async function createStickyContext(browser, sessionId) {
return browser.newContext({
proxy: {
server: 'http://gateway.example.com:8000',
username: `USERNAME-country-us-session-${sessionId}`,
password: 'PASSWORD',
},
locale: 'en-US',
timezoneId: 'America/New_York',
});
}
Two details matter here.
First, make the session lifetime longer than the task. If a 15-minute flow runs on a 10-minute session, the IP changes partway through, and the site may log you out or show a challenge. Residential sessions can also end early when the device behind the IP goes offline, so build in a way to recover.
Second, match the context to the IP. Playwright lets you set locale, timezoneId, and geolocation for each context. A US IP paired with a browser that reports Berlin time is an easy mismatch for anti-bot systems to catch. Our guide to avoiding Cloudflare blocks with proxies covers more of these signals.
Playwright proxy rotation patterns that work
The tempting approach is to point a whole browser at a rotating gateway and let it switch IPs for you. Inside a browser, that gets messy.
A single page load opens several connections for scripts, images, and API calls. Since the gateway picks exits per connection, one page can load from several IPs. Meanwhile, kept-alive connections may hold one IP longer than you expect. You end up with rotation that's neither clean nor predictable.
That hurts on protected sites. Cloudflare says its cf_clearance cookie is tied to the visitor and device it was issued to. Pass a challenge on one IP, send the next request from another, and you'll often be challenged again.
The fix is to rotate at the context level. Keep a sticky session inside each context, and get a new IP by opening a new context with a new session ID:
const { randomUUID } = require('crypto');
for (const url of urls) {
const context = await createStickyContext(browser, randomUUID());
try {
const page = await context.newPage();
await page.goto(url);
// extract data here
} finally {
await context.close();
}
}
Each task gets a clean identity: a new IP, empty cookies, and no leftover state. For related pages, like a search page and its results, keep one context per batch and rotate between batches.
Add a retry rule too. If a page returns a 403, a 429, or a challenge page, close the context and retry on a fresh session ID. Don't keep hitting the target from the same IP.
Rotating contexts burns bandwidth, because every new context starts with an empty cache. Blocking heavy resources helps:
await context.route('**/*', (route) =>
['image', 'font', 'media'].includes(route.request().resourceType())
? route.abort()
: route.continue()
);
For more savings, see our guide to cutting proxy costs in web scraping.
Best practices and common mistakes
Most session problems come down to a few habits. Run through this list before you scale up:
-
Verify the exit IP first. Load an IP-check page at the start of each context and log the result. It's the fastest way to catch a context that silently skipped its proxy.
-
Test before you scale. Check speed, leaks, and IP quality on a small sample using our proxy testing checklist. For account work, check the sticky IP's reputation and fraud score before you log in.
-
Read errors before retrying. A 407 means the proxy rejected your credentials, often because of a typo in the session syntax. Tunnel failures have different causes. Our guide to fixing 407, 502, and tunnel errors walks through each one.
-
Track session age. Record when each session ID was created, and retire it before it expires mid-task.
-
Keep credentials out of logs. Session settings live in the username, so it's easy to dump full proxy URLs into your logs. Log the session ID alone.
-
Close your contexts. Forgotten contexts keep holding memory and open connections, and long runs slow down because of them.
The rule of thumb is short. Stay sticky inside a context, and rotate between contexts. Get that split right, and most of your proxy problems in Playwright go away.