CDP Extensions

Browserless-specific Chrome DevTools Protocol methods you call via cdp.send() on a page's CDP session in Puppeteer or Playwright. They extend standard CDP with live URLs, captcha solving, session reconnect, recording, file transfer, and page identification. Several also emit CDP events (listen with cdp.on()).

Availability depends on how the browser was launched: live URLs, captcha solving, reconnect, and recording are each gated on their own feature flag / query param and return an error in the result when unavailable.

Usage

const browser = await puppeteer.connect({ browserWSEndpoint: '...' });
const [page] = await browser.pages();
const cdp = await page.createCDPSession();

// Command: get a live URL for debugging
const { liveURL } = await cdp.send('Browserless.liveURL', { quality: 70 });

// Event: react to an auto-detected captcha
cdp.on('Browserless.captchaFound', ({ type, status }) => {});

Commands

Browserless.liveURL

Mints a temporary URL that opens a live, interactive view of the current page in any browser. For debugging, QA, or human-in-the-loop workflows. Requires live URLs to be enabled for the session.

Call via CDP: cdp.send('Browserless.liveURL', { quality: 70 })

Returns: { error, liveURLId, liveURL } (error is null on success).

Parameter	Type	Default	Description
quality	number	70	Stream image quality (1-100).
type	string	"jpeg"	Stream frame image format.
timeout	number	30000	How long (ms) the minted URL stays valid.
interactable	boolean	true	Allow the viewer to click/type into the page.
resizable	boolean	true	Allow the viewer to resize the viewport.
showBrowserInterface	boolean	false	Show browser chrome around the page.
compressed	boolean	true	Compress the stream.
emulateComponents	boolean	true	Emulate UI components in the stream.

Browserless.closeLiveURL

Closes a live URL opened with liveURL, freeing server resources. Called automatically when the session ends.

Call via CDP: cdp.send('Browserless.closeLiveURL', { liveURLId })

Returns: { error, liveURLId }.

Parameter	Type	Description
liveURLId	string	Required. The liveURLId returned by liveURL.

Browserless.solveCaptcha

Detects a CAPTCHA on the current page and attempts to solve it via a third-party solving service (reCAPTCHA v2/v3, hCaptcha, Cloudflare Turnstile, and more). Requires captcha solving to be available for the session.

Call via CDP: cdp.send('Browserless.solveCaptcha')

Returns: { ok, captchaFound, solveAttempted, solved, token?, message?, error? }.

Browserless.reconnect

Returns a WebSocket URL for reconnecting to this browser session after disconnecting. The browser stays alive server-side for timeout ms. Requires reconnect to be enabled; timeout is capped by the plan's maximum reconnect time.

Call via CDP: cdp.send('Browserless.reconnect', { timeout: 60000 })

Returns: { auth, error, browserWSEndpoint } (browserWSEndpoint is null on error).

Parameter	Type	Description
timeout	number	How long (ms) to keep the browser alive after disconnect. Defaults to the session timeout.
auth	string	Optional auth token echoed back and required on the reconnect handshake.

Browserless.pageId

Returns Browserless's stable identifier for the current page target, useful for routing and correlating a page across reconnects.

Call via CDP: cdp.send('Browserless.pageId')

Returns: { pageId: '...' }.

Browserless.startRecording

Starts server-side video recording of the page. Requires connecting with ?record=true. Refused after a credential has been filled on the session (the recording could capture the secret).

Call via CDP: cdp.send('Browserless.startRecording', { width, height })

Returns: { recording, error? }.

Parameter	Type	Description
width	number	Optional recording width.
height	number	Optional recording height.

Browserless.stopRecording

Stops the recording started with startRecording and returns the video. Requires ?record=true.

Call via CDP: cdp.send('Browserless.stopRecording', { encoding: 'base64' })

Returns the encoded recording, or { error }.

Parameter	Type	Description
encoding	string	"binary" or "base64".

Browserless.stopSessionRecording

Stops rrweb session-replay capture, then processes and uploads the events. Requires connecting with ?replay=true.

Call via CDP: cdp.send('Browserless.stopSessionRecording')

Returns: { error } (null on success).

Browserless.uploadFile

Uploads one or more files into a file <input> on the page, matched by selector. Total decoded size is capped per request.

Call via CDP: cdp.send('Browserless.uploadFile', { selector, files })

Returns: { ok, error? }.

Parameter	Type	Description
selector	string	Required. CSS selector for the file input.
files	array	Required. Objects of { name, content, mimeType? } where content is base64 and mimeType is inferred from name if omitted.

Browserless.setDownloadEnabled

Toggles streaming of completed downloads back to the client as Browserless.fileDownloaded events. Off by default, so download bytes never flow unless you opt in.

Call via CDP: cdp.send('Browserless.setDownloadEnabled', { enabled: true })

Returns: { ok, enabled }.

Parameter	Type	Description
enabled	boolean	Whether to emit fileDownloaded events.

Events

Subscribe with cdp.on('<EventName>', handler).

Browserless.heartbeat

Periodic keep-alive emitted on each attached session at the server's heartbeat interval. No params.

Browserless.captchaFound

Emitted when a CAPTCHA is auto-detected on a page.

Params: { type, status } — status is "solving" when auto-solve is on, otherwise "found".

Browserless.captchaAutoSolved

Emitted after an auto-solve attempt completes (only when auto-solving is enabled).

Params: the solve result { found, solved, token, time, error? }.

Browserless.fileDownloaded

Emitted when a download completes, if enabled via setDownloadEnabled. Mirrored to every attached session.

Params: { filename, mimeType, size, data } (data base64), or { filename, mimeType, size, error: 'FileTooLarge', maxBytes } when the file exceeds the transfer limit.

Browserless.liveComplete

Emitted when a live URL viewer session ends. No params.