Sessions

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:

{
  "environmentId": "683a1f2e4b0c1d2e3f4a5b6c",     // Optional: reuse browser profile & files
  "policyId": "pol_xyz789",                          // Optional: enforce automation rules
  "proxy": { "source": "WebRun", "country": "US" }, // Optional: route through proxy
  "reachOutMode": "guardrail_only",                  // Optional: chat-user reach-out mode ("off" | "guardrail_only" | "full")
  "mode": "default",                              // Session mode
  "task": {
    "prompt": "What to do",                  // Initial task (can be empty)
    "startingUrl": "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
    "terminateOnCompletion": false,               // Auto-terminate after first task
    "secrets": [                                   // Credentials for website auth
      { "match": "*.example.com", "fields": { "email": "user@co.com", "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).
task: Contains all task-specific parameters.
prompt: Can be empty if you plan to send tasks later via /send-message.
startingUrl: 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.
policyId: Attach an automation policy to enforce runtime rules on agent actions. Policies cover domain restrictions, action rules, URL patterns, and sensitive data. This is a top-level parameter, not nested inside task.
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.
environmentId: Attach an environment to reuse saved cookies, local storage, files, and other browser data. This is a top-level parameter, not nested inside task.
proxy: Route the session through a proxy server for geographic targeting or IP management. Use WebRun-managed proxies or bring your own. Adds 2-3 seconds of cold-start latency. See Proxies guide.
reachOutMode: Controls proactive chat messages to a user (Telegram, WhatsApp, Slack, Discord, Teams) connected to the same environment, only when no client is actively watching the session. One of "off" (no messages), "guardrail_only" (default: bot pings on guardrails like CAPTCHA/2FA/login), or "full" (also delivers task results to chat on completion). Use "off" for sessions handling private data you don’t want surfaced through chat. See Handling Guardrails.

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 an environment is attached. Environments let you persist cookies, local storage, files, 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
{
  "prompt": "Extract data from this page"
}

Pattern 2: Multi-task sequence

// Create session
POST /start/start-session
{ "prompt": "Navigate to site" }

// Send follow-up task
POST /start/send-message
{
  "sessionId": "sess_abc",
  "message": {
    "actionType": "newTask",
    "prompt": "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
{ "prompt": "Navigate to site" }

// Final task with auto-terminate
POST /start/send-message
{
  "sessionId": "sess_abc",
  "message": {
    "actionType": "newTask",
    "prompt": "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

Environments

Persist browser data and files across sessions

Proxies

Route sessions through proxy servers

Automation Policies

Runtime rules that control agent behavior

Getting Started

Concepts

Usage Guides

Integrations

Environments

API Reference

Capabilities

Troubleshooting

Session Lifecycle

Configuration Parameters

Session Types

Persistent Session

Single-Task Session

Key Behaviors

Common Patterns

Session Control

Tasks

Multi-Task Workflows

Cost Optimization

Environments

Proxies

Automation Policies

​Session Lifecycle

​Configuration Parameters

​Session Types

​Persistent Session

​Single-Task Session

​Key Behaviors

​Common Patterns

Session Control

Tasks

Multi-Task Workflows

Cost Optimization

Environments

Proxies

Automation Policies

Session Lifecycle

Configuration Parameters

Session Types

Persistent Session

Single-Task Session

Key Behaviors

Common Patterns