Live View

Live View lets you see and interact with a remote Browser Run session in real time. This is useful for debugging automation scripts, monitoring what a browser is doing, or manually stepping in when a task requires human intervention (see Human in the Loop).

Live View is available for any Browser Session, including sessions created with Puppeteer, Playwright, or the Chrome DevTools Protocol (CDP) endpoints.

A browser session is one remote Chrome instance. A session can contain multiple tabs. CDP calls each debuggable item a target, and a page target usually represents one browser tab. Live View connects to a page target.

Open Live View from the Cloudflare dashboard or with a generated devtoolsFrontendUrl. A generated URL opens Cloudflare's hosted interface in any browser. Chrome users can instead open the connection in Chrome DevTools.

In the Cloudflare dashboard, go to the Browser Run page and select the Live Sessions tab. This shows all active browser sessions in your account. Expand a session to see its tabs, then select Open to open the Live View for that tab.

When you create a session with targets=true or list a session's targets, the API response includes a devtoolsFrontendUrl for each page target. Open this URL in any browser to watch or control that tab through Cloudflare's hosted interface. The generated URL uses live.browser.run; you do not visit that hostname directly.

The hosted UI supports three viewing modes, controlled by the mode parameter in the URL:

Browser Run supports CDP, the protocol that powers Chrome DevTools. If a generated devtoolsFrontendUrl starts with https://live.browser.run/ui/inspector?wss=, replace that prefix with devtools://devtools/bundled/inspector.html?wss=:

devtools://devtools/bundled/inspector.html?wss=live.browser.run/api/devtools/browser/SESSION_ID/page/TARGET_ID?jwt=...

Paste the updated URL into Chrome's address bar. Chrome opens its built-in DevTools interface for the remote tab. The devtools:// protocol works only in Chrome and supports only the devtools viewing mode.

The API examples in the following sections assume $ACCOUNT_ID is set and $CLOUDFLARE_API_TOKEN has Browser Rendering Write permission.

1. Create a browser session with targets=true to include its current page targets and generated Live View URLs in the response:

curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/browser-run/devtools/browser?keep_alive=600000&targets=true" \
	--request POST \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

{
	"sessionId": "1909cef7-23e8-4394-bc31-27404bf4348f",
	"targets": [
		{
			"description": "",
			"devtoolsFrontendUrl": "https://live.browser.run/ui/inspector?wss=live.browser.run/api/devtools/browser/1909cef7-.../page/8E598E99...?jwt=...",
			"id": "8E598E996530FB09E46A22B8B7754F7F",
			"title": "about:blank",
			"type": "page",
			"url": "about:blank",
			"webSocketDebuggerUrl": "wss://live.browser.run/api/devtools/browser/1909cef7-.../page/8E598E99...?jwt=..."
		}
	],
	"webSocketDebuggerUrl": "wss://api.cloudflare.com/client/v4/accounts/{account_id}/browser-run/devtools/browser/1909cef7-..."
}

The targets[].devtoolsFrontendUrl opens the hosted interface for a page. The targets[].webSocketDebuggerUrl connects a CDP client to that page. The top-level webSocketDebuggerUrl connects a CDP client to the browser session.

2. Find the page target you want by its title or url. Copy its devtoolsFrontendUrl and open it in your browser. A new session initially contains an about:blank page.

If you have a running session and want to connect to it:

1. List your active sessions and copy the ID of the session you want to view:

   curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/browser-run/devtools/session" \
   	--request GET \
   	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

2. Using the session ID, list the targets in that session:

   curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/browser-run/devtools/browser/$SESSION_ID/json/list" \
   	--request GET \
   	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

   [
   	{
   		"id": "110850A800BDB8B593CDDA30676635CF",
   		"type": "page",
   		"url": "https://example.com",
   		"title": "Example Domain",
   		"description": "",
   		"devtoolsFrontendUrl": "https://live.browser.run/ui/view?wss=live.browser.run/api/devtools/browser/28d75446-.../page/110850A8...?jwt=...",
   		"webSocketDebuggerUrl": "wss://live.browser.run/api/devtools/browser/28d75446-.../page/110850A8...?jwt=..."
   	}
   ]

3. Copy the devtoolsFrontendUrl and open it in your browser.

Listing targets returns a default devtoolsFrontendUrl for every page target. Generate a custom URL to change its viewing mode, connection deadline, or viewer permissions.

The following optional parameters configure generated links:

The REST API response includes id, options, devtoolsFrontendUrl, and webSocketDebuggerUrl. Open the frontend URL in a browser or use the WebSocket URL with a CDP client. The Cloudflare.getLiveView CDP command returns devtoolsFrontendUrl.

A read-only Live View guardrail applies only to the generated connection. Other connections and automation scripts can still control the session. Session guardrails restrict HTTP and HTTPS destinations for the entire session and remain active for every Live View connection.

Use the Live View endpoint to generate a URL:

curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/browser-run/devtools/browser/$SESSION_ID/live_view" \
	--request POST \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"mode": "tab",
		"expiresInMs": 300000
	}'

To block viewer interaction, set guardrails to { "mode": "readonly" }:

curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/browser-run/devtools/browser/$SESSION_ID/live_view" \
	--request POST \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"mode": "tab",
		"guardrails": {
				"mode": "readonly"
		}
	}'

The link streams the session but blocks navigation, input, and JavaScript evaluation. The tab title starts with READ ONLY - .

CDP is Chrome's remote debugging protocol. Cloudflare.getLiveView is a Cloudflare extension that generates a Live View URL over an existing CDP connection. This Puppeteer example generates a URL for the current page:

export async function getLiveViewUrl(page) {
	const cdp = await page.createCDPSession();

	const { devtoolsFrontendUrl } = await cdp.send("Cloudflare.getLiveView", {
		mode: "tab",
		expiresInMs: 300000,
	});

	return devtoolsFrontendUrl;
}

import type { Page } from "@cloudflare/puppeteer";

export async function getLiveViewUrl(page: Page): Promise<string> {
	const cdp = await page.createCDPSession();

	const { devtoolsFrontendUrl } = await cdp.send("Cloudflare.getLiveView", {
		mode: "tab",
		expiresInMs: 300000,
	});

	return devtoolsFrontendUrl;
}

To use Live View for a human operator handoff, refer to the Human in the Loop workflow.