Guides

Browser API

Connect Playwright, Puppeteer or any other CDP client to a fresh Chrome in Siftzo's cloud. You keep your own browser code; Siftzo runs the browser and sends its traffic through residential proxies.

Connecting

Open a WebSocket to wss://api.siftzo.com/v1/browser. Every connection starts a new Chrome with an empty profile, and closing the connection ends it. Nothing is kept between sessions.

tokenstring
Your API key, for CDP clients that cannot set headers. If yours can, send X-API-Key instead: URLs end up in more logs than headers do.
countryISO 3166-1 alpha-2
Exit country for all of the browser's traffic, for example de.
sessionstring, 1–64 of [A-Za-z0-9_]
Keeps the exit IP. The same name gives the same IP as in /v1/scrape (see Proxies & sessions). Without it, every browser session gets its own IP.
timeoutinteger, 60–900default 300
The longest the session may run, in seconds. Siftzo closes it when the time is up.

Playwright

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

const browser = await chromium.connectOverCDP(
  `wss://api.siftzo.com/v1/browser?token=${process.env.SIFTZO_API_KEY}&country=de`,
);
const context = browser.contexts()[0] ?? (await browser.newContext());
const page = await context.newPage();
await page.goto("https://quotes.toscrape.com/js/");
console.log(await page.locator(".quote .text").allTextContents());
await browser.close();

Playwright for Python works the same way with p.chromium.connect_over_cdp(url). Playwright can also send the key as a header: connectOverCDP(url, { headers: { "X-API-Key": key } }).

Puppeteer

Node.js
import puppeteer from "puppeteer-core";

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://api.siftzo.com/v1/browser?token=${process.env.SIFTZO_API_KEY}&session=cart_1`,
});
const page = await browser.newPage();
await page.goto("https://books.toscrape.com/");
console.log(await page.title());
await browser.close();

Screenshots

Take screenshots with your client's own methods, such as Playwright's and Puppeteer's page.screenshot(), or Page.captureScreenshot over raw CDP. The browser loads images, fonts and CSS, so a screenshot shows the page as a visitor sees it, and fullPage: true captures the whole page, not only the viewport.

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

const browser = await chromium.connectOverCDP(
  `wss://api.siftzo.com/v1/browser?token=${process.env.SIFTZO_API_KEY}`,
);
const context = browser.contexts()[0] ?? (await browser.newContext());
const page = await context.newPage();
await page.goto("https://books.toscrape.com/");
await page.screenshot({ path: "page.png", fullPage: true });
await browser.close();

The image comes back over the WebSocket and is saved on your machine. For a single screenshot without your own browser code, /v1/scrape has screenshot: true, which also takes the whole page with screenshot_full_page: true.

Credits

A session costs 1 credit per started 10 seconds, counted from the moment the connection opens until it closes. A 25-second session costs 3 credits, a full 5-minute session 30. A session that fails to start costs nothing.

You need at least 6 credits left to start a session. Siftzo sets aside one minute (6 credits) at a time while the session runs. If your credits run out, the session ends when the last paid minute is over. Each open session uses one slot of your plan's concurrency, also while it is idle (see Rate limits & credits).

Limits and closing

Siftzo closes the WebSocket with a close code that says why. Before closing, it closes Chrome, so your client sees its pages go away first.

Close codes
CodeReason
1000You closed the browser.
1011Credits could not be checked. Reconnect.
1012Siftzo is restarting a server. Reconnect.
4001The session reached its timeout.
4002Your credits are used up.
4003No CDP messages in either direction for 60 seconds.
4004Chrome used more than its memory limit (about 1.3 GB).
4005Chrome stopped unexpectedly.

Before a session starts you get the same HTTP errors as on the rest of the API, for example 401, 402 credits_exhausted, 429 concurrency_limit and 503 overloaded when every browser is busy (see Errors).

What the browser cannot do

The browser is a real Chrome with its sandbox on, and you control it fully over CDP, with a few exceptions that keep it from reaching the machine it runs on:

  • Only http, https, data: and about:blank can be opened. file:// and chrome:// pages are blocked.
  • Downloads are blocked, and local files cannot be uploaded or dragged into a page.
  • All traffic goes through Siftzo's proxies, so per-context proxies are refused. Use country and session instead.
  • A few CDP domains that describe or touch the host (SystemInfo, Tethering, Extensions) are not available. Refused commands get a CDP error starting with Siftzo:.

Unlike /v1/scrape, the Browser API always loads images, fonts and media, and does not retry or switch exit IPs on blocks. That traffic is part of the session, so block resources you do not need with page.route to keep pages fast.