Skip to main content
Version: v2

Closing Sessions

Properly closing sessions is essential for resource management and cost optimization. This guide covers both automatic cleanup for browser sessions and explicit deletion for Session API.

Browser Session Cleanup​

Browser sessions using Browserless.reconnect are automatically managed by Browserless. Sessions expire when their timeout period elapses.

Automatic Cleanup​

Browser sessions are automatically cleaned up when:

  • Reconnection timeout reached - Sessions using Browserless.reconnect expire after the configured timeout
  • Browser instance terminates - Sessions end when the browser process closes

Manual Cleanup (Optional)​

While Browserless.reconnect handles automatic cleanup, you can manually clear data before session expiration:

import puppeteer from 'puppeteer-core';

const cleanupSession = async (reconnectEndpoint) => {
  const browser = await puppeteer.connect({
    browserWSEndpoint: reconnectEndpoint || 'wss://production-sfo.browserless.io?token=YOUR_API_TOKEN',
  });

  const page = await browser.newPage();

  try {
    // Perform logout to clear server-side sessions
    await page.goto('https://app.example.com/logout');
    await page.waitForNavigation();

    // Clear local storage and cookies
    await page.evaluate(() => {
      localStorage.clear();
      sessionStorage.clear();
    });

    // Clear all cookies
    const cookies = await page.cookies();
    await page.deleteCookie(...cookies);

    console.log('Session cleaned up successfully');
  } catch (error) {
    console.error('Cleanup error:', error);
  } finally {
    await browser.close(); // Automatic cleanup when browser closes
  }
};

// Use in your workflow
await cleanupSession();

Session API Stopping​

Sessions API Only

This section covers stopping sessions created with the Sessions API (REST API for explicit session management). For Browser Sessions using Browserless.reconnect CDP command, sessions automatically clean up when their timeout expires.

Session API requires explicit stopping to terminate the session and free resources immediately. Sessions will also auto-expire when their TTL is reached.

In order to stop your session you'll first need to capture the stop property of successful creation call. See Creating Sessions for more details.

Manual Session Stopping​

const stopSession = async (sessionCloseURL) => {
  try {
    const response = await fetch(
      // https://production-sfo.browserless.io/e/123456/session/123456?token=YOUR_API_TOKEN
      sessionCloseURL,
      {
        method: 'DELETE',
      }
    );

    if (response.ok) {
      const result = await response.json();
      console.log(`Session ${sessionCloseURL} stopped:`, result);
      return true;
    } else {
      console.error(`Failed to stop session ${sessionCloseURL}:`, response.status);
      return false;
    }
  } catch (error) {
    console.error(`Error stopping session ${sessionCloseURL}:`, error);
    return false;
  }
};

// Usage
await stopSession('https://production-sfo.browserless.io/e/123456/session/123456?token=YOUR_API_TOKEN');

Automatic TTL Expiration​

Session API automatically expires when TTL (Time To Live) is reached:

// Session created with 5-minute TTL
const createSessionWithTTL = async () => {
  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 in milliseconds
      stealth: true
    }),
  });

  const { id, stop } = await response.json();
  console.log(`Session ${id} will auto-expire in 5 minutes, kill manually at ${stop}`);

  return { id, stop };
};

Advanced Session Stopping Patterns​

// Gracefully close session after completing current operations
const gracefulSessionShutdown = async (connect, stop) => {
  try {
    // First, connect to complete any pending operations
    const browser = await puppeteer.connect({
      browserWSEndpoint: connect,
    });

    const page = await browser.newPage();

    // Perform any final operations
    await page.evaluate(() => {
      // Save important data before shutdown
      const importantData = localStorage.getItem('workflowProgress');
      if (importantData) {
        // Could send to your server here
        console.log('Saving workflow progress:', importantData);
      }
    });

    // Close browser connection first
    await browser.close();

    // Then stop the session
    const response = await fetch(
      stop
      {
        method: 'DELETE',
      }
    );

    const result = await response.json();
    console.log('Session gracefully shutdown:', result);

  } catch (error) {
    console.error('Error during graceful shutdown:', error);
    // Force stop the session anyway
    await fetch(
      stop,
      {
        method: 'DELETE',
      }
    );
  }
};

Next Steps​