---
title: "List Browser Sessions"
method: GET
path: "/browsers"
tags: ["Browsers"]
---

# List Browser Sessions

`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`

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).

## Query parameters

- `metadata` string[], 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).
- `pageSize` integer
- `pageNumber` integer
- `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)
- `agentSessionId` string, uuid, nullable

## Response `200`

Successful Response

- BrowserSessionListResponse: Response model for paginated browser session list requests.
  - `items` BrowserSessionItemView[], required: List of browser session views for the current page
    - `id` string, uuid, required: Unique identifier for the session
    - `status` 'active' | 'stopped', required: 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)
    - `liveUrl` string, nullable: URL where the browser can be viewed live in real-time
    - `cdpUrl` string, nullable: Chrome DevTools Protocol URL for browser automation
    - `timeoutAt` string, date-time, required: Timestamp when the session will timeout
    - `startedAt` string, date-time, required: Timestamp when the session was created and started
    - `finishedAt` string, date-time, nullable: Timestamp when the session was stopped (None if still active)
    - `proxyUsedMb` string: Amount of proxy data used in MB
    - `proxyCost` string: Cost of proxy usage in USD
    - `browserCost` string: Cost of browser session hosting in USD
    - `agentSessionId` string, uuid, nullable: ID of the agent session that created this browser (None for standalone BaaS sessions)
    - `recordingUrl` string, nullable: Presigned URL to download the session recording. Only populated on `GET /api/v2/browsers/{id}`; always `null` in list responses.
    - `metadata` object: Caller-supplied labels set when the browser was created.
    - `extensions` BrowserExtensionView[]: Extensions installed in the browser, in the order of `extensionIds`.
      - `id` string, uuid, required: Extension ID from POST /api/v4/extensions
      - `runtimeId` string, required: Chromium extension ID, as in chrome-extension://{runtimeId}/
      - `version` string, required: Version from the extension manifest
  - `totalItems` integer, required: Total number of items in the list
  - `pageNumber` integer, required: Page number
  - `pageSize` integer, required: Number of items per page

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/browser-use/apis/browser-use-public-api-v4.md) · [All operations](https://skmtc.dev/browser-use/apis/browser-use-public-api-v4/llms.txt) · [OpenAPI document](https://skmtc.dev/browser-use/apis/browser-use-public-api-v4/revisions/cd7b1eee1102?raw)