Skip to main content

Request Configuration

This page documents configuration options shared across all REST API endpoints. The examples below use /content for demonstration, but every option works the same way on any endpoint. For an exhaustive list of all parameters and response schemas, see the OpenAPI specification.

Waiting for Things​

Browserless offers 4 different ways to wait for preconditions to be met on the page before returning the response. These are timeouts, selectors, functions and events.

waitForTimeout​

Waits for a specified number of milliseconds before continuing. Useful when you need to wait for animations, transitions, or other time-based operations to complete.

Parameters​

  • waitForTimeout: Number, required: The number of milliseconds to wait.

Example

curl -X POST \
  "https://production-sfo.browserless.io/content?token=YOUR_API_TOKEN_HERE" \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://example.com/",
  "waitForTimeout": 10000
}'

waitForSelector​

Waits for a selector to appear on the page. If the selector already exists when the request arrives, Browserless returns immediately. If the selector doesn't appear within the timeout, the API returns a non-200 response with an error message.

Parameters​

  • selector: String, required: A valid CSS selector.
  • hidden: Boolean, optional: Wait for the selected element to not be found in the DOM or to be hidden, i.e. have display: none or visibility: hidden CSS properties.
  • timeout: Number, optional: Maximum number of milliseconds to wait for the selector before failing.
  • visible: Boolean, optional: Wait for the selected element to be present in DOM and to be visible, i.e. to not have display: none or visibility: hidden CSS properties.

Example

curl -X POST \
  "https://production-sfo.browserless.io/content?token=YOUR_API_TOKEN_HERE" \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://example.com/",
  "waitForSelector": {
    "selector": "h1",
    "timeout": 5000
  }
}'

waitForFunction​

Waits for the provided function to return before continuing. The function can be any valid JavaScript function including async functions.

Parameters​

  • fn: String, required: A stringified JavaScript function to evaluate. Must return a truthy value to signal completion.
  • timeout: Number, optional: Maximum number of milliseconds to wait for the function to return before failing.

Example

JS function:

async () => {
  const res = await fetch("https://jsonplaceholder.typicode.com/todos/1");
  const json = await res.json();
  document.querySelector("h1").innerText = json.title;
  return true;
};
curl -X POST \
  "https://production-sfo.browserless.io/content?token=YOUR_API_TOKEN_HERE" \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://example.com/",
  "waitForFunction": {
    "fn": "async()=>{const res=await fetch(\"https://jsonplaceholder.typicode.com/todos/1\");const json=await res.json();document.querySelector(\"h1\").innerText=json.title;return true}",
    "timeout": 5000
  }
}'

waitForEvent​

Waits for a custom event dispatched by the page. Use this for application-specific events your code fires after page load.

Browserless registers the event listener on both window and document, so you can dispatch from either:

// Both of these work
window.dispatchEvent(new Event('customReady'));
document.dispatchEvent(new Event('customReady'));

Parameters​

  • event: String, required: The name of the custom event to wait for.
  • timeout: Number, optional: Maximum number of milliseconds to wait for the event before failing. Default: 30,000ms.

Example

This example waits for a custom event that the page will dispatch:

curl -X POST \
  "https://production-sfo.browserless.io/content?token=YOUR_API_TOKEN_HERE" \
  -H 'Cache-Control: no-cache' \
  -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
  }
}'

If the event never fires, the behavior depends on bestAttempt:

  • bestAttempt: false (default): returns HTTP 408
  • bestAttempt: true: proceeds with whatever page state exists
warning

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

Pass gotoOptions to customize navigation behavior, such as specifying when to consider the page fully loaded. The options mirror Puppeteer's GoToOptions interface.

Example

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

waitUntil options

  • load: Fires when the entire page has loaded, including all dependent resources such as stylesheets, scripts, and images.
  • domcontentloaded: Fires when the initial HTML document has been fully parsed, without waiting for stylesheets, images, or subframes to finish loading.
  • networkidle0: Fires when there are zero network connections for at least 500ms. Best for pages that fully finish loading all resources.
  • networkidle2: Fires when there are no more than 2 network connections for at least 500ms. Best for pages that keep long-polling or background connections open.

Rejecting Undesired Requests​

Use rejectResourceTypes and rejectRequestPattern to block specific content, resources, and requests. For the full schema of available resource types, see the REST API Swagger Schema.

Example

curl -X POST \
  "https://production-sfo.browserless.io/content?token=YOUR_API_TOKEN_HERE" \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://browserless.io/",
  "rejectResourceTypes":["image"],
  "rejectRequestPattern": ["/^.*\\.(css)"]
}'

Continue on Error​

Use bestAttempt: true to tell Browserless to proceed when async events fail or time out. This applies to operations like goto and waitForSelector. The request continues even if a timeout fires, returning whatever page state exists at that point.

Example

curl -X POST \
  "https://production-sfo.browserless.io/content?token=YOUR_API_TOKEN_HERE" \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://example.com/",
  "bestAttempt": true,
  "waitForSelector": { "selector": "table", "timeout": 500 }
}'

Response codes from sites​

When you make a REST API call to Browserless, you may receive an HTTP 200 status code indicating that the connection between Browserless and your client was successful. However, the underlying site that Browserless visits may return a different status response code.

Browserless propagates the actual site's response code through response headers. If a site returns an error like 403, find the status code in the response headers under X-Response-Code.

Response headers provided:

  • X-Response-Code: The HTTP status code from the target site
  • X-Response-Status: The status text from the target site
  • X-Response-URL: The final URL after any redirects
  • X-Response-IP: The IP address of the target site
  • X-Response-Port: The port used to connect to the target site

A successful Browserless API call (HTTP 200) can still mean the target site returned an error (e.g., 403, 404, 500). Check the X-Response-Code header to determine the actual site response.