Connect Playwright or Puppeteer to Zenrows Browser

Zenrows Browser, the browser for agents, is a cloud Chrome that your scripts and AI agents drive over the Chrome DevTools Protocol (CDP). Residential IPs and anti-bot handling are built in, so you keep your Playwright or Puppeteer code and change one line: the browser you connect to. Uses: Browser with proxy_country, proxy_region and session_ttl

Ask your AI agent

With the Zenrows MCP server connected to Claude, Cursor or any MCP client, paste this prompt. Your agent picks the right Zenrows tools and settings on its own.

Use the Zenrows browser to open https://www.scrapingcourse.com/ecommerce/ as a visitor from the US,
tell me the page title and the first three product names, then close the browser session.

Connect and open a page

Every connection starts a new browser session. Use the WebSocket URL wss://browser.zenrows.com?apikey=YOUR_ZENROWS_API_KEY wherever you would launch a local browser, and close the browser when you finish so the session ends right away.

# pip install playwright
import asyncio
from playwright.async_api import async_playwright

CONNECTION_URL = "wss://browser.zenrows.com?apikey=YOUR_ZENROWS_API_KEY"

async def main():
    async with async_playwright() as p:
        browser = await p.chromium.connect_over_cdp(CONNECTION_URL)
        try:
            context = browser.contexts[0]
            page = await context.new_page()
            await page.goto("https://www.scrapingcourse.com/ecommerce/")
            print("Title:", await page.title())
        finally:
            await browser.close()  # ends the session and stops billing

asyncio.run(main())

// npm install playwright-core
import { chromium } from "playwright-core";

const connectionURL = "wss://browser.zenrows.com?apikey=YOUR_ZENROWS_API_KEY";

const browser = await chromium.connectOverCDP(connectionURL);
try {
  const page = await browser.contexts()[0].newPage();
  await page.goto("https://www.scrapingcourse.com/ecommerce/");
  console.log("Title:", await page.title());
} finally {
  await browser.close(); // ends the session and stops billing
}

// npm install puppeteer-core
import puppeteer from "puppeteer-core";

const browser = await puppeteer.connect({
  browserWSEndpoint: "wss://browser.zenrows.com?apikey=YOUR_ZENROWS_API_KEY",
});
try {
  const page = await browser.newPage();
  await page.goto("https://www.scrapingcourse.com/ecommerce/");
  console.log("Title:", await page.title());
} finally {
  await browser.close(); // ends the session and stops billing
}

# Print the WebSocket URL for your account, ready to paste into any CDP client
zenrows browser connect --proxy-country us

The browser arrives with a default context already open, so browser.contexts[0] (Python) or browser.contexts()[0] (Node.js) is the natural place for new pages. Installing playwright-core or puppeteer-core is enough: the browser runs in the cloud, so you skip the local browser download.

Choose the country, region and session lifetime

Add parameters to the WebSocket URL:

Parameter	Example	What it does
`proxy_country`	`proxy_country=us`	Residential IP from one country (ISO 3166-1 alpha-2 code)
`proxy_region`	`proxy_region=eu`	Residential IP from a world region: `eu`, `na`, `ap`, `sa`, `af`, `me`
`session_ttl`	`session_ttl=2m`	How long the session stays open: a duration such as `2m` or `10m` (default `3m`)

Use either proxy_country or proxy_region on a connection. This example opens a US session that lives for two minutes and prints the IP the target site sees:

import asyncio
from playwright.async_api import async_playwright

CONNECTION_URL = (
    "wss://browser.zenrows.com?apikey=YOUR_ZENROWS_API_KEY"
    "&proxy_country=us&session_ttl=2m"
)

async def main():
    async with async_playwright() as p:
        browser = await p.chromium.connect_over_cdp(CONNECTION_URL)
        try:
            page = await browser.contexts[0].new_page()
            await page.goto("https://www.scrapingcourse.com/ecommerce/")
            print("Title:", await page.title())
            await page.goto("https://httpbin.io/ip")
            print("IP:", await page.inner_text("body"))
        finally:
            await browser.close()

asyncio.run(main())

import { chromium } from "playwright-core";

const connectionURL =
  "wss://browser.zenrows.com?apikey=YOUR_ZENROWS_API_KEY&proxy_region=eu&session_ttl=2m";

const browser = await chromium.connectOverCDP(connectionURL);
try {
  const page = await browser.contexts()[0].newPage();
  await page.goto("https://www.scrapingcourse.com/ecommerce/");
  console.log("Title:", await page.title());
  await page.goto("https://httpbin.io/ip");
  console.log("IP:", await page.innerText("body"));
} finally {
  await browser.close();
}

import puppeteer from "puppeteer-core";

const browser = await puppeteer.connect({
  browserWSEndpoint: "wss://browser.zenrows.com?apikey=YOUR_ZENROWS_API_KEY&proxy_country=de",
});
try {
  const page = await browser.newPage();
  await page.goto("https://httpbin.io/ip");
  console.log("IP:", await page.$eval("body", (el) => el.innerText));
} finally {
  await browser.close();
}

Build the URL with the Zenrows Browser SDK

In Node.js, the @zenrows/browser-sdk package builds and validates the URL for you. sessionTTL takes seconds, for example 120, and proxy.location takes a ProxyCountry or ProxyRegion value.

Node.js (SDK)

// npm install @zenrows/browser-sdk playwright-core
import { ScrapingBrowser, ProxyCountry } from "@zenrows/browser-sdk";
import { chromium } from "playwright-core";

const scrapingBrowser = new ScrapingBrowser({ apiKey: "YOUR_ZENROWS_API_KEY" });
const connectionURL = scrapingBrowser.getConnectURL({
  proxy: { location: ProxyCountry.US },
  sessionTTL: 120,
});

const browser = await chromium.connectOverCDP(connectionURL);
try {
  const page = await browser.contexts()[0].newPage();
  await page.goto("https://www.scrapingcourse.com/ecommerce/");
  console.log("Title:", await page.title());
} finally {
  await browser.close();
}

new ScrapingBrowser() with no arguments reads the key from the ZENROWS_API_KEY environment variable.

Example output

From the US session above (the IP changes on every session):

Title: Ecommerce Test Site to Learn Web Scraping – ScrapingCourse.com
IP: {
  "origin": "158.46.196.221:41723"
}

The SDK example prints the title:

Title: Ecommerce Test Site to Learn Web Scraping – ScrapingCourse.com

Customize it

Change	How
A specific country	`&proxy_country=gb` (any ISO code), see Country targeting
A world region	`&proxy_region=ap`, see World region
A longer task	`&session_ttl=10m`, see Session TTL
A fresh, isolated profile	`await browser.new_context()` in the same session, see Log in once and reuse the session
Many browsers at once	Open one connection per task, see Run browser sessions in parallel
Faster page loads	`page.goto(url, wait_until="domcontentloaded")` returns as soon as the HTML is ready

Troubleshooting

page.goto times out waiting for load: a heavy asset on the page is still loading. Pass wait_until="domcontentloaded" (Python) or { waitUntil: "domcontentloaded" } (Node.js), then wait for the element you need.
The session closes in the middle of a long task: the session reached its lifetime. Raise session_ttl, for example &session_ttl=15m.
Usage keeps growing after your script ends: the session stayed open until its lifetime ran out. Call browser.close() in a finally block on every path.
401 when connecting: the API key in the URL is wrong or missing. Copy it again from the Browser dashboard.

Log in once and reuse the session

Save cookies after one login and start every next session signed in.

Run browser sessions in parallel

Open several cloud browsers at once with a concurrency limit.

Build a browser agent with Zenrows

Let Claude or GPT drive the browser with the Zenrows tools.

Let your AI assistant browse with Browser tools

Drive the browser from Claude, Cursor or the CLI.

Start Here

Foundations Course

Fetch Recipes

Extract Recipes

Crawl Recipes

Batch Recipes

Browser Recipes

Pipelines

Use Cases

By Surface

Production

Connect Playwright or Puppeteer to Zenrows Browser

Ask your AI agent

Connect and open a page

Choose the country, region and session lifetime

Build the URL with the Zenrows Browser SDK

Example output

Customize it

Troubleshooting

Log in once and reuse the session

Run browser sessions in parallel

Build a browser agent with Zenrows

Let your AI assistant browse with Browser tools

​Ask your AI agent

​Connect and open a page

​Choose the country, region and session lifetime

​Build the URL with the Zenrows Browser SDK

​Example output

​Customize it

​Troubleshooting

​Related recipes

Log in once and reuse the session

Run browser sessions in parallel

Build a browser agent with Zenrows

Let your AI assistant browse with Browser tools

Ask your AI agent

Connect and open a page

Choose the country, region and session lifetime

Build the URL with the Zenrows Browser SDK

Example output

Customize it

Troubleshooting

Related recipes