Lists the project's sessions, newest first, with each one's id, status, kind and creation time. Use it to find a session again: the server keeps nothing between calls, so a model that has lost a sessionId gets it back here. All of its inputs are optional. Filter by status or kind, or search with q, and read a long list a page at a time with after.

Inputs

Name	Type	Default	Allowed values	Description
`status`	`string`	–	–	Only sessions with this status: `RUNNING`, `STOPPED`, `DELETED` or `ERROR`. Join several with commas, for example `RUNNING,STOPPED`. Leave it out to not filter by status.
`kind`	`string`	–	`browser`, `shell`, `combined`	Only sessions of this kind: `browser` (a browser only), `shell` (a shell only) or `combined` (a browser and a shell).
`q`	`string`	–	–	Search: a session id prefix, or text found in the session's `userMetadata`.
`limit`	`integer`	20	–	How many sessions to list, 1 to 100.
`after`	`string`	–	–	The cursor from the last result (its last line says `after "…"`), to read the sessions that follow. Leave it out for the first page.

Example call

This is what an MCP client sends. You do not write it yourself: ask the model in plain words and it calls the tool.

tools/call

{  "name": "session_list",  "arguments": {    "status": "RUNNING"  }}

What it returns

One line per session: its id, status, kind and when it was created, newest first. When there are more, a last line says what to pass as after to read them.

Result

6c1f3c9e-1d2a-4f67-9b0e-1b2c3d4e5f60  RUNNING  combined  2026-10-07T09:12:30.000Z0b8d52a7-4e19-4c3f-a6d1-7f2e9c1b8a44  RUNNING  browser   2026-10-07T08:55:02.000Z

When a call fails, the result is marked as an error. Its text starts with the API’s error code, such as unauthorized or session_not_running, followed by its message.

Annotations

The server tells every client what this tool does to the world, so a client can decide what to ask you about before it runs.

Annotation	Value
`title`	List sessions
`readOnlyHint`	`true`
`destructiveHint`	`false`
`openWorldHint`	`false`

Good to know

It only reads, and it lists ids, not URLs: the live view URL comes from session_create or session_resume.
Stopped sessions are listed too. session_resume brings one back, and any session tool takes its id.

The same thing with the API

Endpoint	Reference
`GET /v1/sessions`	List sessions

These docs describe a beta API. Endpoints, fields and SDK methods may change before general availability; breaking changes will be listed in the changelog.