Browser Connection (CDP)

Browser-as-a-Service exposes a single WebSocket endpoint that speaks the Chrome DevTools Protocol. Point Playwright or Puppeteer at it and a browser is provisioned automatically — no session to create, inspect, or delete.

wss://browser.omniscrape.io?apikey=YOUR_API_KEY

Authentication

Your API key is passed as the apikey query parameter (CDP clients connect by URL, so the key travels in the URL rather than a header). Keep the URL secret and build it on your backend.

const wsUrl = `wss://browser.omniscrape.io?apikey=${process.env.OMNISCRAPE_KEY}`;

Query parameters

Parameter	Required	Default	Description
apikey	Yes	—	Your API key.
proxy_country	No	auto	ISO country code to route through, e.g. us, de, gb.
render_media	No	false	Load images/fonts/media. true is billed at the higher rate.
session_id	No	—	Reuse the same IP across reconnects (sticky).

Lifecycle

1. Connect — connectOverCDP(wsUrl) provisions a fresh browser and starts the meter.
2. Drive — use the full Playwright/Puppeteer API: navigate, click, type, evaluate, screenshot.
3. Disconnect — browser.close() (or dropping the socket) tears down the browser and finalizes billing.

There are no REST calls to create or delete sessions — the connection is the session.

Example

import { chromium } from "playwright";

const wsUrl = `wss://browser.omniscrape.io?apikey=${process.env.OMNISCRAPE_KEY}&proxy_country=us`;

const browser = await chromium.connectOverCDP(wsUrl);
try {
  const page = await browser.newPage();
  await page.goto("https://example.com");
  console.log(await page.title());
} finally {
  await browser.close(); // always close to stop billing
}

Billing

Billed by connection time:

Mode	Rate
Standard (render_media=false)	$0.02 / minute
Full media (render_media=true)	$0.10 / minute

The meter runs from connect to disconnect. Always close() when done. See Pricing.

Errors

The WebSocket connection is rejected before upgrade when:

Reason	Cause
401	Missing or invalid apikey.
402	Balance too low to start a browser.
429	Concurrent browser limit reached for your plan.

Your CDP client surfaces these as a failed connection. Verify the apikey and account balance, then retry.