Identity & Sessions

What is a session?

A session is a persistent browser context. When you create or reuse a session, the browser retains cookies, local storage, IndexedDB, and authentication tokens between requests. This lets you:

Log into a site once and reuse that auth state across many fetches
Maintain a shopping cart or wizard state across multiple Interact calls
Avoid repeated CAPTCHA or bot-challenge flows on sites that remember prior visits

Creating a session

Sessions are created implicitly on the first Fetch or Interact request that references a session ID:

{
  "url": "https://app.example.com/login",
  "render_js": true,
  "session": { "id": "my-session-1" },
  "output": ["html"]
}

If my-session-1 does not exist, it is created. If it does exist, its state is loaded.

Reusing a session

Pass the same session.id on subsequent requests:

{
  "url": "https://app.example.com/dashboard",
  "render_js": true,
  "session": { "id": "my-session-1" },
  "output": ["markdown"]
}

The session’s cookies and storage are loaded before the page navigates, so auth-gated pages load correctly.

// Step 1: log in
{
  "url": "https://app.example.com/login",
  "session": { "id": "user-session" },
  "actions": [
    { "type": "type", "selector": "#email", "value": "user@example.com" },
    { "type": "type", "selector": "#password", "value": "secret" },
    { "type": "click", "selector": "button[type=submit]" },
    { "type": "wait_for", "selector": ".user-avatar" }
  ],
  "output": ["html"]
}

// Step 2: fetch a protected page using the same session
{
  "url": "https://app.example.com/account/orders",
  "render_js": true,
  "session": { "id": "user-session" },
  "output": ["json"],
  "extract": {
    "mode": "schema",
    "schema": { "orders": "array of recent order IDs and statuses" }
  }
}

Session response field

When a request includes session.id, the response includes a session field indicating whether the session was updated:

{
  "session": {
    "id": "user-session",
    "updated": true
  }
}

updated: true means the session was successfully persisted after this request — it’s set on every successful session-using request, not only when cookies or storage actually changed.

Session limits

Sessions are per-tenant and identified by the string ID you provide.
Session state is stored in Postgres and survives API restarts.
Sessions do not currently expire automatically — there is no default TTL, so a session persists until you stop reusing its ID.
There is no explicit “delete session” endpoint in the current release.

Getting Started

Guides

API Reference

Identity & Sessions

What is a session?

Creating a session

Reusing a session

Session response field

Session limits

​What is a session?

​Creating a session

​Reusing a session

​Login workflow example

​Session response field

​Session limits

What is a session?

Creating a session

Reusing a session

Login workflow example

Session response field

Session limits