Manage Live URLs over REST

Use the REST API to create, inspect, and close a Live URL without holding the browser's CDP connection. This is useful for orchestrators that hand a running browser to a person and need to monitor the handoff from another process.

All three requests require the API token that owns the running browser. Replace the variables below with your Browserless region, API token, and browser ID:

export BROWSERLESS_URL="https://production-sfo.browserless.io"
export TOKEN="YOUR_API_TOKEN_HERE"
export BROWSER_ID="YOUR_BROWSER_ID"

Create a Live URL

Send a POST request to /browser/{browserId}/live. The JSON body is optional.

curl --fail-with-body \
  --request POST \
  --url "$BROWSERLESS_URL/browser/$BROWSER_ID/live?token=$TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "interactable": true,
    "timeout": 600000,
    "quality": 70,
    "type": "jpeg",
    "resizable": false,
    "showBrowserInterface": true,
    "instructions": "Review the form, then submit it."
  }'

The response contains the URL to share and its ID. Treat liveURL as a secret: anyone with it can view the browser without an API token, and when interactable is true, they can also control it. Share it only through a trusted private channel and keep it out of logs and tickets.

{
  "liveURL": "https://production-sfo.browserless.io/live/index.html?i=abc123&t=600000&showBrowserInterface=true",
  "liveURLId": "abc123"
}

Save liveURLId for the status and close requests:

export LIVE_URL_ID="abc123"

Request options and defaults

Field	Type	Default	Description
interactable	boolean	false	Allow the viewer to click, type, and otherwise control the page.
timeout	integer	900000	Maximum lifetime in milliseconds. The effective lifetime cannot exceed 15 minutes or the remaining browser-session time.
quality	integer	70	JPEG quality from 1 through 100. A value below 100 requires type: "jpeg".
type	"jpeg" or "png"	"jpeg"	Stream image format.
resizable	boolean	false	Resize the remote viewport to follow the viewer.
showBrowserInterface	boolean	true	Show browser controls around the page.
instructions	string	none	Short instructions displayed to the viewer.

For the default view-only URL, omit the body entirely. A bodyless request without a Content-Type header is supported:

curl --fail-with-body \
  --request POST \
  --url "$BROWSERLESS_URL/browser/$BROWSER_ID/live?token=$TOKEN"

Get Live URL status

Send a GET request with the liveURLId returned by POST:

curl --fail-with-body \
  --request GET \
  --url "$BROWSERLESS_URL/browser/$BROWSER_ID/live/$LIVE_URL_ID?token=$TOKEN"

An active URL returns open. viewerCount is the number of currently connected viewers, and expiresAt is a Unix timestamp in milliseconds:

{
  "status": "open",
  "reason": null,
  "interactable": true,
  "viewerCount": 1,
  "expiresAt": 1791043200000
}

When its timeout elapses, the URL is expired:

{
  "status": "expired",
  "reason": "timeout",
  "interactable": true,
  "viewerCount": 0,
  "expiresAt": 1791043200000
}

Closing it through the REST API returns closed with a closed reason:

{
  "status": "closed",
  "reason": "closed",
  "interactable": true,
  "viewerCount": 0,
  "expiresAt": 1791043200000
}

If the viewer marks the handoff done, the reason is userDone:

{
  "status": "closed",
  "reason": "userDone",
  "interactable": true,
  "viewerCount": 0,
  "expiresAt": 1791043200000
}

If the viewer selects Couldn't finish, the status is closed with reason userFailed. Use this reason to distinguish a reported problem from a completed handoff.

Ended URL status remains available until the browser closes. After the browser closes, status requests return 404.

Close a Live URL

Send a DELETE request to close an active URL immediately:

curl --fail-with-body \
  --request DELETE \
  --url "$BROWSERLESS_URL/browser/$BROWSER_ID/live/$LIVE_URL_ID?token=$TOKEN"

A successful close returns 204 No Content. A URL cannot be closed twice: deleting an unknown, another browser's, or already-ended URL returns 404.

Access and security checks

• Your plan must support Live URLs.
• The token must own the running browser. Requests made with another owner's token return 404 rather than revealing whether the browser or Live URL exists.
• A Live URL ID is valid only for the browser that created it.
• After Browserless fills a stored credential, creating a new Live URL is blocked so page pixels cannot be exposed. Status and close requests remain available, allowing the owner to inspect or close an existing URL.

Errors

Status	Applies to	Cause
400	All routes	The plan does not support Live URLs.
400	POST	The request body is not a JSON object, an option has the wrong type or range, the timeout exceeds the session maximum, or a stored credential has been filled in the browser.
401	All routes	The API token is missing or invalid.
404	All routes	The browser is not running or is not owned by the token.
404	GET	The Live URL is unknown, belongs to another browser, or its browser has closed.
404	DELETE	The Live URL is unknown, belongs to another browser, or has already ended.