Skip to main content
Version: v2

Managing Sessions

Once you've created a session, you can reconnect to it multiple times to continue your automation workflows while preserving browser state. This guide covers both browser session reconnection using the Browserless.reconnect CDP command and Session API management.

Reconnecting to Browser Sessions​

Browser sessions use the Browserless.reconnect CDP command to maintain state between connections and keep browsers alive after disconnection.

Basic Reconnection​

When managing browser sessions, be aware that new connections may create additional pages. You can start your browser on an existing page to avoid creating an about:blank page, but since many examples online use the newPage() method, we're making sure we're reconnecting to the page that isn't about:blank by filtering the pages array.

import puppeteer from 'puppeteer-core';

const queryParams = new URLSearchParams({
  token: 'YOUR_API_TOKEN',
  timeout: 60000,
}).toString();

console.log('Starting up the first browser and logging in...');
const browser1 = await puppeteer.connect({
  browserWSEndpoint: `wss://production-sfo.browserless.io?${queryParams}`,
});

const page1 = await browser1.newPage();
const cdp = await page1.createCDPSession();
await page1.goto('https://practicetestautomation.com/practice-test-login/', { 
  waitUntil: 'networkidle2',
  timeout: 60000 
});
await page1.type('#username', 'student');
await page1.type('#password', 'Password123');
await page1.click('#submit');

const { browserWSEndpoint } = await cdp.send('Browserless.reconnect', {
  timeout: 60000,
});
console.log('Login successful! Enabling reconnection, the browser will remain active for 60 seconds after disconnect. browserWSEndpoint:', browserWSEndpoint);

await browser1.disconnect(); // Browser must be disconnected, not closed.

const browser2 = await puppeteer.connect({
  browserWSEndpoint: `${browserWSEndpoint}?${queryParams}`,
});
// Get all pages and find the one that's not the about:blank page
const pages = await browser2.pages();
const page2 = pages.find(p => !p.url().startsWith('about:blank'));
const title = await page2.title();
await browser2.close();
console.log('Second browser closed - Demo complete! Page 2 title:', title);

Timeout and Plan Limitations​

Reconnection functionality has timeout limits based on your subscription plan:

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

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

Reconnecting to Sessions​

Sessions maintain their state between connections using the Browserless.reconnect CDP command. Here are common reconnection patterns:

Multi-Step Workflows Perfect for breaking complex automation into manageable steps:

import puppeteer from 'puppeteer-core';

let reconnectEndpoint = null;

// Step 1: Authentication
const authenticateUser = async () => {
  const browser = await puppeteer.connect({
    browserWSEndpoint: 'wss://production-sfo.browserless.io?token=YOUR_API_TOKEN&timeout=60000',
  });
  
  const page = await browser.newPage();
  const cdp = await page.createCDPSession();
  
  await page.goto('https://app.example.com/login');
  await page.type('#username', 'user@example.com');
  await page.type('#password', 'password123');
  await page.click('#login-button');
  await page.waitForNavigation();
  
  // Set up reconnection for next step
  const { browserWSEndpoint } = await cdp.send('Browserless.reconnect', {
    timeout: 60000, // 1 minute timeout
  });
  reconnectEndpoint = browserWSEndpoint;
  
  await browser.close();
  console.log('Authentication complete');
};

// Step 2: Data Collection
const collectData = async () => {
  const browser = await puppeteer.connect({
    browserWSEndpoint: `${reconnectEndpoint}?token=YOUR_API_TOKEN&timeout=60000`,
  });
  
  const [page] = await browser.pages();
  // Still authenticated from previous step
  await page.goto('https://app.example.com/dashboard');
  
  const data = await page.evaluate(() => {
    return document.querySelector('#user-data').textContent;
  });
  
  await browser.close();
  console.log('Data collected:', data);
  return data;
};

// Execute workflow
await authenticateUser();
const userData = await collectData();

Session Recovery with Reconnection Handle interruptions using Browserless.reconnect to maintain session state:

const resumeWorkflow = async (existingEndpoint = null) => {
  let browserEndpoint = existingEndpoint || 'wss://production-sfo.browserless.io?token=YOUR_API_TOKEN';
  
  const browser = await puppeteer.connect({
    browserWSEndpoint: browserEndpoint,
  });
  
  const page = await browser.newPage();
  const cdp = await page.createCDPSession();
  
  // Check current state
  await page.goto('https://app.example.com');
  const isLoggedIn = await page.$('#user-menu') !== null;
  
  if (!isLoggedIn) {
    console.log('Session expired, re-authenticating...');
    await page.goto('https://app.example.com/login');
    // ... perform login
  } else {
    console.log('Session still active, continuing...');
    await page.goto('https://app.example.com/dashboard');
  }
  
  // Set up reconnection before closing
  const { browserWSEndpoint } = await cdp.send('Browserless.reconnect', {
    timeout: 60000,
  });
  
  await browser.close();
  return browserWSEndpoint; // Return for potential reconnection
};

Long-Running Processes with Reconnection Use Browserless.reconnect for session persistence during long operations:

const processLargeDataset = async (startPage = 1) => {
  // Connect and set up reconnection for maintaining session between chunks
  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();
  
  // Set up reconnection with 5 minute timeout
  const { browserWSEndpoint } = await cdp.send('Browserless.reconnect', {
    timeout: 300000, // 5 minutes
  });
  
  // Resume from where we left off
  await page.goto(`https://app.example.com/data?page=${startPage}`);
  
  let currentPage = startPage;
  const maxPages = 100;
  
  while (currentPage <= maxPages) {
    console.log(`Processing page ${currentPage}`);
    
    // Process current page data
    const pageData = await page.evaluate(() => {
      return Array.from(document.querySelectorAll('.data-item')).map(item => item.textContent);
    });
    
    // Save progress
    await page.evaluate((page) => {
      localStorage.setItem('lastProcessedPage', page.toString());
    }, currentPage);
    
    // Navigate to next page
    currentPage++;
    if (currentPage <= maxPages) {
      await page.goto(`https://app.example.com/data?page=${currentPage}`);
    }
  }
  
  await browser.close(); // Reconnection keeps session alive for potential reconnection
};

Managing Session API​

Session API provides explicit control over session lifecycle with WebSocket connections for automation libraries.

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 browserWSEndpoint from the session creation step
const SessionBrowserWSEndpoint = 'wss://production-sfo.browserless.io/e/53...21/session/connect/b9..7b?token=25df...';

const browser = await puppeteer.connect({
  browserWSEndpoint: SessionBrowserWSEndpoint,
});

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

// Get all pages and print them
const pages = await browser.pages();
pages.forEach((p, i) => console.log(`  [${i}] ${p.url()}`)); //print all existing pages

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

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

Session State Persistence​

Both session types preserve browser state, but handle it differently:

// Browser sessions persist state using Browserless.reconnect
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 various types of state
await page.evaluate(() => {
  // Local storage persists
  localStorage.setItem('user_pref', 'dark_mode');
  
  // Session storage persists
  sessionStorage.setItem('temp_data', 'workflow_state');
  
  // IndexedDB persists
  const request = indexedDB.open('myDB', 1);
  // ... IndexedDB operations
});

// Cookies are automatically saved
await page.setCookie({
  name: 'session_token',
  value: 'abc123',
  domain: 'example.com'
});

// Set up reconnection before closing
const { browserWSEndpoint } = await cdp.send('Browserless.reconnect', {
  timeout: 60000,
});

await browser.close();

// All state is preserved for reconnection within timeout window
// Use browserWSEndpoint for reconnection

Next Steps​

  • Closing Sessions - Learn how to properly terminate sessions and clean up resources