Browserless — unblock

When to Use

Competitor data collection: Access competitor product pages, pricing grids, or inventory data that are protected by Cloudflare or similar WAF bot detection.
Public data research: Retrieve publicly available data from sites that aggressively challenge headless browsers, such as airline fare pages or hotel availability grids.
Market intelligence pipelines: Automate recurring collection from sources that use DataDome or Akamai, where standard scraping tools are blocked.
Brand monitoring: Check brand mentions, reviews, or forum posts on sites with bot protection, on a scheduled workflow.
WebSocket handoff for complex automation: Use browserWSEndpoint mode to obtain a live browser connection and hand it to a downstream execute step for further interaction.

Legal and ethical use: Only use the unblock operation against sites where you have legitimate authorisation to access data programmatically. Bypassing bot protection on sites where scraping is prohibited by terms of service may carry legal risk. Always obtain legal review before building unblock-based workflows against third-party sites.

Configuration

Connection

Field	Required	Description
`BaseUrl`	Required	Browserless instance URL. Cloud unblock requires a plan that includes stealth features.
`Token`	Optional	API token for cloud Browserless.

Operation

Field	Required	Description
`url`	Required	The protected page URL to unblock. Supports BizFirst expressions.
`content`	Optional	Default `true`. When `true`, the response includes the page HTML in the `html` field.
`screenshot`	Optional	Default `true`. When `true`, the response includes a base64-encoded screenshot in the `screenshotBase64` field.
`browserWSEndpoint`	Optional	Default `true`. When `true`, the response includes a WebSocket endpoint URL for connecting to the live browser session with Puppeteer or Playwright.
`ttl`	Optional	Time-to-live in milliseconds for the browser WebSocket session. Only relevant when `browserWSEndpoint` is `true`.
`gotoOptions`	Optional	Navigation options JSON: `waitUntil` and `timeout`.
`waitForSelector`	Optional	Wait for a CSS selector to appear after the bot challenge is passed.
`waitForTimeout`	Optional	Fixed delay in milliseconds after the challenge is cleared before capturing output.
`setExtraHTTPHeaders`	Optional	Additional request headers to set before navigation.
`bestAttempt`	Optional	Default `true`. Return available output even if the challenge was not fully resolved.
`blockAds`	Optional	Default `true`.
`useCustomBody`	Optional	Send `customBodyJson` verbatim as the request body.
`customBodyJson`	Optional	Raw JSON body when `useCustomBody` is `true`.

Sample Configuration

{
  "operation": "unblock",
  "baseUrl": "https://chrome.browserless.io",
  "token": "{{ $env.BROWSERLESS_TOKEN }}",
  "url": "https://protected.example.com/pricing",
  "content": true,
  "screenshot": false,
  "browserWSEndpoint": false,
  "gotoOptions": { "waitUntil": "networkidle2", "timeout": 45000 },
  "waitForSelector": { "selector": ".pricing-table", "timeout": 15000 },
  "blockAds": true,
  "bestAttempt": true
}

Validation Errors

Error Code	Cause
`VAL_MISSING_URL`	`url` is empty.
`CFG_INVALID`	Node settings could not be resolved to an unblock configuration.
`BROWSERLESS_BAD_REQUEST`	`customBodyJson` is not valid JSON or does not match the unblock request shape.

Output

Success Port

Field	Type	Description
`status`	string	Always `"success"`.
`errorCode`	string	Always empty on success.
`operation`	string	Always `"unblock"`.
`url`	string	URL that was unblocked.
`html`	string	Rendered page HTML (populated when `content: true`).
`screenshotBase64`	string	Base64-encoded PNG screenshot (populated when `screenshot: true`).
`browserWSEndpoint`	string	WebSocket URL of the live browser session (populated when `browserWSEndpoint: true`).

Error Port

Field	Type	Description
`status`	string	Always `"error"`.
`errorCode`	string	Machine-readable error code.
`errorMessage`	string	Human-readable failure description.
`operation`	string	Always `"unblock"`.
`httpStatusCode`	int	HTTP status code from Browserless, if available.

Sample Output

{
  "status": "success",
  "errorCode": "",
  "operation": "unblock",
  "url": "https://protected.example.com/pricing",
  "html": "<!DOCTYPE html><html><head><title>Pricing — Example</title></head><body><table class=\"pricing-table\"><tr><td>Starter</td><td>$29/mo</td></tr><tr><td>Pro</td><td>$99/mo</td></tr></table></body></html>",
  "screenshotBase64": "",
  "browserWSEndpoint": ""
}

Expression Reference

Expression	Value
`{{ $output.BrowserlessNode.html }}`	Rendered HTML of the unblocked page.
`{{ $output.BrowserlessNode.screenshotBase64 }}`	Base64 PNG screenshot string.
`{{ $output.BrowserlessNode.browserWSEndpoint }}`	WebSocket URL for the live browser session.
`{{ $output.BrowserlessNode.url }}`	URL that was unblocked.

Node Policies & GuardRails

Policy	Recommendation	Severity
Legal compliance	Verify that bypassing bot protection on the target site is permitted. Document legal review in your workflow notes.	Critical
Token storage	Store the API token in a workflow secret — never hardcode it.	Critical
URL validation	Allowlist target domains; never pass user-supplied URLs without validation to prevent SSRF.	High
WebSocket TTL	If using `browserWSEndpoint`, set `ttl` to the shortest duration sufficient for downstream steps. Open browser sessions consume Browserless plan minutes.	Medium
Timeout for challenges	Bot challenges can take 5–20 s to solve. Set `gotoOptions.timeout` to at least 45 s for protected sites.	Medium

Examples

Example 1 — Extract HTML from a Cloudflare-protected site

{
  "operation": "unblock",
  "baseUrl": "https://chrome.browserless.io",
  "token": "{{ $env.BROWSERLESS_TOKEN }}",
  "url": "{{ $input.targetUrl }}",
  "content": true,
  "screenshot": false,
  "browserWSEndpoint": false,
  "gotoOptions": { "waitUntil": "networkidle2", "timeout": 60000 },
  "blockAds": true,
  "bestAttempt": true
}

Example 2 — Screenshot proof of a protected page

{
  "operation": "unblock",
  "baseUrl": "https://chrome.browserless.io",
  "token": "{{ $env.BROWSERLESS_TOKEN }}",
  "url": "https://market-data.example.com/live-prices",
  "content": false,
  "screenshot": true,
  "browserWSEndpoint": false,
  "waitForSelector": { "selector": ".price-feed", "timeout": 20000 },
  "gotoOptions": { "waitUntil": "networkidle2", "timeout": 60000 }
}

Example 3 — Obtain a live WebSocket session for downstream automation

{
  "operation": "unblock",
  "baseUrl": "https://chrome.browserless.io",
  "token": "{{ $env.BROWSERLESS_TOKEN }}",
  "url": "https://protected-app.example.com/login",
  "content": false,
  "screenshot": false,
  "browserWSEndpoint": true,
  "ttl": 120000,
  "gotoOptions": { "waitUntil": "networkidle2", "timeout": 60000 }
}