Skip to main content
Connect Playwright or Puppeteer to a dedicated cloud browser over the Chrome DevTools Protocol (CDP) for multi-step automation that goes beyond single-page fetching. AdsCrawl provisions a real Chromium instance behind a residential proxy, returns a cdpBaseUrl you connect to directly, and charges only for the time the session is active.

Full automation flow

1

Create a CDP session

Send a POST /cdp/sessions request with your desired browser settings. The API returns a sessionId and a cdpBaseUrl that includes an embedded data token.
Response:
2

Connect Playwright using cdpBaseUrl

Pass cdpBaseUrl directly to chromium.connectOverCDP(). Playwright handles the WebSocket handshake; you don’t need to construct any URLs manually.
3

Automate: navigate, click, fill, wait

Use the full Playwright API — page.goto(), page.fill(), page.click(), page.waitForSelector(), and everything else. The browser runs in AdsCrawl’s infrastructure, routed through the proxy you configured.
4

Collect your results

Read DOM content, take screenshots, capture network responses, or export cookies and storage — whatever your automation needs.
5

Close the browser and delete the session

Call browser.close() to release Playwright’s connection, then DELETE /cdp/sessions/:sessionId to terminate the cloud browser and stop billing.

TypeScript example

Session limits and 429 errors

Each API key has a maximum number of concurrent CDP sessions. Attempting to create a new session when the limit is reached returns 429:
List your active sessions to inspect what’s running before creating new ones:
Delete any sessions you no longer need, then retry.

Session timeouts

Set idleTimeoutMs to automatically terminate the session after a period of inactivity. This prevents runaway costs if your automation crashes before reaching the cleanup step. Values above the server cap are automatically clamped.
Use maxSessionMs as a hard wall-clock limit for long-running automations. Both timeouts are enforced server-side — no client-side keepalive is required.

Data token security

The cdpBaseUrl contains a data token that grants direct access to your browser session’s CDP WebSocket. Treat it like a credential: never log it, embed it in client-side code, or include it in URLs that appear in browser history. Keep it server-side only.

browserSettings reference

string
Managed proxy region. "GLOBAL" picks from 15 popular regions. A two-letter code (e.g. "US", "DE") prefers a trusted proxy with dynamic fallback. Cannot be combined with proxy.
object
Browser window size, e.g. { "width": 1440, "height": 900 }.
"random" | "custom"
Set to "random" for a server-selected realistic User-Agent string.
"windows" | "macos"
Operating system for random User-Agent selection. Defaults to "windows".
string
Browser locale, such as "en-US".
string
IANA timezone ID, such as "America/New_York".
cookies[]
Cookies injected into the browser context before any navigation.
fingerprint
Browser fingerprint settings. When omitted, canvas and webGlImage default to real; other signals use a coherent randomised profile.
proxy
Custom proxy configuration. Cannot be combined with countryCode.