Browserless — screenshot

When to Use

Visual regression testing: Capture a page screenshot after each deployment and compare it to a baseline image to detect unexpected visual changes.
Automated reporting: Take a screenshot of a dashboard or chart at a scheduled time and attach it to a Slack message, email, or PDF report.
Competitor monitoring: Screenshot a competitor's pricing page daily and store the images in S3 for visual review without storing HTML.
Proof-of-delivery archives: Screenshot a web confirmation page after processing a transaction and store it as an audit record.
Social media previews: Render an Open Graph image dynamically from a template URL and capture it as a PNG for upload to the social platform.

Configuration

Connection

Field	Required	Description
`BaseUrl`	Required	Browserless instance URL.
`Token`	Optional	API token for cloud Browserless.

Operation

Field	Required	Description
`url`	Required	The page URL to capture. Supports BizFirst expressions.
`options`	Optional	Screenshot options JSON object. Key fields: `type` (`"png"` or `"jpeg"`, default `"png"`), `fullPage` (bool, default `false`), `quality` (int 0–100, JPEG only), `clip` (viewport crop object with `x`, `y`, `width`, `height`).
`selector`	Optional	CSS selector of a specific element to capture. When set, only that element is screenshotted rather than the full page or viewport.
`gotoOptions`	Optional	Navigation options JSON: `waitUntil` and `timeout`.
`waitForSelector`	Optional	Wait for a CSS selector to appear before taking the screenshot.
`waitForTimeout`	Optional	Fixed delay in milliseconds before capture (e.g. to let animations finish).
`viewport`	Optional	Viewport dimensions JSON: `{ "width": 1440, "height": 900 }`.
`userAgent`	Optional	Override the browser user-agent string.
`setExtraHTTPHeaders`	Optional	Additional HTTP request headers.
`cookies`	Optional	Cookies to set before navigation.
`blockAds`	Optional	Default `true`. Block ad networks.
`bestAttempt`	Optional	Default `true`. Return a screenshot even if some sub-resources failed.
`useCustomBody`	Optional	Send `customBodyJson` verbatim as the request body.
`customBodyJson`	Optional	Raw JSON body when `useCustomBody` is `true`.

Sample Configuration

{
  "operation": "screenshot",
  "baseUrl": "https://chrome.browserless.io",
  "token": "{{ $env.BROWSERLESS_TOKEN }}",
  "url": "https://app.example.com/dashboard/{{ $input.tenantId }}",
  "options": {
    "type": "png",
    "fullPage": false
  },
  "viewport": { "width": 1440, "height": 900 },
  "gotoOptions": { "waitUntil": "networkidle2", "timeout": 20000 },
  "waitForSelector": { "selector": ".chart-container", "timeout": 10000 },
  "blockAds": true
}

Validation Errors

Error Code	Cause
`VAL_MISSING_URL`	`url` is empty and no `html` source was provided.
`CFG_INVALID`	Node settings could not be resolved to a screenshot configuration.
`BROWSERLESS_BAD_REQUEST`	`customBodyJson` is not valid JSON or does not match the screenshot request shape.

Output

Success Port

Field	Type	Description
`status`	string	Always `"success"`.
`errorCode`	string	Always empty on success.
`operation`	string	Always `"screenshot"`.
`url`	string	URL that was captured.
`mimeType`	string	`"image/png"` or `"image/jpeg"`.
`fileName`	string	Suggested file name, e.g. `"screenshot.png"`.
`sizeBytes`	int	Image size in bytes.
`data`	bytes	Raw image bytes. Pass to an S3 upload node or file-write node directly.

Error Port

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

Sample Output

{
  "status": "success",
  "errorCode": "",
  "operation": "screenshot",
  "url": "https://app.example.com/dashboard/tenant-42",
  "mimeType": "image/png",
  "fileName": "screenshot.png",
  "sizeBytes": 218430,
  "data": "<binary image bytes>"
}

Expression Reference

Expression	Value
`{{ $output.BrowserlessNode.mimeType }}`	`"image/png"` or `"image/jpeg"`.
`{{ $output.BrowserlessNode.fileName }}`	Suggested file name for storage.
`{{ $output.BrowserlessNode.sizeBytes }}`	Image size in bytes.
`{{ $output.BrowserlessNode.data }}`	Raw image bytes — pass directly to upload nodes.
`{{ $output.BrowserlessNode.url }}`	URL that was captured.

Node Policies & GuardRails

Policy	Recommendation	Severity
URL validation	Validate and allowlist target domains before passing user-supplied URLs to prevent SSRF via the Browserless service.	High
Token storage	Store the API token in a workflow secret — never hardcode it in the node configuration JSON.	Critical
Image storage	The `data` field contains raw bytes. Store via an S3 or file node rather than logging the binary payload.	Medium
Full-page vs. viewport	Full-page screenshots of long pages can be very large (several MB). Use viewport mode or `clip` for targeted captures unless full-page is explicitly required.	Medium
Concurrent session limits	Implement retry logic with exponential backoff for `429` errors when running screenshot workflows at high volume.	Medium

Examples

Example 1 — Full-page PNG for archive

{
  "operation": "screenshot",
  "baseUrl": "https://chrome.browserless.io",
  "token": "{{ $env.BROWSERLESS_TOKEN }}",
  "url": "{{ $input.pageUrl }}",
  "options": { "type": "png", "fullPage": true },
  "viewport": { "width": 1280, "height": 800 },
  "gotoOptions": { "waitUntil": "networkidle2", "timeout": 30000 },
  "blockAds": true
}

Example 2 — JPEG thumbnail of specific element

{
  "operation": "screenshot",
  "baseUrl": "https://chrome.browserless.io",
  "token": "{{ $env.BROWSERLESS_TOKEN }}",
  "url": "https://analytics.example.com/chart/{{ $input.chartId }}",
  "selector": "#chart-canvas",
  "options": { "type": "jpeg", "quality": 85 },
  "gotoOptions": { "waitUntil": "networkidle0", "timeout": 25000 },
  "waitForSelector": { "selector": "#chart-canvas", "timeout": 12000 }
}

Example 3 — Mobile viewport screenshot

{
  "operation": "screenshot",
  "baseUrl": "https://chrome.browserless.io",
  "token": "{{ $env.BROWSERLESS_TOKEN }}",
  "url": "https://www.example.com",
  "options": { "type": "png", "fullPage": false },
  "viewport": { "width": 390, "height": 844, "deviceScaleFactor": 3 },
  "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15",
  "gotoOptions": { "waitUntil": "networkidle2", "timeout": 20000 }
}