Browserless — Configuration

ApiToken is required on every operation. All operations require ApiToken set to your Browserless.io API key. This is not repeated in each table.

Url or Html is required on most operations. For content, pdf, screenshot, scrape, execute, and performance, provide either Url (navigate to a URL) or Html (render an HTML string directly). The download operation requires Url only. The unblock operation requires Url only.

Common Properties (Shared Across Most Operations)

These properties are available on content, pdf, screenshot, scrape, and execute. Individual operations may not support all of them — see per-operation notes where restrictions apply.

Property	Required	Description
`Url`	Optional*	URL to navigate to. Required if `Html` is not provided.
`Html`	Optional*	Raw HTML string to render in the browser. Required if `Url` is not provided.
`BestAttempt`	Optional	Boolean. Default `true`. When `true`, returns a partial result if the page times out rather than returning an error.
`WaitForTimeoutMs`	Optional	Integer. Milliseconds to wait after page load before capturing. Useful for animations or deferred content.
`JavaScriptEnabled`	Optional	Boolean. Default `true`. Set `false` to disable JavaScript execution (faster for static HTML).
`EmulateMediaType`	Optional	Enum: `screen` or `print`. Useful for PDF generation using print stylesheets.
`UserAgent`	Optional	Custom user agent string to use. Overrides the default Chromium user agent.
`Viewport`	Optional	JSON object: `{"width": 1280, "height": 800, "deviceScaleFactor": 1}`. Sets the browser viewport dimensions.
`GotoOptions`	Optional	JSON object of Puppeteer `goto` options: `{"waitUntil": "networkidle0", "timeout": 30000}`. Controls page load wait strategy.
`WaitForSelector`	Optional	CSS selector string. The browser waits until this element appears in the DOM before capturing.
`WaitForEvent`	Optional	DOM event name to wait for before capturing (e.g. `load`, `DOMContentLoaded`).
`WaitForFunction`	Optional	JavaScript expression that must evaluate to `true` before capturing (e.g. `window.__appReady === true`).
`Authenticate`	Optional	JSON object for HTTP Basic Auth: `{"username": "user", "password": "pass"}`.
`ExtraHttpHeaders`	Optional	JSON object of additional request headers to send with every request (e.g. `{"X-API-Key": "abc123"}`).
`AddScriptTags`	Optional	Array of script objects to inject: `[{"url": "https://cdn.example.com/lib.js"}]` or `[{"content": "window.myVar = 1;"}]`.
`AddStyleTags`	Optional	Array of style objects to inject: `[{"url": "https://cdn.example.com/style.css"}]` or `[{"content": "body{font-size:14px;}"}]`.
`RejectResourceTypes`	Optional	Array of resource types to block. Values: `"image"`, `"media"`, `"font"`, `"stylesheet"`, `"script"`. Blocking reduces bandwidth and speeds up requests.
`RejectRequestPattern`	Optional	Array of URL patterns (strings or regex) to block. Example: `["analytics.google.com", "doubleclick.net"]`.
`RequestInterceptors`	Optional	Array of request interceptor objects to modify outgoing requests before they are sent.
`Cookies`	Optional	Array of cookie objects to inject: `[{"name": "session", "value": "abc", "domain": "example.com"}]`.
`BlockAds`	Optional	Boolean. Default `true`. Blocks common ad network requests automatically.

Per-Operation Extra Properties

content

Renders the page and returns the fully executed HTML. No additional properties beyond common ones.

download

Downloads a binary file from a URL. Requires Url only. Common browser controls (viewport, scripts, etc.) do not apply.

Property	Required	Description
`Url`	Required	URL of the file to download.

pdf

Generates a PDF from a URL or HTML. Extra properties control the output format and margins.

Property	Required	Description
`Format`	Optional	Paper size format. Enum: `A4`, `Letter`, `A3`, `A5`, `Legal`, `Tabloid`. Default: `Letter`.
`PrintBackground`	Optional	Boolean. When `true`, renders background colours and images. Default: `false`.
`MarginTop`	Optional	Top margin (e.g. `"1cm"`, `"10mm"`, `"0.5in"`).
`MarginBottom`	Optional	Bottom margin.
`MarginLeft`	Optional	Left margin.
`MarginRight`	Optional	Right margin.

performance

Runs a Lighthouse audit on the provided URL. Common browser properties apply. Requires Url — does not support Html.

Returns full Lighthouse JSON including First Contentful Paint (FCP), Largest Contentful Paint (LCP), Cumulative Layout Shift (CLS), Time to Interactive (TTI), and category scores (Performance, Accessibility, Best Practices, SEO).

screenshot

Captures a screenshot. Extra properties control output format, quality, and crop area.

Property	Required	Description
`FullPage`	Optional	Boolean. When `true`, captures the full scrollable page height. Default: `false` (viewport only).
`Type`	Optional	Image format. Enum: `png` (lossless) or `jpeg` (smaller). Default: `png`.
`Quality`	Optional	Integer (1–100). JPEG quality. Only applies when `Type=jpeg`.
`Clip`	Optional	JSON object to crop the screenshot: `{"x": 0, "y": 0, "width": 800, "height": 600}`.

scrape

Extracts structured data using CSS selector rules. The Elements property is required.

Property	Required	Description
`Elements`	Required	Array of selector rule objects. Each object has a `selector` (CSS selector string) and a `results` array of extraction rules. See selector syntax note below.

Extraction rule types within each results item:

Type	Description
`text`	Inner text content of the matched element (equivalent to `element.innerText`).
`attribute`	Value of a specific HTML attribute. Requires `attribute` field (e.g. `"href"`, `"src"`, `"data-price"`).
`html`	Full inner HTML of the matched element.
`eval`	Custom JavaScript expression evaluated in the element's context. Requires `fn` field (e.g. `"el => el.getAttribute('data-price').replace('$','')"`).

unblock

Navigates to a URL using advanced bot-detection bypass techniques. Only supports Url (not Html).

Property	Required	Description
`Url`	Required	URL of the bot-protected page to access.
`TtlSeconds`	Optional	Integer. Cache the unblocked response for this many seconds. Subsequent requests to the same URL return cached HTML.
`Tokens`	Optional	Integer. Maximum number of AI tokens to spend on bot-detection solving. Higher values improve success rate on harder challenges.

execute

Loads the page and runs custom JavaScript in the browser context.

Property	Required	Description
`Code`	Required	JavaScript code string to execute in the page context. Has access to the DOM (`document`, `window`) and can return any serialisable value.

// Example Code value:
return document.querySelector('.product-price')?.textContent.trim() ?? null;