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.

Manual Session Stopping

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

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

// Usage
await stopSession('session-abc123');

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 { sessionId } = await response.json();
console.log(`Session ${sessionId} will auto-expire in 5 minutes`);

return sessionId;
};

// Monitor session status
const monitorSession = async (sessionId) => {
const checkStatus = async () => {
try {
const response = await fetch(
`https://production-sfo.browserless.io/session/${sessionId}?token=YOUR_API_TOKEN`
);

if (response.ok) {
const sessionInfo = await response.json();
console.log('Session active:', sessionInfo);
return true;
} else {
console.log('Session expired or not found');
return false;
}
} catch (error) {
console.log('Session no longer accessible:', error.message);
return false;
}
};

// Check every minute
const interval = setInterval(async () => {
const isActive = await checkStatus();
if (!isActive) {
clearInterval(interval);
}
}, 60000);
};

Advanced Session Stopping Patterns

// Gracefully close session after completing current operations
const gracefulSessionShutdown = async (sessionId) => {
try {
// First, connect to complete any pending operations
const browser = await puppeteer.connect({
browserWSEndpoint: `wss://production-sfo.browserless.io/session/connect/${sessionId}?token=YOUR_API_TOKEN`,
});

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(
`https://production-sfo.browserless.io/session?token=YOUR_API_TOKEN`,
{
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ stop: sessionId })
}
);

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(
`https://production-sfo.browserless.io/session?token=YOUR_API_TOKEN`,
{
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ stop: sessionId })
}
);
}
};

Next Steps