Browsers

List Browser Sessions

Get paginated list of browser sessions with optional status filtering.

List responses intentionally omit per-session presigned recording URLs (recording_url is always null here). Each recording URL requires a synchronous boto3 SigV4 signing call (plus an S3 HEAD) that holds the GIL and blocks the event loop. With page_size up to the max this CPU-pegs the worker and starves the DB pool, cascading into pool exhaustion across the fleet. Clients should fetch the recording URL on demand via GET /api/v2/browsers/{id}, which signs exactly one URL for a single session. Mirrors the v3 sessions list fix (ENG-4904, PR #4621).

get/browsers

Request

  • Base URL: https://api.browser-use.com/api/v4
  • URL: https://api.browser-use.com/api/v4/browsers
  • Auth: API key in header X-Browser-Use-API-Key

Query parameters

metadatastring[] nullable

Only browsers tagged with every one of these terms. key matches any value; key=value matches exactly. Repeat the param to require more than one (AND).

pageSizeinteger
pageNumberinteger
filterBy'active' | 'stopped'

Enumeration of possible browser session states

Attributes: ACTIVE: Session is currently active and running (browser is running) STOPPED: Session has been stopped and is no longer active (browser is stopped)

agentSessionIdstring uuid nullable

Response

Successful Response

totalItemsinteger required

Total number of items in the list

pageNumberinteger required

Page number

pageSizeinteger required

Number of items per page

Changes

No recorded changes to this operation across all 1 revision of this API.