Live preview & recording

Watch an API V4 run in real time or record its browser.

Wait for browser.ready as soon as you create the run so the URL is available while the browser is live. A follow-up that reuses the session’s open browser emits browser.reattached, with the same live_view_url field, instead. The SDK wait for browser.ready returns either event; see browser events.

Python

from browser_use_sdk.v4 import BrowserUse

client = BrowserUse()
run = client.runs.create("Find the top Hacker News story")
ready = client.runs.wait_for_event(run.id, "browser.ready", interval=3)
print(ready.data["live_view_url"])

These examples poll immediately, then every three seconds (Python uses seconds; TypeScript uses milliseconds). Setting the interval explicitly also reduces traffic on older SDK releases whose event default is one second. Event reads share the project’s general request budget; stagger concurrent waits and leave room for other calls.

The helper advances the event cursor and times out after five minutes. See run events for the full event stream and custom polling.

Embed the live browser

<iframe
  src="{LIVE_VIEW_URL}"
  style="width: 100%; aspect-ratio: 16/9; border: 0;"
  allow="autoplay"
></iframe>

The URL is hosted on live.browser-use.com. Add that origin to your Content Security Policy’s frame-src directive when needed. Treat the URL as a credential: anyone with it can interact with the active browser.

Read-only embeds

To let users watch without clicking, typing, or scrolling the remote page, make the iframe non-interactive in your application. This works with V4 today and provides the same UI-level restriction as the V2 dashboard’s view-only mode. No API request parameter is needed.

Use ready.data.live_view_url from the V4 browser.ready event above. For REST integrations, read that event from GET /api/v4/runs/{run_id}/events. Standalone POST /api/v4/browsers responses return the URL as liveUrl.

<div inert>
  <iframe
    src="{LIVE_VIEW_URL}"
    title="Live browser preview"
    tabindex="-1"
    style="width: 100%; aspect-ratio: 16/9; border: 0; pointer-events: none;"
    allow="autoplay"
  ></iframe>
</div>

The preview keeps streaming. The inert wrapper prevents focus and keyboard input, while pointer-events: none blocks pointer interaction with the iframe. Use a browser that supports inert. To allow human takeover, remove inert, tabindex="-1", and pointer-events: none when your application enables control.

ui=false only hides the tabs and toolbar; it does not disable interaction. View-only embeds are a UI restriction, not a server-enforced permission. Anyone who opens the live URL directly or uses the underlying CDP URL can still control the browser. Keep both URLs private.

Read-only URL option

The live viewer supports readOnly=true. It blocks browser controls and page input while keeping connection and screencast Retry buttons usable:

const previewUrl = new URL(liveViewUrl);
previewUrl.searchParams.set("readOnly", "true");
previewUrl.searchParams.set("ui", "false"); // Optional: hide tabs and toolbar.
iframe.src = previewUrl.toString();

It is a viewer URL option, not a field in the browser or run creation request. Omitting it or setting it to false keeps the viewer interactive, and /session/{id} links preserve it when redirecting. Like the wrapper, it prevents UI input without changing CDP access permissions.

Recording

Enable recording when the run creates its browser:

Python

run = client.runs.create(
    "Test the checkout flow",
    browser_settings={"record": True},
)

The MP4 becomes available in the Dashboard after the browser stops. After a run completes, its browser stays open about 2 minutes, or for the run’s keepAlive seconds, for follow-ups; finishing the run alone does not finalize the video. Once you no longer need the browser, stop it with PATCH /api/v4/browsers/{id} and {"action":"stop"}, then allow time for upload and processing.

API runs default to recording off. Zero Data Retention (ZDR) projects never record, even if recording was requested; stopping the browser cannot produce a recording when ZDR is active. See Zero Data Retention for result retrieval and cleanup timing.

For standalone browsers, use enableRecording: true in POST /api/v4/browsers (enable_recording=True in the Python SDK). For agent-created browsers, use browserSettings.record: true as above. These are different request shapes.

After stopping a standalone browser, poll GET /api/v4/browsers/{id} for recordingUrl. The stop response and browser-list response do not contain a ready recording URL. Stop polling when recordingAvailable is false; the video cannot appear for that session. If the installed SDK does not expose that field, use the REST response and the current API reference.