Sessions

A session is one browser that webagent runs for you in the cloud. You open it, give it work (a goal, a skill, plain actions), and close it. Everything else, such as tasks, live view and evidence, belongs to a session.

Session ids look like sess_us_…. The part after sess_ is the region.

Open a sessionCopy Anchor Link

You get a session in three ways:

• Call the create_session MCP tool, or POST /v1/sessions. You choose the options and keep the session until you stop it. See Tools.
• Call run_task without a sessionId. The tool opens a session, runs the goal and closes the session after the task unless keepOpen is true. It takes the common options itself: record, headers, proxyUrl, allowHosts and credentials.
• Run a skill (including smoke_test), or a quick action such as scrape. Each run gets its own session. You do not manage it.

A session opens in Chromium unless you ask for firefox or webkit. The create call takes options such as startUrl, device, viewport, record, headers, proxyUrl, locale and timezone. The full list is in the API reference.

Every page the browser opens goes through a guard. Private, loopback and link-local addresses are blocked. A cloud browser cannot open localhost on your machine. See Test a local app.

StatesCopy Anchor Link

An ended session has an endReason: closed (you stopped it), idle_timeout, max_duration, runner_lost, error, memory_limit or capacity_timeout (see below).

When no browser is freeCopy Anchor Link

By default, a create call fails with capacity_exceeded when every browser is busy. Two options change that:

• waitForCapacityMs (0 to 30 000): wait up to this long for a browser to free up, then fail.
• queueForCapacity ({ "maxWaitSeconds": 1 to 900 }): keep the session in a queue. Not together with waitForCapacityMs above 0.

A queued session has the status starting and a queue object with position, etaSeconds, reason (vpc_full or scaling_up, when a new browser is starting up), queuedAt and expiresAt. The queue object goes away when the session starts. Read the session with GET /v1/sessions/:id until queue is gone and the status is live, then ask for a token with POST /v1/sessions/:id/token. A session that finds no browser before expiresAt ends with the end reason capacity_timeout. A quota refusal (too many open sessions, memory, budget or credits) is not queued: it fails at once.

How long a session livesCopy Anchor Link

A session ends on its own in two cases:

• Idle. No action for 5 minutes. Change it with idleTimeoutMs.
• Maximum age. One hour after it started. Change it with maxDurationMs.

Both options accept 10 seconds up to 24 hours. These are today's defaults and they may change.

A session that uses more memory than its cap is stopped the second time it goes over the cap, with the end reason memory_limit.

Stop a sessionCopy Anchor Link

Call the stop_session MCP tool, or DELETE /v1/sessions/:id. Stopping is safe to repeat. A session you forget is closed by the idle and age limits above, but it holds browser capacity and counts as compute until then. See Limits and Billing.

Talk to a live sessionCopy Anchor Link

POST /v1/sessions returns endpoints and a short-lived token. They let a client talk to the browser directly. For most uses you do not need them: the MCP tools and the dashboard do this for you. To get a fresh token, call POST /v1/sessions/:id/token.

Read sessions backCopy Anchor Link

GET /v1/sessions lists sessions, GET /v1/sessions/:id reads one. The list_sessions and get_session MCP tools do the same. Each session may have a title. It is made from the first goal you give it, or you can set it with PATCH /v1/sessions/:id.