session_id / sessionId to continue:
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. SetkeepAlive 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.
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: itsrunId 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.
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
null or a blank title clears the name, and
the dashboard shows the opening task instead.
Delete
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.
Share a read-only link
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)
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.