Sessions
Understand session lifecycle, connection, and cleanup.
Use sessions for JS-heavy pages, state, screenshots, or Playwright control.
Keep timeoutSec explicit and stop the session when the job is finished.
Attach a profile only when durable login state or browser context is required.
When to Create a Session
Create a session whenever a workflow needs a real browser runtime. Common cases include:
Run Playwright or Puppeteer for login, clicks, navigation, screenshots, and page checks.
Validate Fetch, Crawl, selectors, timeouts, and artifact output in the playground.
Attach a profile to reuse cookies, local storage, and stable browser context.
Keep logs, replay, screenshots, and artifacts so failed runs can be inspected.
If you only need a normal HTTP API call, you do not need a session. If the target site depends on JavaScript, browser state, or real rendering, use a session.
Session Lifecycle
Every session moves through these states:
The session is requested and waiting for healthy runner assignment.
The runner is launching Chromium and downloading profile state if a profile is attached.
Chromium is running. Connect over CDP and execute browser automation.
The runner flushes artifacts, writes profile state back, and releases resources.
Sessions also transition to ERROR if something goes wrong during launch or execution.
Default posture: set an explicit timeoutSec and stop the session when ordinary automation finishes; keep the session alive only for human inspection; attach profiles only for login state; enable recording or retained artifacts when investigating failures. See the Sessions API for request fields, defaults, and response shapes.
Connecting via Playwright
After creating a session, use the returned connectUrl to connect:
import { chromium } from 'playwright-core';
const browser = await chromium.connectOverCDP(session.connectUrl);
const context = browser.contexts()[0];
const page = context.pages()[0] || (await context.newPage());
// Now use the page as normal
await page.goto('https://example.com');
await page.screenshot({ path: 'screenshot.png' });The connectUrl includes a one-time connect token. Traffic is routed through the Connect Gateway to the correct runner.
Stop and Collect
When you are done, stop the session explicitly:
const res = await fetch(`${API}/v1/sessions/${sessionId}/stop`, {
method: 'POST',
headers: { Authorization: `Bearer ${API_KEY}` },
});The stop phase writes back writable profile state, flushes pending screenshot/PDF/content captures, and releases browser processes plus session slots.
If you do not stop the session manually, it will be terminated after timeoutSec seconds.
Troubleshooting
Check status, timeout settings, and runner health.
Confirm the connectUrl belongs to the current ACTIVE session and has not expired.
Check timeoutSec, script exceptions, browser logs, and network events.
Confirm a profile is attached and write-back is allowed; persist only the session id, terminal state, and key timestamps. See the Sessions API.