Chrome DevTools Protocol (CDP)

The /devtools endpoints provide session management capabilities that follow the Chrome DevTools Protocol (CDP) ↗︎. These endpoints allow you to create persistent browser sessions, manage multiple tabs, and interact with browsers using CDP commands. This is useful for advanced automation, debugging, and remote browser control.

CDP endpoints can be accessed from any environment that supports WebSocket connections, including local development machines, external servers, and CI/CD pipelines. This means you can connect to Browser Run from Node.js scripts, Puppeteer, Playwright, or any CDP-compatible client.

Before you begin, create a custom API Token with Browser Rendering - Edit permission.

The Chrome DevTools Protocol (CDP) is a remote debugging protocol that allows you to instrument, inspect, debug, and profile Chromium-based browsers. It is the same protocol used by Chrome DevTools to control and monitor the browser. Popular browser automation libraries like Puppeteer and Playwright provide high-level APIs over the Chrome DevTools Protocol, making it easier to automate common tasks.

The browser sessions endpoints enable you to:

• Create and manage persistent browser sessions — Launch browser instances that remain active for extended periods
• Open, close, and list browser tabs (targets) — Manage multiple debuggable targets (pages, iframes, etc.) within a single browser instance
• Connect via WebSocket to send CDP commands — Automate browser actions programmatically
• View live browser sessions using Chrome DevTools UI — Debug and inspect remote browser sessions visually
• Integrate with existing CDP clients — Use standard CDP clients like Puppeteer or custom WebSocket implementations

Once you acquire a browser session, you can interact with it in two ways:

Connect to the WebSocket endpoint /devtools/browser to acquire a session and send CDP commands ↗︎ directly over the connection. This is the standard way to use CDP and works with any CDP client, including Puppeteer, Playwright, and MCP clients.

HTTP endpoints are also available to manage the browser lifecycle without using WebSockets. These follow the standard CDP HTTP endpoints ↗︎:

1. Create session — POST /devtools/browser
2. List tabs — GET /devtools/browser/{session_id}/json/list
3. Create tab — PUT /devtools/browser/{session_id}/json/new
4. Close tab — DELETE /devtools/browser/{session_id}/json/close/{target_id}
5. Close session — DELETE /devtools/browser/{session_id}

Check the API reference for the HTTP endpoints. The WebSocket endpoints and their parameters are documented in WebSocket endpoints.

Browser Run provides three WebSocket endpoints. Each endpoint requires an API token in the Authorization: Bearer <API_TOKEN> header.

Use this endpoint to acquire a browser session and connect to it:

wss://api.cloudflare.com/client/v4/accounts/{account_id}/browser-run/devtools/browser

Path parameters:

Query parameters:

Optional headers:

Use this endpoint to connect to an existing browser session:

wss://api.cloudflare.com/client/v4/accounts/{account_id}/browser-run/devtools/browser/{session_id}

Path parameters:

Query parameters:

Optional headers:

Use this endpoint to connect to a specific target or page:

wss://api.cloudflare.com/client/v4/accounts/{account_id}/browser-run/devtools/browser/{session_id}/page/{target_id}

Path parameters:

Optional headers:

If you have questions or encounter an error, see the Browser Run FAQ and troubleshooting guide.