Standard Sessions

Browserless provides browser sessions that allow you to maintain state across multiple connections. This allows you to keep users logged in, preserve shopping cart contents, or maintain form data between script runs. Sessions are essential for building realistic automation workflows that mimic human behavior.

With standard sessions, the browser instance will keep running until it's reconnected to, allowing you to maintain active state during temporary disconnections. Reconnecting to an existant session the standard way allows you to decide to persist a given session during execution, unlike the persisting state approach which requires premeditation.

The best way to manage persistent sessions is to use Browserless.reconnect CDP command to maintain state between connections. This works with all automation libraries and automatically manages session lifecycle.

Standard Sessions Workflow

1. Get Your API Token

   • Go to the Browserless dashboard
   • Sign up or log in to your account
   • Copy your API token from the dashboard

2. Connect with browserless

   Here is a working example of connecting to Browserless for either Playwright or Puppeteer:

   Puppeteer

   import puppeteer from "puppeteer-core";
   
   // Connect to browser with your API token
   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(); // Create CDP session for reconnection
   await page.goto("https://example.com");
   
   // Set up session state that will persist across reconnections
   await page.evaluate(() => {
     localStorage.setItem("myData", "persistent-value");
   });

   Playwright

   import { chromium } from "playwright";
   
   // Connect to browser with your API token
   const browser = await chromium.connectOverCDP(
     "wss://production-sfo.browserless.io?token=YOUR_API_TOKEN",
   );
   
   const page = await browser.newPage();
   const cdpSession = await page.context().newCDPSession(page); // Create CDP session for reconnection
   await page.goto("https://example.com");
   
   // Set up session state that will persist across reconnections
   await page.evaluate(() => {
     localStorage.setItem("myData", "persistent-value");
   });

3. Prepare to reconnect (Optional)

   Enable reconnection to keep the browser alive after disconnection:

   Puppeteer

   // Enable reconnection with 60 second timeout (must be within plan limits)
   const { error, browserWSEndpoint } = await cdp.send("Browserless.reconnect", {
     timeout: 60000, // Browser stays alive for 60 seconds after disconnect
   });
   
   if (error) throw error;
   console.log("Reconnection endpoint:", browserWSEndpoint);
   
   // Use disconnect() instead of close() to keep browser alive for reconnection
   await browser.disconnect(); // Browser remains alive for 60 seconds

   Playwright

   // Enable reconnection with 60 second timeout (must be within plan limits)
   const { error, browserWSEndpoint } = await cdpSession.send("Browserless.reconnect", {
     timeout: 60000, // Browser stays alive for 60 seconds after disconnect
   });
   
   if (error) throw new Error(error);
   console.log("Reconnection endpoint:", browserWSEndpoint);
   
   // Use disconnect() instead of close() to keep browser alive for reconnection
   await browser.disconnect(); // Browser remains alive for 60 seconds

4. Reconnect to previous session (Optional)

   Use the browserWSEndpoint from the previous step to reconnect to the same browser instance:

   Puppeteer

   // Reconnect using the browserWSEndpoint from the previous step
   const browser = await puppeteer.connect({
     browserWSEndpoint: browserWSEndpoint, // From previous step
   });
   
   const pages = await browser.pages();
   const page = pages.find(p => p.url().startsWith('https://example.com'));
   
   // Read myData from localStorage from previous step
   const myData = await page.evaluate(() => {
     return localStorage.getItem("myData");
   });
   console.log("Retrieved data:", myData); // Should show "persistent-value"

   Playwright

   // Reconnect using the browserWSEndpoint from the previous step
   const browser = await chromium.connectOverCDP(browserWSEndpoint); // From previous step
   
   const pages = await browser.pages();
   const page = pages.find(p => p.url().startsWith('https://example.com'));
   
   // Read myData from localStorage from previous step
   const myData = await page.evaluate(() => {
     return localStorage.getItem("myData");
   });
   console.log("Retrieved data:", myData); // Should show "persistent-value"

5. Closing your session

   Clean up session data and properly close the browser:

   Puppeteer

   // Clear local storage and cookies
   await page.evaluate(() => {
     localStorage.clear();
     sessionStorage.clear();
   });
   
   // Clear all cookies
   const cookies = await page.cookies();
   await page.deleteCookie(...cookies);
   
   // Close the browser session
   await browser.close();

   Playwright

   // Clear local storage and cookies
   await page.evaluate(() => {
     localStorage.clear();
     sessionStorage.clear();
   });
   
   // Clear all cookies
   const cookies = await page.context().cookies();
   await page.context().clearCookies();
   
   // Close the browser session
   await browser.close();

Advanced Session Management

For more control over session lifecycle, including explicit session creation and deletion, see Persisting State for the Session API approach. The Persisting State method allows you to close the browser and keep the session data stored for multiple days, providing greater flexibility for long-term automation workflows.

Reconnection TTL Limits

Reconnection TTL (Time-To-Live) is the maximum duration a browser instance remains available for reconnection after disconnecting:

Plan	Maximum Reconnection TTL	Overall Session Timeout
Free	10 seconds (10,000ms)	60 seconds
Prototyping/Starter	1 minute (60,000ms)	15-30 minutes
Scale	5 minutes (300,000ms)	60 minutes

Next Steps

Ready to take your session management to the next level? Explore these key areas:

Bot Detection

Bypass anti-bot measures with stealth mode and advanced evasion techniques.

Custom Launch Arguments

Configure browser with custom Chrome launch arguments for specialized use cases.

Persisting State

Learn about Session API for explicit session lifecycle control through REST endpoints.