Sessions

Sessions are short-lived browser contexts that let your agent navigate multi-page workflows. Within a session, cookies, auth state, and navigation history carry across calls; sessions are ephemeral and expire on the timeouts below.

Creating a Session

A new session is created automatically when you browse a URL:

const page = await client.browse('https://stackoverflow.com');
const sessionId = page.session_id; // Use for follow-up calls within this task

Multi-Step Workflow

Scope session reuse to a single short task — open, do the steps, close:

// Step 1: Open the site
const page = await client.browse('https://stackoverflow.com');

// Step 2: Search
const results = await client.browse({
  session_id: page.session_id,
  tool: 'search_questions',
  params: { q: 'rust lifetimes' },
});

// Step 3: Open a result
const question = await client.browse({
  session_id: page.session_id,
  tool: 'navigate_to_question',
  params: { url: 'https://stackoverflow.com/questions/11227809' },
});

// Step 4: Clean up
await client.closeSession(page.session_id);

Sessions are ephemeral — don't hold a session_id across tasks or persist it anywhere. A follow-up call can return SESSION_NOT_FOUND (404) or SESSION_EXPIRED (410) at any time; handle either by starting a fresh session, not by retrying the old one.

Session lifetime & re-authentication

Both caps are flat across all plans, and when a session expires its cookies and auth state are destroyed with it. The recommended pattern:

1. Complete one task within one session — log in if the task needs it, do the steps, read the result.
2. Close the session when the task is done.
3. Start a fresh session for the next task — and execute the login tool again if that task needs auth. See the Authentication guide.

Don't poll or ping a session to keep it alive. Every /v1/browse call — including an observe-only call with a session_id — bills at least one action, so a keepalive loop burns quota and never lifts the ~15-minute cap anyway.

Concurrent Sessions

An agent can hold multiple sessions simultaneously:

// Two independent browser sessions
const github = await client.browse('https://github.com');
const docs = await client.browse('https://docs.example.com');

// Each has its own cookies, auth state, and history

Concurrency is plan-limited: 1 session on Free, 15 on Builder (and the trial), 30 on Pro. At the limit, new sessions return CONCURRENCY_EXCEEDED (503, retryable) until a slot frees up — close sessions you're done with, or see pricing for higher limits.

Closing Sessions

Always close sessions when done to free browser resources:

await client.closeSession(sessionId);

Sessions auto-expire on idle timeout, but explicit cleanup releases resources immediately and is especially important during batch workflows.