ZenRows Scraping Browser lets you control the duration of your browser sessions with Session TTL (Time To Live) configuration. This is crucial for managing resource usage, maintaining session consistency, and optimizing scraping workflows.

​
What is Session TTL?

Session TTL (Time To Live) controls how long a browser session stays active before terminating. Think of it as a timer for your scraping session after the time expires, the session closes automatically, freeing up resources and ensuring clean session management.

Why Session TTL matters:

  • Resource Management: Prevents sessions from running indefinitely
  • Cost Control: Helps manage usage costs by auto-terminating idle sessions
  • Session Consistency: Maintains stable connections for multi-step workflows
  • Workflow Optimization: Lets you match session duration to your scraping needs

The default Session TTL is 3 minutes (180 seconds), which works well for most tasks. You can customize this between 1 minute (60 seconds) and 15 minutes (900 seconds).

​
How to Configure Session TTL

You can configure Session TTL in two ways:

  • ZenRows SDK: Recommended for most users (simple, robust)
  • Direct WebSocket URL: For advanced or custom integrations

For advanced users or custom integrations, specify Session TTL in the WebSocket URL using the session_ttl parameter with duration strings.

wss://browser.zenrows.com?apikey=YOUR_ZENROWS_API_KEY&session_ttl=2m

Duration String Examples:

  • 1m - 1 minute (60 seconds)
  • 2m - 2 minutes (120 seconds)
  • 5m - 5 minutes (300 seconds)
  • 10m - 10 minutes (600 seconds)
  • 15m - 15 minutes (900 seconds - max)
const puppeteer = require('puppeteer-core');
const wsUrl = 'wss://browser.zenrows.com?apikey=YOUR_ZENROWS_API_KEY&session_ttl=5m';
(async () => {
    const browser = await puppeteer.connect({ browserWSEndpoint: wsUrl });
    const page = await browser.newPage();
    await page.goto('https://example.com');
    await browser.close();
})();

​
Choosing the Right Session TTL

Session Duration Guidelines:

1-2 Minutes (60-120 seconds):

  • Quick data extraction from single pages
  • Simple form submissions
  • Basic content scraping
  • Testing and development

3-5 Minutes (180-300 seconds):

  • Multi-page navigation
  • Workflows with several steps
  • Moderate data collection
  • Most general scraping

10-15 Minutes (600-900 seconds):

  • Complex multi-step workflows
  • Large-scale extraction
  • User interaction simulation
  • Long-running automation

​
Combining Session TTL with Other Features

Session TTL works seamlessly with other ZenRows features for advanced scraping setups.

​
Session TTL + Country Targeting

Node.js
const connectionURL = scrapingBrowser.getConnectURL({
    sessionTTL: 300, // 5 minutes
    proxy: { location: ProxyCountry.ES },
});

​
Session TTL + World Region Targeting

Node.js
const connectionURL = scrapingBrowser.getConnectURL({
    sessionTTL: 600, // 10 minutes
    proxy: { location: ProxyRegion.Europe },
});

​
Direct WebSocket with Multiple Parameters

wss://browser.zenrows.com?apikey=YOUR_API_KEY&session_ttl=8m&proxy_country=us

​
Best Practices

Optimize for Your Workflow:

  • Match session duration to your scraping needs
  • Add a small buffer (30-60 seconds) for delays
  • Use shorter sessions for simple tasks

SDK vs Direct Connection:

  • SDK: Use for most projects and handles sessions automatically
  • Direct WebSocket: Use for custom frameworks or specific control

Monitoring and Debugging:

  • Monitor session usage in the ZenRows dashboard
  • Log session start/end times
  • Use proper durations to avoid premature expiry

Error Handling:

Node.js
try {
    const browser = await puppeteer.connect({ browserWSEndpoint: connectionURL });
    // Your scraping code
} catch (error) {
    if (error.message.includes('session expired')) {
        console.log('Session TTL expired, consider increasing duration');
    }
    // Other errors
}

​
Troubleshooting

Common Issues and Solutions:

Session Expires Too Quickly:

  • Increase sessionTTL for more time
  • Monitor execution time and add buffer
  • Break long workflows into smaller sessions

Invalid TTL Values:

  • TTL must be 60-900 seconds in SDK
  • Use valid duration strings (1m, 2m, etc.) for WebSocket
  • Match TTL to workflow

Session Management Issues:

  • Always close browser connections properly
  • Handle session expiration errors
  • Monitor usage in the Analytics dashboard

The sessionTTL parameter uses seconds with the SDK (e.g., 120 for 2 min) and duration strings for direct WebSocket (e.g., “2m”).

​
Next Steps