Sessions

Create options

Field	Type	Default	Notes
`country`	string	`us`	Exit country for the residential IP
`ttl_seconds`	integer	`1800`	60–3600. Plan may set a lower max
`idle_timeout_seconds`	integer	`300`	Min 30. Clicks and typing keep the session active; watching the stream does not
`engine`	string	`chromium`	`chromium` or `firefox`
`block_resources`	string[] \| null	default set	`image`, `font`, `media`. Omit for plan default. Empty list downloads everything. Not for Firefox
`profile`	string \| null	null	Profile name to load and save on end. Chromium only
`record`	boolean	`false`	Record the screen as MP4
`extensions`	string[] \| null	null	e.g. `["stagehand"]`. Chromium only
`warm_for`	string \| null	null	Domain to start from when a warmed cookie/exit pair exists
`webgl`	string \| null	null	Chromium: `swiftshader` or `mesa`

Lifecycle

State	Meaning
`starting`	Session is coming up (`wait=false` path)
`ready`	Connect and drive
`failed`	Did not start; read `error`
`gone`	Ended

API max TTL is 60 minutes, subject to a lower plan limit. Default idle timeout is 5 minutes.

When a session ends, ended_reason may be: expired, idle, stopped_by_user, session_traffic_cap, quota, failed_to_start, out_of_memory, browser_crashed, or closed.

Live view

live_url: MJPEG stream of the screen
live_view_url: page with Take control (click, type, paste)
Watching alone does not reset idle timeout
A live viewer is not counted as a CDP clients entry

Set record: true at create. While the session lives, recording_url points at the session door. After it ends, the kept file is available for seven days. GET /v1/sessions/{id}/recording redirects (307) to that location.

Stagehand

{
  "engine": "chromium",
  "extensions": ["stagehand"]
}

Inspect extensions.stagehand in the response. Startup is slower than a plain prestarted browser.

Memory fields

memory.percent, memory.high_water_pct, and memory.tabs_closed are shares of the memory limit, not sizes in MB.

List and get

GET /v1/sessions - your sessions
GET /v1/sessions/{session_id} - one session
DELETE /v1/sessions/{session_id} - stop a session