Skip to main content
A session is a remote browser instance that you control. When you call playwright.connect(), you create a session.

​
Session Lifecycle

Create → Use → Close

// 1. Create session
const session = await playwright.connect({
  apiKey: process.env.BCTRL_API_KEY
});

// 2. Use session
await session.page.goto('https://example.com');
await session.page.locator('button').click();

// 3. Close session
await session.close();

​
What’s in a Session?

When you create a session, you get:
PropertyDescription
session.idUnique session identifier
session.browserBrowser instance (Playwright/Puppeteer)
session.contextDefault browser context
session.pageDefault page (tab)
session.stagehandAI agent namespace
session.browserUseBrowser-use agent namespace

​
Session Options

Configure sessions at creation: 
const session = await playwright.connect({
  apiKey: process.env.BCTRL_API_KEY,
  sessionOptions: {
    // Driver
    driver: 'playwright',           // 'playwright' | 'puppeteer' | 'selenium' | 'stagehand'

    // Display
    screen: { width: 1920, height: 1080 },

    // Anti-detection
    useStealth: true,               // Enable stealth mode
    humanize: true,                 // Human-like mouse movements
    humanizePersonaId: 42,          // Specific movement persona (0-124)

    // Proxy
    useProxy: true,
    proxyCountry: 'US',             // 'US', 'UK', 'DE', etc.

    // Profile
    profile: { id: 'profile-uuid' }, // Use existing profile

    // Timeout
    timeoutMinutes: 60              // Session timeout (default: 30)
  }
});

​
Session Timeout

Sessions automatically close after inactivity:
  • Default: 30 minutes
  • Maximum: Depends on your plan
  • Manual: Always call session.close() when done
// Extend timeout at creation
const session = await playwright.connect({
  apiKey: '...',
  sessionOptions: {
    timeoutMinutes: 120  // 2 hours
  }
});
Unclosed sessions consume resources. Always close sessions when done.

​
Multiple Sessions

You can run multiple sessions concurrently: 
// Create multiple sessions
const session1 = await playwright.connect({ apiKey: '...' });
const session2 = await playwright.connect({ apiKey: '...' });

// Use them in parallel
await Promise.all([
  session1.page.goto('https://site1.com'),
  session2.page.goto('https://site2.com')
]);

// Close both
await session1.close();
await session2.close();

​
Session IDs

Every session has a unique ID: 
const session = await playwright.connect({ apiKey: '...' });
console.log('Session ID:', session.id);
// "sess_abc123xyz"
Use session IDs for:
  • Debugging and logging
  • API calls to check session status
  • Support requests

​
Session vs Browser vs Context vs Page

Session
└── Browser
    └── Context (isolated environment)
        └── Page (tab)
  • Session: Your connection to a remote browser
  • Browser: The Chrome instance
  • Context: Isolated environment with own cookies/storage
  • Page: A single tab
const session = await playwright.connect({ apiKey: '...' });

// Default hierarchy
const browser = session.browser;
const context = session.context;    // Default context
const page = session.page;          // Default page

// Create more
const context2 = await browser.newContext();
const page2 = await context.newPage();

​
Error Handling

try {
  const session = await playwright.connect({ apiKey: '...' });
  await session.page.goto('https://example.com');
  await session.close();
} catch (error) {
  if (error.message.includes('Session not found')) {
    // Session expired or invalid
  } else if (error.message.includes('timeout')) {
    // Command timed out
  }
  console.error('Session error:', error);
}

​
Best Practices

const session = await playwright.connect({ apiKey: '...' });
try {
  // Your code
} finally {
  await session.close();
}
Set timeoutMinutes based on your task duration. Don’t set excessively long timeouts.
Wrap session code in try/catch and always close in finally block.