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-Keyinstead: 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
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
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.
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.
| Code | Reason |
|---|---|
| 1000 | You closed the browser. |
| 1011 | Credits could not be checked. Reconnect. |
| 1012 | Siftzo is restarting a server. Reconnect. |
| 4001 | The session reached its timeout. |
| 4002 | Your credits are used up. |
| 4003 | No CDP messages in either direction for 60 seconds. |
| 4004 | Chrome used more than its memory limit (about 1.3 GB). |
| 4005 | Chrome 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:andabout:blankcan be opened.file://andchrome://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
countryandsessioninstead. - A few CDP domains that describe or touch the host (
SystemInfo,Tethering,Extensions) are not available. Refused commands get a CDP error starting withSiftzo:.
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.