Integration Scraping framework

Puppeteer Proxy Setup

Puppeteer automates headless Chrome, which is ideal for scraping JavaScript-heavy sites but instantly recognizable when every request leaves from one datacenter IP. Routing Puppeteer through ProxyOmega residential proxies gives each browser a real consumer address, with authentication handled by page.authenticate. This guide covers the exact launch flags and session patterns you need.

Get started All integrations

200+countries
1.5M+residential IPs
SOCKS5on every port

Puppeteer

What is Puppeteer?

Puppeteer is a Node.js library maintained by the Chrome team that controls headless (or headful) Chrome and Chromium over the DevTools Protocol. It launches a browser, navigates pages, runs JavaScript, fills forms, intercepts network requests, and captures screenshots or PDFs, which makes it a common choice for scraping dynamic sites and automating browser workflows.

Compared with a multi-browser tool, Puppeteer is tightly focused on Chromium, which keeps its API small and its DevTools integration deep. You launch a browser, open a page, and interact with it through a promise-based API. Proxy configuration happens at two points: the --proxy-server launch flag tells Chrome where to route traffic, and page.authenticate supplies the username and password for an authenticated proxy.

Because Puppeteer runs a genuine Chrome build, it passes most JavaScript and rendering checks. The weak point is the network layer: Chrome opens many connections to fetch a page and its assets, and from a datacenter IP that pattern is an obvious automation signal.

Puppeteer

Why Puppeteer needs residential proxies

A single headless Chrome instance fetches a page plus its scripts, styles, images, and API calls from one IP in a rapid burst. Anti-bot systems tie that footprint to the source address, and datacenter ranges are the first thing they block. Residential IPs remove that easy signal.

ProxyOmega gives each Puppeteer instance a real consumer IP and lets you rotate or pin it. With a residential address behind a real Chrome fingerprint, protected sites are far more likely to return full content instead of a challenge.

Avoid datacenter blocks

Residential IPs sidestep the datacenter blocklists that headless Chrome hits on protected targets, so pages return content instead of block screens or CAPTCHAs.

One IP per browser

Launch multiple browser instances, each with its own proxy username, to scrape in parallel from different residential IPs without sessions colliding.

Regional content

Geo-target the exit IP so the site serves local pricing, language, and inventory. Combine with a matching Accept-Language header for consistency.

Stateful automation

Hold one IP across a login and the pages that follow with a sticky session, so the target does not see the source address change mid-flow.

Puppeteer

Using ProxyOmega with Puppeteer

Puppeteer needs two pieces: pass the proxy host and port to Chrome with the --proxy-server launch argument, then supply credentials with page.authenticate before your first navigation. Chrome does not accept username:password in the --proxy-server flag, so page.authenticate is the correct place for auth. The username carries targeting parameters (here -country-us) and the password is your dashboard API key.

For Budget Unlimited, use residential.proxyomega.com with any port from 10000 to 10199. Each port serves HTTP, HTTPS, and SOCKS5 on the same port, so there is no separate SOCKS5 endpoint to configure. Call page.authenticate on every page you open in that browser.

const puppeteer = require("puppeteer");

// Targeting params attach to the username, dash-separated.
const USERNAME = "user123-country-us";
const PASSWORD = "your_dashboard_api_key"; // account API key

(async () => {
  const browser = await puppeteer.launch({
    headless: "new",
    args: ["--proxy-server=http://residential.proxyomega.com:10000"],
  });

  const page = await browser.newPage();

  // Chrome ignores credentials in --proxy-server, so auth here.
  await page.authenticate({ username: USERNAME, password: PASSWORD });

  await page.goto("https://api.ipify.org?format=json", {
    waitUntil: "domcontentloaded",
    timeout: 60000,
  });

  const body = await page.evaluate(() => document.body.innerText);
  console.log(body); // shows your residential exit IP

  await browser.close();
})();

Puppeteer

Rotating vs sticky sessions

The proxy is set per browser launch, so the natural rotation pattern in Puppeteer is a new browser instance (or a new username) per task. On Budget Unlimited the pool also rotates on the dashboard interval, so fresh launches generally land on fresh IPs.

When a flow spans multiple pages and the target ties state to the source IP, hold one address with a sticky session. Add -session-<id> to the username in the page.authenticate call, optionally with -ttl-<minutes>, and reuse that id for the browser's lifetime. Use a new id to get a new IP.

Rotating per launch

Start a fresh browser (or omit the session parameter) for each task. With the dashboard rotation interval, each launch loads from a different residential IP, ideal for scraping many independent pages.

Sticky per session

Add -session-run7-ttl-20 to the username to hold one IP for twenty minutes across a login and its follow-up navigation. Keep the browser open for the flow, then rotate the id.

Puppeteer

Which ProxyOmega plan to pick

Headless Chrome downloads full pages and assets, so bandwidth and concurrency matter. Choose the plan that matches your load and targeting needs.

Workload	Plan	Why
General dynamic scraping	Budget Unlimited (:10000)	Unlimited bandwidth handles full page loads; rotating pool plus country targeting covers most jobs.
Many parallel browsers or heavy pages	Premium Unlimited (:8000)	Dedicated 200Mbps-1Gbps throughput keeps concurrent Chrome instances fast.
City/state/ASN targeting	Platinum (:20228)	Pay-per-GB with the finest geo-targeting for localized rendering.
Mobile-specific targets	Mobile (:20229)	Real 4G/5G IPs for sites that treat carrier traffic differently.
Fixed whitelisted IP	Static ISP (:30000)	One stable US (Dallas) address for targets requiring a consistent source IP.

Puppeteer

Troubleshooting

Puppeteer proxy failures usually appear as navigation errors or repeated auth prompts. Check these first.

407 Proxy Authentication Required

Confirm you called page.authenticate before goto, that the password is your dashboard API key, and that the username's targeting parameters are valid for the plan. A parameter that does not apply to the product rejects the whole username, so verify the suffix.

net::ERR_TUNNEL_CONNECTION_FAILED

Chrome could not reach the proxy. Check the --proxy-server host and use a port in the 10000-10199 range for Budget Unlimited. Do not put credentials in the flag; keep them in page.authenticate.

Auth prompt keeps reappearing

page.authenticate applies per page. If you open new pages or popups, call it on each one. For many pages, wrap browser.newPage so authentication is always applied.

Connection reset / refused

If IP whitelisting is enabled on your account, add the machine's public IP to the allowlist in the dashboard. Once whitelisting is on, requests from other addresses are dropped after auth.

FAQ

Frequently asked questions

Why can't I put the username and password in --proxy-server?

Chrome ignores credentials embedded in the --proxy-server flag. Puppeteer's supported way to authenticate is page.authenticate({ username, password }), called before your first navigation on each page.

Do I need a separate SOCKS5 proxy port?

No. Every ProxyOmega port serves HTTP, HTTPS, and SOCKS5 on the same port. For HTTP CONNECT (the Puppeteer default) just use the http:// scheme in --proxy-server.

How do I target a specific country?

Append -country-<code> to the username you pass to page.authenticate, for example user123-country-fr. Combine it with a matching Accept-Language header for a consistent locale.

How do I keep the same IP across a login flow?

Add -session-<id> to the username, optionally with -ttl-<minutes>. Reuse the same id for the browser's lifetime to hold one IP; use a new id for a fresh address.

Can I run several browsers with different IPs at once?

Yes. Launch multiple browser instances, each authenticating with its own username (or session id), and they scrape in parallel from different residential IPs.

What is the proxy password?

It is your account API key from the ProxyOmega dashboard, not your login password. Keep it in an environment variable rather than hardcoded.

Run Puppeteer behind real residential IPs Start routing today.

1.5M+ IPs across 200+ countries, SOCKS5 on every port.

Get started