Skip to main content
A session holds the agent’s conversation and can reuse its live browser. One session ID can contain multiple runs. Every run creates a session implicitly unless you pass an existing session ID. One session ID holding four runs: the conversation gains a turn per run and the workspace keeps its files, while back-to-back runs reuse one live browser. That browser stops after 120 s idle, so a later run gets a new browser but keeps the conversation and files. One session ID holding four runs: the conversation gains a turn per run and the workspace keeps its files, while back-to-back runs reuse one live browser. That browser stops after 120 s idle, so a later run gets a new browser but keeps the conversation and files. Pass session_id / sessionId to continue:
Omit the session ID for a new conversation. Pass only a workspace ID when you want a fresh conversation that keeps the same files.

Keep the browser open between runs

After a session’s last run, its browser stays open about 2 minutes, then stops. A later follow-up gets a fresh browser with the same settings and profile, but not the old tabs or page state. Set keepAlive on the run to keep the browser open longer: integer seconds from 120 to 14400 (default 120), never past the browser’s 4-hour lifetime. Follow-ups inherit the value, a new value changes it, and null restores 120 seconds.
SDK 3.12+ types it as keep_alive / keepAlive. On 3.11.3, Python must pass keepAlive=900 (keep_alive sends the wrong key) and TypeScript needs as RunCreateBody. Unlike the boolean keepAlive in V2/V3, V4 takes seconds and rejects true with 422. Kept time is billed as browser time but takes no concurrency slot. Free-tier and Zero Data Retention runs always use 120 seconds.

Follow up while a run is busy

Use the session queue to send the next instruction without interrupting the active run. The response is a queued message, not a run: its runId can be null until dispatch. Keep its message ID and poll that message before waiting for the resulting run. Do not resend the message to poll it.
This example times out only its local wait. It does not remove the queued message or cancel a run. interrupt=True / interrupt: true instead cancels the active run so the new instruction can run immediately. Keep it false to preserve the active work.

Manage a session

Rename

Titles are up to 255 characters. null or a blank title clears the name, and the dashboard shows the opening task instead.

Delete

Returns 204. The session disappears from lists and cannot be opened or continued. An active run and any pending queued messages are cancelled first. Deleting again also returns 204. On 502 or 503 the session was not deleted; retry. Delete hides the session but keeps its records for billing; it does not erase data.
The response contains shareUrl, shareToken, isActive, and viewCount. Anyone with the link can see the session’s tasks, results, workspace files, and recording without an API key. Disable the link with PUT /api/v4/sessions/{id}/share and {"isActive": false}; it stops working immediately. Enabling it again keeps the same URL. GET /api/v4/sessions/{id}/share returns null if the session was never shared. Zero Data Retention projects cannot share sessions.

Purge data (Zero Data Retention projects)

Purge erases the session’s run content, workspace files, recordings, and downloads. It returns 204 when done, or 202 with Retry-After: 60 while active work or uploads delay deletion; call it again after that delay. Projects without Zero Data Retention get 403. The SDK sessions.purge helpers do not handle the 202 yet, so use the HTTP call to know when deletion finished.