How to Use ProxyOmega Proxies with Puppeteer
Puppeteer is the de-facto Node.js library for driving headless Chromium. It is widely used for scraping, screenshotting and end-to-end testing, and any of those workflows quickly hit rate limits without a rotating proxy in front of them. This guide shows how to connect Puppeteer to ProxyOmega in three lines, then rotate sessions and target a country.
Quick start
Use the Premium Unlimited endpoint below — it accepts the username-modifier syntax used throughout this guide. Other plans use the same code shape with a different host and port (see the endpoint table at the bottom).
// npm install puppeteer
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch({
headless: 'new',
args: ['--proxy-server=http://premium.proxyomega.com:8000']
});
const page = await browser.newPage();
await page.authenticate({
username: '<USERNAME>',
password: '<PASSWORD>'
});
await page.goto('https://api.ipify.org');
console.log(await page.content());
await browser.close();
})();Rotation: sticky session vs rotating
Append -session-<id>-ttl-<seconds> to your username to hold the same exit IP. Drop the suffix entirely for a fresh IP on every request.
// Rotating: new IP on every request — omit any session suffix
await page.authenticate({ username: '<USERNAME>', password: '<PASSWORD>' });
// Sticky: hold the same IP for N seconds by appending -session-<id>-ttl-<seconds>
await page.authenticate({
username: '<USERNAME>-session-checkout-ttl-600',
password: '<PASSWORD>'
});
// Same IP for the next 600 seconds across this Puppeteer session.Country targeting
Add -country-XX (ISO 3166 alpha-2) to your username. State and city modifiers are supported on Premium Unlimited, Platinum and Mobile.
// Append -country-XX to the username. ISO 3166 two-letter codes.
const browser = await puppeteer.launch({
args: ['--proxy-server=http://premium.proxyomega.com:8000']
});
const page = await browser.newPage();
await page.authenticate({
username: '<USERNAME>-country-de',
password: '<PASSWORD>'
});
await page.goto('https://api.ipify.org');Authentication: username/password vs IP whitelist
Two ways to authenticate. Username/password is set on every request and is what every example in this guide uses. IP whitelist is configured in the ProxyOmega dashboard — once your runner IP is listed, drop the credentials from the proxy URL and the connection is authorised by source IP.
Puppeteer cannot send Proxy-Authorization headers on the launch flag, so you must use page.authenticate(). If you prefer IP whitelisting, add your server IP in the dashboard and pass the proxy URL without credentials.
Common errors and fixes
Wrong username or password, or the credentials contain a special character that was not URL-encoded. Re-copy from the dashboard.
Either the runner IP is not on your whitelist (if you use IP auth) or your network blocks outbound on the proxy port. Test with curl first.
Residential exits sometimes have tail latency. Raise client timeout to 30–60 s and enable retry. If timeouts persist across many sessions, the target is rate-limiting your country — switch country.
You have a -session- suffix in your username, or HTTP keep-alive is reusing the connection. Drop the session suffix and disable keep-alive on the client to force new exits.
Recommended plan
All endpoints
| Plan | Host | Port | Notes |
|---|---|---|---|
| Budget Unlimited | residential.proxyomega.com | 10000–10099 | Per-port country / rotation set in the dashboard. No username suffixes. |
| Premium Unlimited | premium.proxyomega.com | 8000 | Username modifiers: -country-XX, -session-{id}-ttl-{seconds}. |
| Platinum | platinum.proxyomega.com | 20228 | ASN / state / city targeting via username modifiers. |
| Mobile | mobile.proxyomega.com | 20229 | Real 4G/5G carrier IPs. Same username modifier syntax. |
| IPv6 | ipv6.proxyomega.com | 9000 | IPv6 exits, supports UDP_ASSOCIATE. |
FAQ
Why is Puppeteer ignoring my proxy credentials?
Chromium does not accept user:pass embedded in --proxy-server. You must call page.authenticate() after newPage() (or whitelist the source IP in the dashboard and drop credentials entirely).
How do I rotate IP per page navigation?
Drop the -session- suffix from the username. Each new TCP connection then exits via a fresh IP. For one-IP-per-page, also call browser.createIncognitoBrowserContext() per request.
Does Puppeteer support SOCKS5?
Yes. Use --proxy-server=socks5://host:port. ProxyOmega exposes HTTP CONNECT on the standard ports above; if you need SOCKS5 specifically, contact support.
Can I run multiple proxies in parallel?
Launch one browser per proxy (the proxy is browser-scoped, not page-scoped). For higher throughput use a worker pool, one Chromium per worker.