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 at the moment of calling this API, the selector already exists, the method will return immediately. If the selector doesn't appear after the timeout milliseconds of waiting, the API will return a non-200 response code 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 to be dispatched on the page. This is useful for waiting on application-specific events that will be triggered after the page loads.

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.

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
  }
}'
warning

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

To customize the navigation behavior when loading a page, such as specifying when to consider the page fully loaded (e.g., waiting for network activity to settle), you can use the gotoOptions parameter. The objects 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​

You can use rejectResourceTypes and rejectRequestPattern to block undesired 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​

You can use bestAttempt to make Browserless attempt to proceed when async events fail or timeout. This includes things like the goto or waitForSelector properties in the JSON payload. With bestAttempt: true, the request will continue even if a timeout operation fails, allowing you to capture partial results.

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 something like "Error 403 - Forbidden", you'll find that 403 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

This means a successful Browserless API call (HTTP 200) can still indicate that the target site returned an error (e.g., 403, 404, 500) - check the X-Response-Code header to determine the actual site response.