Skip to main content
Version: v2

Creating Sessions

Sessions allow you to maintain browser state across multiple connections, enabling complex workflows that require persistence. Browserless offers two approaches for creating and managing sessions.

Browser Sessions use the Browserless.reconnect CDP command to maintain state between connections. This approach works with all automation libraries and automatically manages session lifecycle.

Session API allows you to restore sessions with all their preserved state, such as a logged-in user session, shopping cart contents, or any other browser state you need to maintain. This is particularly useful when you need to continue automation workflows across multiple script runs or when building applications that require users to authenticate once and then perform multiple operations over time. This approach provides explicit programmatic control over session creation and deletion through dedicated endpoints, designed for advanced use cases requiring precise lifecycle management or integration with larger automation platforms.

Browser Sessions​

The standard approach uses the Browserless.reconnect CDP command for explicit reconnection control, which keeps browsers alive after disconnection for a specified timeout duration.

Browser Sessions TTL Limitations by Plan​

PlanMaximum TTL
Free10 seconds (10,000ms)
Prototyping/Starter1 minute (60,000ms)
Scale5 minutes (300,000ms)

Default TTL: 30 seconds (30,000ms) if not specified

How it works​

When you use reconnection commands, Browserless:

  1. Maintains browser state including cookies, localStorage, sessionStorage, and cache
  2. Keeps browsers alive for the specified timeout duration after disconnection
  3. Allows reconnection to the same browser instance within the timeout window
  4. Automatically cleans up sessions after the timeout expires

Creating a Session​

import puppeteer from 'puppeteer-core';

// Connect to browser
const browser = await puppeteer.connect({
  browserWSEndpoint: 'wss://production-sfo.browserless.io?token=YOUR_API_TOKEN',
});

const page = await browser.newPage();
const cdp = await page.createCDPSession();
await page.goto('https://example.com');

// Set up session state
await page.evaluate(() => {
  localStorage.setItem('myData', 'persistent-value');
});

// Enable reconnection with 60 second timeout
const { error, browserWSEndpoint } = await cdp.send('Browserless.reconnect', {
  timeout: 60000,
});

if (error) throw error;
console.log('Reconnection endpoint:', browserWSEndpoint);

await browser.disconnect(); // Browser remains alive for 60 seconds

Session Configuration​

You can combine reconnection timeouts with other browser options for advanced configuration:

const browser = await puppeteer.connect({
  browserWSEndpoint: 'wss://production-sfo.browserless.io?' + new URLSearchParams({
    token: 'YOUR_API_TOKEN',
    stealth: 'true'
  }).toString(),
});

const page = await browser.newPage();
const cdp = await page.createCDPSession();

// Enable reconnection with stealth mode active
const { error, browserWSEndpoint } = await cdp.send('Browserless.reconnect', {
  timeout: 60000,
});

Session API​

Paid Feature

Session API requires a paid plan and is designed for advanced use cases requiring explicit session lifecycle control.

For more control over session lifecycle, you can use the REST API to explicitly create sessions. This approach is useful when you need programmatic session management or advanced session control.

Creating a Session via REST API​

const response = await fetch('https://production-sfo.browserless.io/session?token=YOUR_API_TOKEN', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    ttl: 300000, // 5 minutes
    stealth: true,
    headless: true,
    args: ['--no-sandbox', '--disable-dev-shm-usage']
  }),
});

const { id } = await response.json();
console.log('Created session:', id);

Session Configuration Options​

ParameterTypeDefaultDescription
ttlnumber300000Time-to-live in milliseconds (max 30 minutes)
stealthbooleanfalseEnable stealth mode to avoid detection
headlessbooleantrueRun browser in headless mode
argsstring[][]Additional Chrome launch arguments
proxyobjectnullProxy configuration

Advanced Session Creation​

const sessionConfig = {
  ttl: 1800000, // 30 minutes
  stealth: true,
  headless: false,
  args: [
    '--no-sandbox',
    '--disable-dev-shm-usage',
    '--disable-background-timer-throttling',
  ],
  proxy: {
    server: 'http://proxy.example.com:8080',
    username: 'user',
    password: 'pass'
  }
};

const response = await fetch('https://production-sfo.browserless.io/session?token=YOUR_API_TOKEN', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(sessionConfig),
});

Connecting to Session API​

After creating a session with the Session API, use the WebSocket endpoint to connect your automation library:

import puppeteer from 'puppeteer-core';

// Assume you have a sessionId from session creation
const sessionId = 'session-abc123';

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://production-sfo.browserless.io/session/connect/${sessionId}?token=YOUR_API_TOKEN`,
});

const page = await browser.newPage();
await page.goto('https://example.com');

// Session state is maintained by the Session API
await page.evaluate(() => {
  localStorage.setItem('myData', 'api-session-value');
});

await browser.close(); // Session remains active

Choosing the Right Approach​

Use Browser Sessions When:​

  • Working with existing automation scripts
  • Need simple session persistence
  • Want maximum compatibility
  • Session lifetime managed by your application logic

Use Session API When:​

  • Need explicit session lifecycle control
  • Building advanced session management workflows
  • Want programmatic session creation/deletion
  • Need session monitoring and metadata

Next Steps​