Version: v2

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. Standard sessions are only supported with the Puppeteer library, as Playwright does not provide a way to disconnect from a browser without also clearing the browser context.

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.

REST API Limitations

REST APIs (like /function, /screenshot, /pdf, etc.) automatically close browser sessions after execution and do not support session persistence. For persistent sessions, use BaaS with the Browserless.reconnect CDP command as described on this page, or BrowserQL with the reconnect mutation.

Standard Sessions Workflow

Get Your API Token
- Go to the Browserless dashboard
- Sign up or log in to your account
- Copy your API token from the dashboard

Connect with browserless

Here is a working example of connecting to Browserless with Puppeteer:

import puppeteer from "puppeteer-core";

const TOKEN = "YOUR_API_TOKEN_HERE";
const BROWSERLESS_URL = `wss://production-sfo.browserless.io?token=${TOKEN}`;

async function connectToBrowserless() {
  const browser = await puppeteer.connect({
    browserWSEndpoint: BROWSERLESS_URL,
  });

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

  return { browser, page, cdp };
}

const { browser, page, cdp } = await connectToBrowserless();

Set up session state

Set up session state that will persist across reconnections:

async function setupSessionState(page) {
  await page.evaluate(() => {
    localStorage.setItem("myData", "persistent-value");
  });
}

await setupSessionState(page);

Prepare to reconnect (Optional)

Enable reconnection to keep the browser alive after disconnection:

async function prepareReconnection(cdp, browser, timeout = 60000) {
  const { error, browserWSEndpoint } = await cdp.send("Browserless.reconnect", {
    timeout,
  });

  if (error) throw new Error(error);
  console.log("Reconnection endpoint:", browserWSEndpoint);

  await browser.disconnect();

  return browserWSEndpoint;
}

const browserWSEndpoint = await prepareReconnection(cdp, browser);

Reconnect to previous session (Optional)

Use the browserWSEndpoint from the previous step to reconnect to the same browser instance. Note that you must append your API token to the endpoint URL:

async function reconnectToSession(browserWSEndpoint, token) {
  const reconnectUrl = `${browserWSEndpoint}?token=${token}`;

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

  const pages = await browser.pages();
  const page = pages.find((p) => p.url().startsWith("https://example.com"));

  const cdp = await page.createCDPSession();

  return { browser, page, cdp };
}

const reconnected = await reconnectToSession(browserWSEndpoint, TOKEN);
const myData = await reconnected.page.evaluate(() => {
  return localStorage.getItem("myData");
});
console.log("Retrieved data:", myData); // Should show "persistent-value"

Closing your session

Clean up session data and properly close the browser:

async function closeSession(browser, page) {
  await page.evaluate(() => {
    localStorage.clear();
    sessionStorage.clear();
  });

  const cookies = await page.cookies();
  await page.deleteCookie(...cookies);

  await browser.close();
}

await closeSession(reconnected.browser, reconnected.page);

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.

Complete Example

Here is the complete code that you can copy and paste to run the full session workflow:

import puppeteer from "puppeteer-core";

const TOKEN = "YOUR_API_TOKEN_HERE";
const BROWSERLESS_URL = `wss://production-sfo.browserless.io?token=${TOKEN}`;

async function connectToBrowserless() {
  const browser = await puppeteer.connect({
    browserWSEndpoint: BROWSERLESS_URL,
  });

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

  return { browser, page, cdp };
}

async function setupSessionState(page) {
  await page.evaluate(() => {
    localStorage.setItem("myData", "persistent-value");
  });
}

async function prepareReconnection(cdp, browser, timeout = 60000) {
  const { error, browserWSEndpoint } = await cdp.send("Browserless.reconnect", {
    timeout,
  });

  if (error) throw new Error(error);
  console.log("Reconnection endpoint:", browserWSEndpoint);

  await browser.disconnect();

  return browserWSEndpoint;
}

async function reconnectToSession(browserWSEndpoint, token) {
  const reconnectUrl = `${browserWSEndpoint}?token=${token}`;

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

  const pages = await browser.pages();
  const page = pages.find((p) => p.url().startsWith("https://example.com"));

  const cdp = await page.createCDPSession();

  return { browser, page, cdp };
}

async function closeSession(browser, page) {
  await page.evaluate(() => {
    localStorage.clear();
    sessionStorage.clear();
  });

  const cookies = await page.cookies();
  await page.deleteCookie(...cookies);

  await browser.close();
}

async function main() {
  // Step 1: Connect to Browserless
  console.log("Connecting to Browserless...");
  const { browser, page, cdp } = await connectToBrowserless();

  // Step 2: Set up session state
  console.log("Setting up session state...");
  await setupSessionState(page);

  // Step 3: Prepare for reconnection
  console.log("Preparing for reconnection...");
  const browserWSEndpoint = await prepareReconnection(cdp, browser);

  // Step 4: Reconnect to the session
  console.log("Reconnecting to session...");
  const reconnected = await reconnectToSession(browserWSEndpoint, TOKEN);

  // Verify the session state persisted
  const myData = await reconnected.page.evaluate(() => {
    return localStorage.getItem("myData");
  });
  console.log("Retrieved data:", myData); // Should show "persistent-value"

  // Step 5: Close the session
  console.log("Closing session...");
  await closeSession(reconnected.browser, reconnected.page);

  console.log("Session workflow complete!");
}

main().catch(console.error);

Reconnection timeout Limits

Reconnection timeout 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.

Standard Sessions Workflow​

Get Your API Token