Skip to main content

Timeout Configuration

This document explains how to configure timeouts for Browserless REST APIs. Proper timeout configuration is essential for reliable browser automation, especially when dealing with slow-loading pages or complex interactions.

Overview​

Browserless REST APIs support timeout configuration through two methods:

  1. Query Parameter Timeout: Global timeout for the entire request
  2. JSON Body Timeout Parameters: Granular timeout control for specific operations

All timeout values are specified in milliseconds.

Query Parameter Timeout​

You can set a global timeout for any REST API request using the timeout query parameter. This controls the maximum duration for the entire operation.

For detailed information about query parameter timeouts, see the Launch Parameters documentation.

JSON Body Timeout Parameters​

REST APIs support several timeout parameters in the JSON request body for fine-grained control over different operations. For full details on what each option does and its available parameters, see the Request Configuration page.

Controls how long to wait for page navigation to complete. This is part of the gotoOptions object which mirrors Puppeteer's GoToOptions interface.

curl -X POST \
  "https://production-sfo.browserless.io/content?token=YOUR_API_TOKEN_HERE" \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://example.com/",
  "gotoOptions": {
    "timeout": 30000,
    "waitUntil": "networkidle2"
  }
}'

Selector Timeouts (waitForSelector.timeout)​

Controls how long to wait for a specific element to appear on the page. If the element doesn't appear within the timeout period, the operation will fail (unless bestAttempt is enabled). See waitForSelector for full parameter details.

curl -X POST \
  "https://production-sfo.browserless.io/screenshot?token=YOUR_API_TOKEN_HERE" \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://example.com/",
  "waitForSelector": {
    "selector": "#main-content",
    "timeout": 10000,
    "visible": true
  }
}' \
  --output "screenshot.png"

Function Timeouts (waitForFunction.timeout)​

Controls how long to wait for a custom JavaScript function to return a truthy value. Useful for waiting on complex conditions or asynchronous operations. See waitForFunction for full parameter details.

curl -X POST \
  "https://production-sfo.browserless.io/content?token=YOUR_API_TOKEN_HERE" \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://example.com/",
  "waitForFunction": {
    "fn": "() => document.title === \"Example Domain\"",
    "timeout": 15000
  }
}'

Event Timeouts (waitForEvent.timeout)​

Controls how long to wait for a specific custom event to fire before proceeding with the operation. See waitForEvent for full parameter details.

warning

waitForEvent only works with custom events, not lifecycle events like load or DOMContentLoaded. Use gotoOptions.waitUntil for lifecycle events.

curl -X POST \
  "https://production-sfo.browserless.io/content?token=YOUR_API_TOKEN_HERE" \
  -H 'Content-Type: application/json' \
  -d '{
  "html": "<html><body><h1>Test</h1><script>setTimeout(() => document.dispatchEvent(new Event(\"customReady\")), 1000);</script></body></html>",
  "waitForEvent": {
    "event": "customReady",
    "timeout": 5000
  }
}'

Fixed Delay Timeout (waitForTimeout)​

Waits for a specified number of milliseconds before proceeding. Useful when you need to wait for animations, transitions, or other time-based operations to complete. See waitForTimeout for full parameter details.

curl -X POST \
  "https://production-sfo.browserless.io/scrape?token=YOUR_API_TOKEN_HERE" \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://example.com/",
  "elements": [
    { "selector": "h1" }
  ],
  "waitForTimeout": 3000
}'

Combining Multiple Timeout Parameters​

You can combine multiple timeout parameters in a single request for comprehensive control over the browser automation process:

curl -X POST \
  "https://production-sfo.browserless.io/screenshot?token=YOUR_API_TOKEN_HERE&timeout=60000" \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://example.com/",
  "gotoOptions": {
    "timeout": 30000,
    "waitUntil": "networkidle2"
  },
  "waitForSelector": {
    "selector": "h1",
    "timeout": 10000,
    "visible": true
  },
  "waitForTimeout": 2000
}' \
  --output "screenshot.png"

Best Practices​

  1. Set Realistic Timeouts: Don't set timeouts too low for slow-loading content, but avoid unnecessarily high values that could delay error detection.

  2. Use Appropriate waitUntil Options: Choose the right navigation completion criteria for your use case. See Navigation Options for the full list of available values.

  3. Combine Timeouts Strategically: Use navigation timeouts for page loading, selector timeouts for dynamic content, and fixed delays sparingly.

  4. Monitor Total Request Time: Remember that the query parameter timeout applies to the entire request, including all wait operations.

  5. Handle Timeout Errors: Always implement proper error handling for timeout scenarios in your application code.