List Sessions

List the project’s V4 sessions — one row per session (its most recent run), most-recent first.

A session is a conversation: follow-up runs reuse the same public_session_id, so GET /api/v4/runs would list one row per RUN. This collapses to one row per SESSION directly in Postgres with DISTINCT ON, so a chatty session with 100 runs is still a single row (no scan amplification), and selects only the slim columns the session list needs — never the heavy per-run text/token/cost fields.

Keyset-paginated on the latest run’s (created_at, id): pass next_cursor back as cursor to page. Offset/COUNT was dropped — it doesn’t scale on projects with many sessions.

GET /sessions

List Sessions

JavaScript

const options = {method: 'GET', headers: {'X-Browser-Use-API-Key': '<api-key>'}};

fetch('https://api.browser-use.com/api/v4/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

200

{
  "sessions": [
    {
      "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "workspaceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "latestRunId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "task": "<string>",
      "title": "<string>",
      "status": "queued",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "nextCursor": "<string>",
  "hasMore": false
}

Authorizations

X-Browser-Use-API-Key · string · header · required

Query Parameters

limit · integer · default: 20

Max sessions per page (max 100).

Required range: 1 <= x <= 100

cursor · string | null

Keyset cursor from a prior response.

Response

200

application/json

Successful Response

One entry per session (the session's most recent run), most-recent first.

A V4 session is a conversation: every follow-up run reuses the same public_session_id. GET /api/v4/runs returns one row per RUN, so callers that want a list of distinct sessions (e.g. the recent-sessions panel) should use this instead of de-duplicating runs client-side.

sessions · SessionInfo · object[] · required

Show child attributes

nextCursor · string | null

hasMore · boolean · default: false