Skip to main content
A session is an isolated browser instance running your automation tasks. You get a dedicated environment with a unique sessionId that persists until you terminate it or it times out due to inactivity (sessions expire after 5 minutes of inactivity). Sessions run completely isolated—no shared cookies, no shared state. This lets you run multiple concurrent sessions without interference. Run tasks sequentially within the same session: navigate to a site, authenticate, then execute your workflow. Terminate when done, or you’ll pay for the full timeout window.

​
Session Lifecycle

Sessions progress through these states: Pending → Browser instance initializing Active → Task currently executing Completed → Session ended successfully Terminated → Ended by user or timeout Failed → Session ended due to error Orphaned → Instance disconnected unexpectedly (reconnection window available) Orphaned sessions are rare. If a browser instance loses connection, the session waits for reconnection. If it doesn’t reconnect within the grace period, the session fails.

​
Configuration Parameters

Configure sessions when creating them: 
{
  "profileId": "683a1f2e4b0c1d2e3f4a5b6c",       // Optional: reuse browser profile
  "mode": "default",                              // Session mode
  "initialTask": {
    "taskDetails": "What to do",                  // Initial task (can be empty)
    "startingPoint": "https://example.com",       // Skip navigation
    "maxDuration": 300000,                        // Task timeout in ms (max 5 min)
    "maxInputTokens": 100000,                     // AI model input limit
    "maxOutputTokens": 100000,                    // AI model output limit
    "avoidDomains": ["ads.example.com"],          // Domains to block
    "terminateOnCompletion": false,               // Auto-terminate after first task
    "secrets": [                                   // Credentials for website auth
      { "match": "*.example.com", "fields": { "email": "[email protected]", "password": "pass" } }
    ],
    "outputType": "structured_json",              // "text", "structured_json", or "structured_csv"
    "outputSchema": { ... }                       // JSON Schema for structured output
  }
}
Key parameters:
  • mode: Session mode (currently only "default" is supported).
  • initialTask: Contains all task-specific parameters.
  • taskDetails: Can be empty if you plan to send tasks later via /send-message.
  • startingPoint: Saves tokens and time by skipping navigation.
  • maxDuration: Maximum time a task can run before automatic termination (default: 5 minutes). Note: Session inactivity timeout is fixed at 5 minutes.
  • terminateOnCompletion: Automatically true for /start/run-task endpoint.
  • avoidDomains: Prevents accidental navigation to unwanted domains.
  • secrets: Provide credentials upfront so the agent can authenticate without guardrail interruptions. Secrets are never stored and are discarded when the session ends. See Secrets guide.
  • profileId: Attach a browser profile to reuse saved cookies, local storage, and other browser data. The profile ID is a top-level parameter, not nested inside initialTask.

​
Session Types

​
Persistent Session

Create a session that stays open for multiple tasks: 
POST /start/start-session
Use persistent sessions when you need to execute multiple related tasks or when tasks depend on previous state (like staying logged in).

​
Single-Task Session

Create a session that auto-terminates after one task: 
POST /start/run-task
Use single-task sessions for one-off automations with no follow-up actions. This is the simplest integration pattern.

​
Key Behaviors

One task at a time: Sessions execute tasks sequentially, not in parallel. If you send a new task while one is running, it queues and starts after the current task completes. Inactivity timeout: Sessions automatically terminate after 5 minutes of inactivity. Active sessions can run indefinitely. You’re billed only for actual compute time used. Complete isolation: No shared cookies, cache, or session state between sessions. Each session starts with a clean browser — unless a profile is attached. Profiles let you persist cookies, local storage, and other browser data across sessions. Billing: Sessions are billable from creation until termination or timeout. Idle time between tasks counts as compute time. Always terminate sessions when finished.

​
Common Patterns

Pattern 1: Single task 
// Create and auto-terminate
POST /start/run-task
{
  "taskDetails": "Extract data from this page"
}
Pattern 2: Multi-task sequence 
// Create session
POST /start/start-session
{ "taskDetails": "Navigate to site" }

// Send follow-up task
POST /start/send-message
{
  "sessionId": "sess_abc",
  "message": {
    "actionType": "newTask",
    "taskDetails": "Extract data"
  }
}

// Terminate explicitly
POST /start/send-message
{
  "sessionId": "sess_abc",
  "message": { "actionType": "state", "newState": "terminate" }
}
Pattern 3: Multi-task with auto-terminate 
// Create session
POST /start/start-session
{ "taskDetails": "Navigate to site" }

// Final task with auto-terminate
POST /start/send-message
{
  "sessionId": "sess_abc",
  "message": {
    "actionType": "newTask",
    "taskDetails": "Extract data",
    "terminateOnCompletion": true  // Auto-terminates after this task
  }
}

Session Control

Pause, resume, stop, and terminate sessions

Tasks

Understanding task lifecycle and execution

Multi-Task Workflows

Chain tasks effectively

Cost Optimization

Reduce costs with session management

Browser Profiles

Persist browser data across sessions