Browserless (2.54.1)

Download OpenAPI specification:Download

This is the API reference for Browserless Enterprise and Cloud deployments. You'll find endpoints for capturing screenshots and PDFs, scraping content, running custom browser functions, solving CAPTCHAs, bypassing bot detection with stealth browsing, managing authenticated browser profiles, and orchestrating crawls.

The API includes REST endpoints (JSON in, JSON or binary out), WebSocket connections for direct CDP/Playwright/Puppeteer access, and CDP extensions that expose Browserless-specific commands like liveURL, solveCaptcha, and saveProfile. For the open-source container API, see the GitHub repository.

Just Getting Started?

Check out the Quick Start guide to launch your first session, or explore the BrowserQL IDE for a GraphQL-based automation workflow.

Base URL

All API requests go to your deployment's base URL. For Browserless Cloud:

https://production-sfo.browserless.io

Self-hosted Enterprise deployments use the host and port where the container is running (default http://localhost:3000).

Authentication

Include your API token as a query parameter on every request:

https://production-sfo.browserless.io/chromium/content?token=YOUR_API_TOKEN

Tokens are managed from the Account dashboard. Self-hosted deployments set the token via the TOKEN environment variable. See connection details for all authentication options.

Changelog

For release notes and version history, see the Enterprise Changelog.

Software keys

Self-hosted Enterprise deployments use time-limited software keys for offline licensing. No external connections or callbacks are required. Keys are cryptographically secure and can't be reverse engineered. When a key expires, the container exits with a semantic error code.

To use a software key, set the KEY environment variable when running the container:

docker run -e KEY=your-generated-key browserless/enterprise

Screenshots & PDFs

Capture full-page or element screenshots and generate PDFs from web pages. The root /screenshot and /pdf routes work for most cases. Use browser-specific variants like /edge/screenshot when you need a particular engine.

/screenshot

Returns a screenshot binary from a url or html payload. "url" or "html" payload in your request. Many options exist including cookies, user-agents, setting timers and network mocks.

Note: This is the preferred endpoint. The /chromium/screenshot route is equivalent.

query Parameters

allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
	object or string Launch options for the browser, either as a JSON object or a JSON string. Includes options like `headless`, `args`, `defaultViewport`, etc.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier

Request Body schema: application/json

blockConsentModals	boolean Whether to automatically block cookie consent modals and popups.
	object
	Array of objects An array of script tags to add to the page before performing actions. Each object can contain either a `url`, or a `content` property.
	Array of objects An array of style tags to add to the page before performing actions. Each object can contain either a `url`, or a `content` property.
	object
bestAttempt	boolean When bestAttempt is set to true, browserless will attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more.
	Array of objects An array of cookies to set on the page before navigation. Each cookie object should contain at least `name` and `value` properties.
emulateMediaType	string Changes the CSS media type of the page. Accepts values like "screen" or "print".
	object
html	string HTML content to set as the page content instead of navigating to a URL.
rejectRequestPattern	Array of strings An array of patterns to match against request URLs for automatic rejection. Requests matching these patterns will be aborted.
rejectResourceTypes	Array of strings Items Enum: "cspviolationreport" "document" "eventsource" "fedcm" "fetch" "font" "image" "manifest" "media" "other" "ping" "prefetch" "preflight" "script" "signedexchange" "stylesheet" "texttrack" "websocket" "xhr" An array of resource types to reject during page load. Common types include "image", "stylesheet", "font", "script", etc.
	Array of objects An array of request interceptors that can modify or mock network requests. Each interceptor has a `pattern` to match URLs and a `response` to return.
	object An object containing additional HTTP headers to send with every request.
setJavaScriptEnabled	boolean Whether or not to allow JavaScript to run on the page.
url	string The URL to navigate to before performing actions.
	object The user agent string to use for the page.
	object
	object Options for waiting for a specific event to be fired on the page.
	object Options for waiting for a JavaScript function to execute.
	object Options for waiting for a specific CSS selector to appear on the page.
waitForTimeout	number The amount of time in milliseconds to wait before proceeding.
scrollPage	boolean Whether to scroll through the entire page before capturing content. Useful for triggering lazy-loaded content.
selector	string A CSS selector to target a specific element instead of the full page.

Responses

Request samples

Payload

Content type

application/json

{"blockConsentModals": true,
"options": {"optimizeForSpeed": true,
"type": "jpeg",
"quality": 0,
"fromSurface": true,
"fullPage": true,
"omitBackground": true,
"path": "string",
"clip": {"scale": 0,
"width": 0,
"height": 0,
"x": 0,
"y": 0
},
"encoding": "base64",
"captureBeyondViewport": true
},
"addScriptTag": [{"url": "string",
"path": "string",
"content": "string",
"type": "string",
"id": "string"
}
],
"addStyleTag": [{"url": "string",
"path": "string",
"content": "string"
}
],
"authenticate": {"username": "string",
"password": "string"
},
"bestAttempt": true,
"cookies": [{"name": "string",
"value": "string",
"url": "string",
"domain": "string",
"path": "string",
"secure": true,
"httpOnly": true,
"sameSite": "Default",
"expires": 0,
"priority": "High",
"sourceScheme": "NonSecure",
"partitionKey": {"sourceOrigin": "string",
"hasCrossSiteAncestor": true
}
}
],
"emulateMediaType": "string",
"gotoOptions": {"referer": "string",
"referrerPolicy": "string",
"timeout": 0,
"waitUntil": ["domcontentloaded"
],
"signal": {"aborted": true,
"onabort": { },
"reason": null
}
},
"html": "string",
"rejectRequestPattern": ["string"
],
"rejectResourceTypes": ["cspviolationreport"
],
"requestInterceptors": [{"pattern": "string",
"response": {"headers": { },
"status": 0,
"contentType": "string",
"body": "string"
}
}
],
"setExtraHTTPHeaders": {"property1": "string",
"property2": "string"
},
"setJavaScriptEnabled": true,
"url": "string",
"userAgent": {"userAgent": "string",
"userAgentMetadata": {"brands": [{"brand": "string",
"version": "string"
}
],
"fullVersionList": [{"brand": "string",
"version": "string"
}
],
"fullVersion": "string",
"platform": "string",
"platformVersion": "string",
"architecture": "string",
"model": "string",
"mobile": true,
"bitness": "string",
"wow64": true,
"formFactors": ["string"
]
},
"platform": "string"
},
"viewport": {"width": 0,
"height": 0,
"deviceScaleFactor": 0,
"isMobile": true,
"isLandscape": true,
"hasTouch": true
},
"waitForEvent": {"event": "string",
"timeout": 0
},
"waitForFunction": {"fn": "string",
"polling": "string",
"timeout": 0
},
"waitForSelector": {"hidden": true,
"selector": "string",
"timeout": 0,
"visible": true
},
"waitForTimeout": 0,
"scrollPage": true,
"selector": "string"
}

/pdf

Returns a PDF binary from a url or html payload. "url" or "html" payload in your request. Many options exist for injecting cookies, request interceptors, user-agents and waiting for selectors, timers and more.

Note: This is the preferred endpoint. The /chromium/pdf route is equivalent.

query Parameters

allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
	object or string Launch options for the browser, either as a JSON object or a JSON string. Includes options like `headless`, `args`, `defaultViewport`, etc.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier

Request Body schema: application/json

blockConsentModals	boolean Whether to automatically block cookie consent modals and popups.
	object PDF generation options based on Puppeteer's PDFOptions interface. Includes properties like `format`, `margin`, `printBackground`, `landscape`, etc.
	Array of objects An array of script tags to add to the page before performing actions. Each object can contain either a `url`, or a `content` property.
	Array of objects An array of style tags to add to the page before performing actions. Each object can contain either a `url`, or a `content` property.
	object
bestAttempt	boolean When bestAttempt is set to true, browserless will attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more.
	Array of objects An array of cookies to set on the page before navigation. Each cookie object should contain at least `name` and `value` properties.
emulateMediaType	string Changes the CSS media type of the page. Accepts values like "screen" or "print".
	object
html	string HTML content to set as the page content instead of navigating to a URL.
rejectRequestPattern	Array of strings An array of patterns to match against request URLs for automatic rejection. Requests matching these patterns will be aborted.
rejectResourceTypes	Array of strings Items Enum: "cspviolationreport" "document" "eventsource" "fedcm" "fetch" "font" "image" "manifest" "media" "other" "ping" "prefetch" "preflight" "script" "signedexchange" "stylesheet" "texttrack" "websocket" "xhr" An array of resource types to reject during page load. Common types include "image", "stylesheet", "font", "script", etc.
	Array of objects An array of request interceptors that can modify or mock network requests. Each interceptor has a `pattern` to match URLs and a `response` to return.
	object An object containing additional HTTP headers to send with every request.
setJavaScriptEnabled	boolean Whether or not to allow JavaScript to run on the page.
url	string The URL to navigate to before performing actions.
	object The user agent string to use for the page.
	object
	object Options for waiting for a specific event to be fired on the page.
	object Options for waiting for a JavaScript function to execute.
	object Options for waiting for a specific CSS selector to appear on the page.
waitForTimeout	number The amount of time in milliseconds to wait before proceeding.

Responses

Request samples

Payload

Content type

application/json

{"blockConsentModals": true,
"options": {"scale": 0,
"displayHeaderFooter": true,
"headerTemplate": "string",
"footerTemplate": "string",
"printBackground": true,
"landscape": true,
"pageRanges": "string",
"format": "A0",
"width": "string",
"height": "string",
"preferCSSPageSize": true,
"margin": {"top": "string",
"bottom": "string",
"left": "string",
"right": "string"
},
"path": "string",
"omitBackground": true,
"tagged": true,
"outline": true,
"timeout": 0,
"waitForFonts": true,
"fullPage": true
},
"addScriptTag": [{"url": "string",
"path": "string",
"content": "string",
"type": "string",
"id": "string"
}
],
"addStyleTag": [{"url": "string",
"path": "string",
"content": "string"
}
],
"authenticate": {"username": "string",
"password": "string"
},
"bestAttempt": true,
"cookies": [{"name": "string",
"value": "string",
"url": "string",
"domain": "string",
"path": "string",
"secure": true,
"httpOnly": true,
"sameSite": "Default",
"expires": 0,
"priority": "High",
"sourceScheme": "NonSecure",
"partitionKey": {"sourceOrigin": "string",
"hasCrossSiteAncestor": true
}
}
],
"emulateMediaType": "string",
"gotoOptions": {"referer": "string",
"referrerPolicy": "string",
"timeout": 0,
"waitUntil": ["domcontentloaded"
],
"signal": {"aborted": true,
"onabort": { },
"reason": null
}
},
"html": "string",
"rejectRequestPattern": ["string"
],
"rejectResourceTypes": ["cspviolationreport"
],
"requestInterceptors": [{"pattern": "string",
"response": {"headers": { },
"status": 0,
"contentType": "string",
"body": "string"
}
}
],
"setExtraHTTPHeaders": {"property1": "string",
"property2": "string"
},
"setJavaScriptEnabled": true,
"url": "string",
"userAgent": {"userAgent": "string",
"userAgentMetadata": {"brands": [{"brand": "string",
"version": "string"
}
],
"fullVersionList": [{"brand": "string",
"version": "string"
}
],
"fullVersion": "string",
"platform": "string",
"platformVersion": "string",
"architecture": "string",
"model": "string",
"mobile": true,
"bitness": "string",
"wow64": true,
"formFactors": ["string"
]
},
"platform": "string"
},
"viewport": {"width": 0,
"height": 0,
"deviceScaleFactor": 0,
"isMobile": true,
"isLandscape": true,
"hasTouch": true
},
"waitForEvent": {"event": "string",
"timeout": 0
},
"waitForFunction": {"fn": "string",
"polling": "string",
"timeout": 0
},
"waitForSelector": {"hidden": true,
"selector": "string",
"timeout": 0,
"visible": true
},
"waitForTimeout": 0
}

/edge/screenshot

Returns a screenshot binary from a url or html payload using Edge. "url" or "html" payload in your request. Many options exist including cookies, user-agents, setting timers and network mocks.

query Parameters

blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object or string Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier
allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true

Request Body schema: application/json

	Array of objects
	Array of objects
	object or null Credentials for HTTP authentication. Contains `username` and `password` properties.
bestAttempt	boolean When bestAttempt is set to true, browserless attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more.
	Array of objects
emulateMediaType	string
	object
html	string
	object
rejectRequestPattern	Array of strings
rejectResourceTypes	Array of strings Items Enum: "cspviolationreport" "document" "eventsource" "fedcm" "fetch" "font" "image" "manifest" "media" "other" "ping" "prefetch" "preflight" "script" "signedexchange" "stylesheet" "texttrack" "websocket" "xhr"
	Array of objects
scrollPage	boolean
selector	string
	object
setJavaScriptEnabled	boolean
url	string
	object
	object or null The viewport dimensions and settings for the page. Includes properties like `width`, `height`, `deviceScaleFactor`, etc.
	object
	object
	object
waitForTimeout	number

Responses

Request samples

Payload

Content type

application/json

{"addScriptTag": [{"url": "string",
"path": "string",
"content": "string",
"type": "string",
"id": "string"
}
],
"addStyleTag": [{"url": "string",
"path": "string",
"content": "string"
}
],
"authenticate": {"username": "string",
"password": "string"
},
"bestAttempt": true,
"cookies": [{"name": "string",
"value": "string",
"url": "string",
"domain": "string",
"path": "string",
"secure": true,
"httpOnly": true,
"sameSite": "Default",
"expires": 0,
"priority": "High",
"sourceScheme": "NonSecure",
"partitionKey": {"sourceOrigin": "string",
"hasCrossSiteAncestor": true
}
}
],
"emulateMediaType": "string",
"gotoOptions": {"referer": "string",
"referrerPolicy": "string",
"timeout": 0,
"waitUntil": ["domcontentloaded"
],
"signal": {"aborted": true,
"onabort": { },
"reason": null
}
},
"html": "string",
"options": {"optimizeForSpeed": true,
"type": "jpeg",
"quality": 0,
"fromSurface": true,
"fullPage": true,
"omitBackground": true,
"path": "string",
"clip": {"scale": 0,
"width": 0,
"height": 0,
"x": 0,
"y": 0
},
"encoding": "base64",
"captureBeyondViewport": true
},
"rejectRequestPattern": ["string"
],
"rejectResourceTypes": ["cspviolationreport"
],
"requestInterceptors": [{"pattern": "string",
"response": {"headers": { },
"status": 0,
"contentType": "string",
"body": "string"
}
}
],
"scrollPage": true,
"selector": "string",
"setExtraHTTPHeaders": {"property1": "string",
"property2": "string"
},
"setJavaScriptEnabled": true,
"url": "string",
"userAgent": {"userAgent": "string",
"userAgentMetadata": {"brands": [{"brand": "string",
"version": "string"
}
],
"fullVersionList": [{"brand": "string",
"version": "string"
}
],
"fullVersion": "string",
"platform": "string",
"platformVersion": "string",
"architecture": "string",
"model": "string",
"mobile": true,
"bitness": "string",
"wow64": true,
"formFactors": ["string"
]
},
"platform": "string"
},
"viewport": {"width": 0,
"height": 0,
"deviceScaleFactor": 0,
"isMobile": true,
"isLandscape": true,
"hasTouch": true
},
"waitForEvent": {"event": "string",
"timeout": 0
},
"waitForFunction": {"fn": "string",
"polling": "string",
"timeout": 0
},
"waitForSelector": {"hidden": true,
"selector": "string",
"timeout": 0,
"visible": true
},
"waitForTimeout": 0
}

/edge/pdf

Returns a PDF binary from a url or html payload using Edge. "url" or "html" payload in your request. Many options exist for injecting cookies, request interceptors, user-agents and waiting for selectors, timers and more.

query Parameters

blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object or string Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier
allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true

Request Body schema: application/json

	Array of objects
	Array of objects
	object or null Credentials for HTTP authentication. Contains `username` and `password` properties.
bestAttempt	boolean When bestAttempt is set to true, browserless attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more.
	Array of objects
emulateMediaType	string
	object
html	string
	object PDF generation options based on Puppeteer's PDFOptions interface. Includes properties like `format`, `landscape`, `margin`, `scale`, etc.
rejectRequestPattern	Array of strings
rejectResourceTypes	Array of strings Items Enum: "cspviolationreport" "document" "eventsource" "fedcm" "fetch" "font" "image" "manifest" "media" "other" "ping" "prefetch" "preflight" "script" "signedexchange" "stylesheet" "texttrack" "websocket" "xhr"
	Array of objects
	object
setJavaScriptEnabled	boolean
url	string
	object
	object or null The viewport dimensions and settings for the page. Includes properties like `width`, `height`, `deviceScaleFactor`, etc.
	object
	object
	object
waitForTimeout	number

Responses

Request samples

Payload

Content type

application/json

{"addScriptTag": [{"url": "string",
"path": "string",
"content": "string",
"type": "string",
"id": "string"
}
],
"addStyleTag": [{"url": "string",
"path": "string",
"content": "string"
}
],
"authenticate": {"username": "string",
"password": "string"
},
"bestAttempt": true,
"cookies": [{"name": "string",
"value": "string",
"url": "string",
"domain": "string",
"path": "string",
"secure": true,
"httpOnly": true,
"sameSite": "Default",
"expires": 0,
"priority": "High",
"sourceScheme": "NonSecure",
"partitionKey": {"sourceOrigin": "string",
"hasCrossSiteAncestor": true
}
}
],
"emulateMediaType": "string",
"gotoOptions": {"referer": "string",
"referrerPolicy": "string",
"timeout": 0,
"waitUntil": ["domcontentloaded"
],
"signal": {"aborted": true,
"onabort": { },
"reason": null
}
},
"html": "string",
"options": {"scale": 0,
"displayHeaderFooter": true,
"headerTemplate": "string",
"footerTemplate": "string",
"printBackground": true,
"landscape": true,
"pageRanges": "string",
"format": "A0",
"width": "string",
"height": "string",
"preferCSSPageSize": true,
"margin": {"top": "string",
"bottom": "string",
"left": "string",
"right": "string"
},
"path": "string",
"omitBackground": true,
"tagged": true,
"outline": true,
"timeout": 0,
"waitForFonts": true,
"fullPage": true
},
"rejectRequestPattern": ["string"
],
"rejectResourceTypes": ["cspviolationreport"
],
"requestInterceptors": [{"pattern": "string",
"response": {"headers": { },
"status": 0,
"contentType": "string",
"body": "string"
}
}
],
"setExtraHTTPHeaders": {"property1": "string",
"property2": "string"
},
"setJavaScriptEnabled": true,
"url": "string",
"userAgent": {"userAgent": "string",
"userAgentMetadata": {"brands": [{"brand": "string",
"version": "string"
}
],
"fullVersionList": [{"brand": "string",
"version": "string"
}
],
"fullVersion": "string",
"platform": "string",
"platformVersion": "string",
"architecture": "string",
"model": "string",
"mobile": true,
"bitness": "string",
"wow64": true,
"formFactors": ["string"
]
},
"platform": "string"
},
"viewport": {"width": 0,
"height": 0,
"deviceScaleFactor": 0,
"isMobile": true,
"isLandscape": true,
"hasTouch": true
},
"waitForEvent": {"event": "string",
"timeout": 0
},
"waitForFunction": {"fn": "string",
"polling": "string",
"timeout": 0
},
"waitForSelector": {"hidden": true,
"selector": "string",
"timeout": 0,
"visible": true
},
"waitForTimeout": 0
}

Scraping & Content

Load pages and extract HTML, text, or structured data. /chromium/content returns raw HTML. /chromium/scrape runs querySelectorAll against the rendered DOM and returns matched elements. /smart-scrape cascades through multiple extraction strategies automatically.

/chromium/content

Given a url or html field, loads the page and returns the fully rendered HTML.

Note: Also available at /content as a convenience alias.

query Parameters

blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object or string
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier
allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true

Request Body schema: application/json

	Array of objects
	Array of objects
	object or null Credentials for HTTP authentication. Contains `username` and `password` properties.
bestAttempt	boolean When bestAttempt is set to true, browserless attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more.
	Array of objects
emulateMediaType	string
	object
html	string
rejectRequestPattern	Array of strings
rejectResourceTypes	Array of strings Items Enum: "cspviolationreport" "document" "eventsource" "fedcm" "fetch" "font" "image" "manifest" "media" "other" "ping" "prefetch" "preflight" "script" "signedexchange" "stylesheet" "texttrack" "websocket" "xhr"
	Array of objects
	object
setJavaScriptEnabled	boolean Whether or not to allow JavaScript to run on the page.
url	string
	object
	object or null The viewport dimensions and settings for the page. Includes properties like `width`, `height`, `deviceScaleFactor`, etc.
	object
	object
	object
waitForTimeout	number

Responses

Request samples

Payload

Content type

application/json

{"addScriptTag": [{"url": "string",
"path": "string",
"content": "string",
"type": "string",
"id": "string"
}
],
"addStyleTag": [{"url": "string",
"path": "string",
"content": "string"
}
],
"authenticate": {"username": "string",
"password": "string"
},
"bestAttempt": true,
"cookies": [{"name": "string",
"value": "string",
"url": "string",
"domain": "string",
"path": "string",
"secure": true,
"httpOnly": true,
"sameSite": "Default",
"expires": 0,
"priority": "High",
"sourceScheme": "NonSecure",
"partitionKey": {"sourceOrigin": "string",
"hasCrossSiteAncestor": true
}
}
],
"emulateMediaType": "string",
"gotoOptions": {"referer": "string",
"referrerPolicy": "string",
"timeout": 0,
"waitUntil": ["domcontentloaded"
],
"signal": {"aborted": true,
"onabort": { },
"reason": null
}
},
"html": "string",
"rejectRequestPattern": ["string"
],
"rejectResourceTypes": ["cspviolationreport"
],
"requestInterceptors": [{"pattern": "string",
"response": {"headers": { },
"status": 0,
"contentType": "string",
"body": "string"
}
}
],
"setExtraHTTPHeaders": {"property1": "string",
"property2": "string"
},
"setJavaScriptEnabled": true,
"url": "string",
"userAgent": {"userAgent": "string",
"userAgentMetadata": {"brands": [{"brand": "string",
"version": "string"
}
],
"fullVersionList": [{"brand": "string",
"version": "string"
}
],
"fullVersion": "string",
"platform": "string",
"platformVersion": "string",
"architecture": "string",
"model": "string",
"mobile": true,
"bitness": "string",
"wow64": true,
"formFactors": ["string"
]
},
"platform": "string"
},
"viewport": {"width": 0,
"height": 0,
"deviceScaleFactor": 0,
"isMobile": true,
"isLandscape": true,
"hasTouch": true
},
"waitForEvent": {"event": "string",
"timeout": 0
},
"waitForFunction": {"fn": "string",
"polling": "string",
"timeout": 0
},
"waitForSelector": {"hidden": true,
"selector": "string",
"timeout": 0,
"visible": true
},
"waitForTimeout": 0
}

/chromium/scrape

Returns text, HTML, and metadata from a given list of CSS selectors against the rendered DOM. Debugging information is available by sending in the appropriate flags in the "debugOpts" property. Responds with an array of JSON objects.

Note: Also available at /scrape as a convenience alias.

query Parameters

blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object or string
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier
allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true

Request Body schema: application/json

	Array of objects
	Array of objects
	object or null Credentials for HTTP authentication. Contains `username` and `password` properties.
bestAttempt	boolean When bestAttempt is set to true, browserless attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more.
	Array of objects
	object
required	Array of objects
emulateMediaType	string
	object
html	string
rejectRequestPattern	Array of strings
rejectResourceTypes	Array of strings Items Enum: "cspviolationreport" "document" "eventsource" "fedcm" "fetch" "font" "image" "manifest" "media" "other" "ping" "prefetch" "preflight" "script" "signedexchange" "stylesheet" "texttrack" "websocket" "xhr"
	Array of objects
	object
setJavaScriptEnabled	boolean
url	string
	object
	object or null The viewport dimensions and settings for the page. Includes properties like `width`, `height`, `deviceScaleFactor`, etc.
	object
	object
	object
waitForTimeout	number

Responses

Request samples

Payload

Content type

application/json

{"addScriptTag": [{"url": "string",
"path": "string",
"content": "string",
"type": "string",
"id": "string"
}
],
"addStyleTag": [{"url": "string",
"path": "string",
"content": "string"
}
],
"authenticate": {"username": "string",
"password": "string"
},
"bestAttempt": true,
"cookies": [{"name": "string",
"value": "string",
"url": "string",
"domain": "string",
"path": "string",
"secure": true,
"httpOnly": true,
"sameSite": "Default",
"expires": 0,
"priority": "High",
"sourceScheme": "NonSecure",
"partitionKey": {"sourceOrigin": "string",
"hasCrossSiteAncestor": true
}
}
],
"debugOpts": {"console": true,
"cookies": true,
"html": true,
"network": true,
"screenshot": true
},
"elements": [{"selector": "string",
"timeout": 0
}
],
"emulateMediaType": "string",
"gotoOptions": {"referer": "string",
"referrerPolicy": "string",
"timeout": 0,
"waitUntil": ["domcontentloaded"
],
"signal": {"aborted": true,
"onabort": { },
"reason": null
}
},
"html": "string",
"rejectRequestPattern": ["string"
],
"rejectResourceTypes": ["cspviolationreport"
],
"requestInterceptors": [{"pattern": "string",
"response": {"headers": { },
"status": 0,
"contentType": "string",
"body": "string"
}
}
],
"setExtraHTTPHeaders": {"property1": "string",
"property2": "string"
},
"setJavaScriptEnabled": true,
"url": "string",
"userAgent": {"userAgent": "string",
"userAgentMetadata": {"brands": [{"brand": "string",
"version": "string"
}
],
"fullVersionList": [{"brand": "string",
"version": "string"
}
],
"fullVersion": "string",
"platform": "string",
"platformVersion": "string",
"architecture": "string",
"model": "string",
"mobile": true,
"bitness": "string",
"wow64": true,
"formFactors": ["string"
]
},
"platform": "string"
},
"viewport": {"width": 0,
"height": 0,
"deviceScaleFactor": 0,
"isMobile": true,
"isLandscape": true,
"hasTouch": true
},
"waitForEvent": {"event": "string",
"timeout": 0
},
"waitForFunction": {"fn": "string",
"polling": "string",
"timeout": 0
},
"waitForSelector": {"hidden": true,
"selector": "string",
"timeout": 0,
"visible": true
},
"waitForTimeout": 0
}

Response samples

200

Content type

application/json

{"data": [{"results": [{"attributes": [{"name": "string",
"value": "string"
}
],
"height": 0,
"html": "string",
"left": 0,
"text": "string",
"top": 0,
"width": 0
}
],
"selector": "string"
}
],
"debug": {"console": ["string"
],
"cookies": [{"path": "string",
"expires": 0,
"size": 0,
"secure": true,
"session": true,
"partitionKeyOpaque": true,
"name": "string",
"value": "string",
"domain": "string",
"httpOnly": true,
"sameSite": "Default",
"priority": "High",
"sourceScheme": "NonSecure",
"partitionKey": {"sourceOrigin": "string",
"hasCrossSiteAncestor": true
}
}
],
"html": null,
"network": {"inbound": [{"headers": null,
"status": 0,
"url": "string"
}
],
"outbound": [{"headers": null,
"method": "string",
"url": "string"
}
]
},
"screenshot": null
}
}

/smart-scrape

Intelligently scrapes a URL using cascading strategies (HTTP fetch, proxy, headless browser, etc).

query Parameters

profile	string Optional name of an authentication profile to hydrate into the browser before scraping. The profile's cookies, localStorage, and IndexedDB entries are loaded into the session before navigation. Forces the browser strategy.
timeout	number The timeout for the scrape operation in milliseconds
token	string The API token for authenticating the request. Can also be provided in the `Authorization` header as a Bearer token. If both are provided, the `Authorization` header takes precedence. If no token is provided, the route will attempt to authenticate the request using any legacy authentication methods (e.g. cookie-based sessions) before rejecting the request as unauthorized.
allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true

Request Body schema: application/json

url required	string The URL to scrape. Must be an http or https URL.
formats	Array of strings Default: ["html"] Items Enum: "html" "links" "markdown" "pdf" "screenshot" Output formats to include in the response. Accepts an array of format strings such as `["markdown", "screenshot"]`. When `screenshot` or `pdf` is included, a browser strategy is forced. Mirrors the Firecrawl "formats" convention. `markdown` – page content converted to markdown `html` – cleaned HTML (returned by default in `content`, this is a no-op convenience value) `screenshot` – full-page screenshot as base64-encoded PNG (forces browser strategy) `pdf` – PDF of the page as base64-encoded string (forces browser strategy) `links` – list of links extracted from the page
proxy	string Enum: "datacenter" "residential" The proxy network to route the scrape through. Defaults to `residential`. Use `datacenter` for the cheaper datacenter pool.

Responses

Request samples

Payload

Content type

application/json

{"url": "string",
"formats": ["html"
],
"proxy": "datacenter"
}

Response samples

200

Content type

application/json

{"ok": true,
"statusCode": 0,
"content": { },
"contentType": "string",
"headers": { },
"strategy": "string",
"attempted": ["string"
],
"message": "string",
"screenshot": "string",
"pdf": "string",
"markdown": "string",
"links": ["string"
]
}

/search

Search the web and optionally scrape result pages. Accepts a query, performs a web search via SearXNG, and optionally scrapes each result URL — returning structured, LLM-ready data (markdown, HTML, links, or screenshots).

query Parameters

timeout	number The timeout for the search operation in milliseconds.
token	string The API token for authenticating the request.
allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true

Request Body schema: application/json

query required	string The search query string.
limit	number Maximum number of results per source. Defaults to `10`. Capped by plan limits.
lang	string Language code for results (e.g., `"en"`, `"es"`, `"de"`). Defaults to `"en"`.
location	string City or region to narrow geo-targeting (e.g., `"San Francisco"`). Use with `country`.
country	string ISO 3166-1 alpha-2 country code for geo-targeted results (e.g., `"us"`, `"gb"`, `"de"`).
proxy	string Enum: "datacenter" "residential" Proxy network to route result scraping through: `"residential"` (default) or `"datacenter"`.
tbs	string Enum: "day" "month" "qdr:d" "qdr:m" "qdr:w" "qdr:y" "week" "year" Time-based filter. Accepts `"day"`, `"week"`, `"month"`, `"year"`, or raw Google TBS syntax (`"qdr:d"`, `"qdr:w"`, `"qdr:m"`, `"qdr:y"`).
categories	Array of strings Items Enum: "github" "pdf" "research" Content category filters. Restricts results to `"github"` repos, `"research"` papers, or `"pdf"` documents.
sources	Array of strings Items Enum: "images" "news" "web" Sources to search. Defaults to `["web"]`. Also supports `"news"` and `"images"`.
timeout	number Request timeout in milliseconds.
	object When provided, fetches and processes each result URL into structured content.

Responses

Request samples

Payload

Content type

application/json

{"query": "string",
"limit": 0,
"lang": "string",
"location": "string",
"country": "string",
"proxy": "datacenter",
"tbs": "day",
"categories": ["github"
],
"sources": ["images"
],
"timeout": 0,
"scrapeOptions": {"formats": ["html"
],
"stripNonContentTags": true,
"onlyMainContent": true,
"removeBase64Images": true,
"includeTags": ["string"
],
"excludeTags": ["string"
]
}
}

Response samples

200

Content type

application/json

{"success": true,
"data": {"web": [{"title": "string",
"url": "string",
"description": "string",
"position": 0,
"markdown": "string",
"html": "string",
"links": ["string"
],
"screenshot": "string",
"metadata": {"statusCode": 0,
"strategy": "string",
"error": "string"
}
}
],
"news": [{"date": "string",
"imageUrl": "string",
"title": "string",
"url": "string",
"description": "string",
"position": 0,
"markdown": "string",
"html": "string",
"links": ["string"
],
"screenshot": "string",
"metadata": {"statusCode": 0,
"strategy": "string",
"error": "string"
}
}
],
"images": [{"title": "string",
"imageUrl": "string",
"imageWidth": 0,
"imageHeight": 0,
"url": "string",
"position": 0
}
]
},
"totalResults": 0,
"error": "string"
}

/map

Primarily discovers URLs from the site's sitemap, supplemented with link extraction from the page via the smart-scrape strategy pipeline (HTTP-first, browser fallback for JS-rendered pages). Use the search parameter to order results by relevance.

query Parameters

timeout	number Request timeout in milliseconds
token	string API authentication token
allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true

Request Body schema: application/json

url required	string The base URL to start mapping from (required)
search	string Search query to order results by relevance
limit	number Maximum number of links to return (default: 5000, max: 5000)
timeout	number Request timeout in milliseconds
sitemap	string Enum: "include" "only" "skip" Controls sitemap behavior: "include" (default), "skip", "only"
includeSubdomains	boolean Whether to include URLs from subdomains (default: true)
ignoreQueryParameters	boolean Exclude URLs with query parameters (default: true)
	object Geo-targeting settings
proxy	string Enum: "datacenter" "residential" Proxy network to route through: `"residential"` (default) or `"datacenter"`.

Responses

Request samples

Payload

Content type

application/json

{"url": "string",
"search": "string",
"limit": 0,
"timeout": 0,
"sitemap": "include",
"includeSubdomains": true,
"ignoreQueryParameters": true,
"location": {"country": "string",
"languages": ["string"
]
},
"proxy": "datacenter"
}

Response samples

200

Content type

application/json

["string"
]

/edge/content

Given a url or html field, loads the page in Edge and returns the fully rendered HTML.

query Parameters

blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object or string
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier
allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true

Request Body schema: application/json

	Array of objects
	Array of objects
	object or null Credentials for HTTP authentication. Contains `username` and `password` properties.
bestAttempt	boolean When bestAttempt is set to true, browserless attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more.
	Array of objects
emulateMediaType	string
	object
html	string
rejectRequestPattern	Array of strings
rejectResourceTypes	Array of strings Items Enum: "cspviolationreport" "document" "eventsource" "fedcm" "fetch" "font" "image" "manifest" "media" "other" "ping" "prefetch" "preflight" "script" "signedexchange" "stylesheet" "texttrack" "websocket" "xhr"
	Array of objects
	object
setJavaScriptEnabled	boolean Whether or not to allow JavaScript to run on the page.
url	string
	object
	object or null The viewport dimensions and settings for the page. Includes properties like `width`, `height`, `deviceScaleFactor`, etc.
	object
	object
	object
waitForTimeout	number

Responses

Request samples

Payload

Content type

application/json

{"addScriptTag": [{"url": "string",
"path": "string",
"content": "string",
"type": "string",
"id": "string"
}
],
"addStyleTag": [{"url": "string",
"path": "string",
"content": "string"
}
],
"authenticate": {"username": "string",
"password": "string"
},
"bestAttempt": true,
"cookies": [{"name": "string",
"value": "string",
"url": "string",
"domain": "string",
"path": "string",
"secure": true,
"httpOnly": true,
"sameSite": "Default",
"expires": 0,
"priority": "High",
"sourceScheme": "NonSecure",
"partitionKey": {"sourceOrigin": "string",
"hasCrossSiteAncestor": true
}
}
],
"emulateMediaType": "string",
"gotoOptions": {"referer": "string",
"referrerPolicy": "string",
"timeout": 0,
"waitUntil": ["domcontentloaded"
],
"signal": {"aborted": true,
"onabort": { },
"reason": null
}
},
"html": "string",
"rejectRequestPattern": ["string"
],
"rejectResourceTypes": ["cspviolationreport"
],
"requestInterceptors": [{"pattern": "string",
"response": {"headers": { },
"status": 0,
"contentType": "string",
"body": "string"
}
}
],
"setExtraHTTPHeaders": {"property1": "string",
"property2": "string"
},
"setJavaScriptEnabled": true,
"url": "string",
"userAgent": {"userAgent": "string",
"userAgentMetadata": {"brands": [{"brand": "string",
"version": "string"
}
],
"fullVersionList": [{"brand": "string",
"version": "string"
}
],
"fullVersion": "string",
"platform": "string",
"platformVersion": "string",
"architecture": "string",
"model": "string",
"mobile": true,
"bitness": "string",
"wow64": true,
"formFactors": ["string"
]
},
"platform": "string"
},
"viewport": {"width": 0,
"height": 0,
"deviceScaleFactor": 0,
"isMobile": true,
"isLandscape": true,
"hasTouch": true
},
"waitForEvent": {"event": "string",
"timeout": 0
},
"waitForFunction": {"fn": "string",
"polling": "string",
"timeout": 0
},
"waitForSelector": {"hidden": true,
"selector": "string",
"timeout": 0,
"visible": true
},
"waitForTimeout": 0
}

/edge/scrape

Returns text, HTML, and metadata from a given list of CSS selectors against the rendered DOM (Edge). Debugging information is available by sending in the appropriate flags in the "debugOpts" property. Responds with an array of JSON objects.

query Parameters

blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object or string
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier
allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true

Request Body schema: application/json

	Array of objects
	Array of objects
	object or null Credentials for HTTP authentication. Contains `username` and `password` properties.
bestAttempt	boolean When bestAttempt is set to true, browserless attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more.
	Array of objects
	object
required	Array of objects
emulateMediaType	string
	object
html	string
rejectRequestPattern	Array of strings
rejectResourceTypes	Array of strings Items Enum: "cspviolationreport" "document" "eventsource" "fedcm" "fetch" "font" "image" "manifest" "media" "other" "ping" "prefetch" "preflight" "script" "signedexchange" "stylesheet" "texttrack" "websocket" "xhr"
	Array of objects
	object
setJavaScriptEnabled	boolean
url	string
	object
	object or null The viewport dimensions and settings for the page. Includes properties like `width`, `height`, `deviceScaleFactor`, etc.
	object
	object
	object
waitForTimeout	number

Responses

Request samples

Payload

Content type

application/json

{"addScriptTag": [{"url": "string",
"path": "string",
"content": "string",
"type": "string",
"id": "string"
}
],
"addStyleTag": [{"url": "string",
"path": "string",
"content": "string"
}
],
"authenticate": {"username": "string",
"password": "string"
},
"bestAttempt": true,
"cookies": [{"name": "string",
"value": "string",
"url": "string",
"domain": "string",
"path": "string",
"secure": true,
"httpOnly": true,
"sameSite": "Default",
"expires": 0,
"priority": "High",
"sourceScheme": "NonSecure",
"partitionKey": {"sourceOrigin": "string",
"hasCrossSiteAncestor": true
}
}
],
"debugOpts": {"console": true,
"cookies": true,
"html": true,
"network": true,
"screenshot": true
},
"elements": [{"selector": "string",
"timeout": 0
}
],
"emulateMediaType": "string",
"gotoOptions": {"referer": "string",
"referrerPolicy": "string",
"timeout": 0,
"waitUntil": ["domcontentloaded"
],
"signal": {"aborted": true,
"onabort": { },
"reason": null
}
},
"html": "string",
"rejectRequestPattern": ["string"
],
"rejectResourceTypes": ["cspviolationreport"
],
"requestInterceptors": [{"pattern": "string",
"response": {"headers": { },
"status": 0,
"contentType": "string",
"body": "string"
}
}
],
"setExtraHTTPHeaders": {"property1": "string",
"property2": "string"
},
"setJavaScriptEnabled": true,
"url": "string",
"userAgent": {"userAgent": "string",
"userAgentMetadata": {"brands": [{"brand": "string",
"version": "string"
}
],
"fullVersionList": [{"brand": "string",
"version": "string"
}
],
"fullVersion": "string",
"platform": "string",
"platformVersion": "string",
"architecture": "string",
"model": "string",
"mobile": true,
"bitness": "string",
"wow64": true,
"formFactors": ["string"
]
},
"platform": "string"
},
"viewport": {"width": 0,
"height": 0,
"deviceScaleFactor": 0,
"isMobile": true,
"isLandscape": true,
"hasTouch": true
},
"waitForEvent": {"event": "string",
"timeout": 0
},
"waitForFunction": {"fn": "string",
"polling": "string",
"timeout": 0
},
"waitForSelector": {"hidden": true,
"selector": "string",
"timeout": 0,
"visible": true
},
"waitForTimeout": 0
}

Response samples

200

Content type

application/json

{"data": [{"results": [{"attributes": [{"name": "string",
"value": "string"
}
],
"height": 0,
"html": "string",
"left": 0,
"text": "string",
"top": 0,
"width": 0
}
],
"selector": "string"
}
],
"debug": {"console": ["string"
],
"cookies": [{"path": "string",
"expires": 0,
"size": 0,
"secure": true,
"session": true,
"partitionKeyOpaque": true,
"name": "string",
"value": "string",
"domain": "string",
"httpOnly": true,
"sameSite": "Default",
"priority": "High",
"sourceScheme": "NonSecure",
"partitionKey": {"sourceOrigin": "string",
"hasCrossSiteAncestor": true
}
}
],
"html": null,
"network": {"inbound": [{"headers": null,
"status": 0,
"url": "string"
}
],
"outbound": [{"headers": null,
"method": "string",
"url": "string"
}
]
},
"screenshot": null
}
}

/chromium/performance

Run lighthouse performance audits with a supplied "url" in your JSON payload.

Note: Also available at /performance as a convenience alias.

query Parameters

blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object or string Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier
allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true

Request Body schema: application/json

budgets	Array of objects
config	object
url required	string

Responses

Request samples

Payload

Content type

application/json

{"budgets": [{ }
],
"config": { },
"url": "string"
}

Response samples

200

Content type

application/json

{ }

/edge/performance

Run lighthouse performance audits with a supplied "url" in your JSON payload.

query Parameters

blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object or string Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier
allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true

Request Body schema: application/json

budgets	Array of objects
config	object
url required	string

Responses

Request samples

Payload

Content type

application/json

{"budgets": [{ }
],
"config": { },
"url": "string"
}

Response samples

200

Content type

application/json

{ }

Functions & Downloads

Run custom JavaScript in a browser context and retrieve the resulting files. Use /function to execute a Puppeteer or Playwright script server-side, and /download to capture binary assets triggered by in-page actions.

/chromium/function

Executes a Puppeteer or Playwright script in the browser context and returns the result. Browserless sets up a blank page, injects your puppeteer code, and runs it. You can optionally load external libraries via the "import" module that are meant for browser usage. Values returned from the function are checked and an appropriate content-type and response is sent back to your HTTP call.

Note: Also available at /function as a convenience alias.

query Parameters

blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object or string Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier
allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true

Request Body schema:
application/json

code required	string
	object An object of variables to inject into your Puppeteer function scope. Each key becomes a variable name accessible inside the function body. Use this to pass dynamic values (URLs, selectors, credentials) without hardcoding them in the code string.

Responses

Request samples

Payload

Content type

application/json

{"code": "string",
"context": {"property1": [null
],
"property2": [null
]
}
}

/chromium/download

Runs a Puppeteer or Playwright script and returns any files the browser downloaded during execution. the execution of puppeteer code, which is ran inside context of the browser. Browserless sets up a blank page, a fresh download directory, injects your puppeteer code, and then executes it. You can load external libraries via the "import" syntax, and import ESM-style modules that are written for execution inside of the browser. Once your script is finished, any downloaded files from Chromium are returned back with the appropriate content-type header.

Note: Also available at /download as a convenience alias.

query Parameters

blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object or string Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier
allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true

Request Body schema:
application/json

code required	string
	object An object of variables to inject into your Puppeteer function scope. Each key becomes a variable name accessible inside the function body. Use this to pass dynamic values (URLs, selectors, credentials) without hardcoding them in the code string.

Responses

Request samples

Payload

Content type

application/json

{"code": "string",
"context": {"property1": [null
],
"property2": [null
]
}
}

/edge/function

Executes a Puppeteer or Playwright script in the Edge browser context and returns the result. Browserless sets up a blank page, injects your puppeteer code, and runs it. You can optionally load external libraries via the "import" module that are meant for browser usage. Values returned from the function are checked and an appropriate content-type and response is sent back to your HTTP call.

query Parameters

blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object or string Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier
allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true

Request Body schema:
application/json

code required	string
	object An object of variables to inject into your Puppeteer function scope. Each key becomes a variable name accessible inside the function body. Use this to pass dynamic values (URLs, selectors, credentials) without hardcoding them in the code string.

Responses

Request samples

Payload

Content type

application/json

{"code": "string",
"context": {"property1": [null
],
"property2": [null
]
}
}

/edge/download

Runs a Puppeteer or Playwright script in Edge and returns any files the browser downloaded during execution. the execution of puppeteer code, which is ran inside context of the browser. Browserless sets up a blank page, a fresh download directory, injects your puppeteer code, and then executes it. You can load external libraries via the "import" syntax, and import ESM-style modules that are written for execution inside of the browser. Once your script is finished, any downloaded files from Chromium are returned back with the appropriate content-type header.

query Parameters

blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object or string Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier
allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true

Request Body schema:
application/json

code required	string
	object An object of variables to inject into your Puppeteer function scope. Each key becomes a variable name accessible inside the function body. Use this to pass dynamic values (URLs, selectors, credentials) without hardcoding them in the code string.

Responses

Request samples

Payload

Content type

application/json

{"code": "string",
"context": {"property1": [null
],
"property2": [null
]
}
}

/chromium/export

Exports a webpage to a PDF or image format. This API is useful for generating reports, screenshots, or PDFs of web pages.

Note: Also available at /export as a convenience alias.

query Parameters

allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
	object or string Launch options for the browser, either as a JSON object or a JSON string. Includes options like `headless`, `args`, `defaultViewport`, etc.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier

Request Body schema: application/json

bestAttempt	boolean When bestAttempt is set to true, browserless will attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more.
url required	string The URL of the site you want to archive.
	object
	object Options for waiting for a specific event to be fired on the page.
	object Options for waiting for a JavaScript function to execute.
	object Options for waiting for a specific CSS selector to appear on the page.
waitForTimeout	number The amount of time in milliseconds to wait before proceeding.
	object An object containing additional HTTP headers to send with every request.
includeResources	boolean Whether to include all linked resources (images, CSS, JS) in a zip file. When true, the response will be a zip file containing the HTML and all resources. When false or not provided, the response will be the raw content (default behavior).

Responses

Request samples

Payload

Content type

application/json

{"bestAttempt": true,
"url": "string",
"gotoOptions": {"referer": "string",
"referrerPolicy": "string",
"timeout": 0,
"waitUntil": ["domcontentloaded"
],
"signal": {"aborted": true,
"onabort": { },
"reason": null
}
},
"waitForEvent": {"event": "string",
"timeout": 0
},
"waitForFunction": {"fn": "string",
"polling": "string",
"timeout": 0
},
"waitForSelector": {"hidden": true,
"selector": "string",
"timeout": 0,
"visible": true
},
"waitForTimeout": 0,
"headers": {"property1": "string",
"property2": "string"
},
"includeResources": true
}

Response samples

200

Content type

application/json

{"html": "string"
}

Sessions & Connections

Create persistent browser sessions, reconnect to running browsers, and query CDP metadata. /session spins up a session that outlives a single WebSocket connection. /reconnect/:id reattaches to it later.

/session

Creates a new browser session with the specified parameters. The session can be used for persistent browser connections with well-defined lifetimes and reconnection semantics. BrowserQL support is only available for stealth sessions.

Request Body schema: application/json

ttl required	number The time-to-live (TTL) for the session in milliseconds. Once reached, will be forcefully terminated and all files and processes will be cleaned up. Must be a non-negative number greater than 0.
processKeepAlive	number An optional time, in milliseconds, to keep the underlying browser process alive after a connection to the session closes. If a connection happens within the keep-alive window, the browser process will remain running and the session can be reconnected to. If a connection happens after the keep-alive window has expired, a new browser process will be launched for the session, with the prior session data. Defaults to 0 (no keep-alive).
stealth	boolean Whether or not to enable advanced stealth mode. Defaults to false.
blockAds	boolean Whether or not to enable ad-blocking. Defaults to false.
headless	boolean Whether the browser should be launched in headless mode. Ignored if `stealth` is true, defaults to "true".
args	Array of strings An array of command-line arguments to pass to the browser. Defaults to an empty array.
browser	string Enum: "chrome" "chromium" "stealth" The type of browser to use for the session. 'stealth' uses the Brave browser with advanced anti-detection. Defaults to 'chromium'.
url	string The underlying page URL you're attempting to automate. Some pages may required special handling in order to work correctly or unblock. This is not required, but can be useful or required for certain sites.
	object Proxy Parameters for the session if desired. If not specified, the session will use the default network settings.
replay	boolean Whether to enable session recording for replay. When true, the session will be recorded and can be replayed later.
extensions	Array of strings An array of extension IDs to load into the browser session. Extensions must be previously uploaded to the browserless extension storage. This allows sessions to start with extensions pre-loaded without specifying them in launch arguments at connection time.
profile	string Optional name of an authentication profile to use as initial browser state. The profile's cookies, localStorage, and IndexedDB entries are injected via CDP before your code runs. sessionStorage is intentionally not restored — it is tab-scoped and stale values break OAuth/CSRF flows. Changes during the session do not affect the source profile.
integrationId	string Optional 1Password integration id. When set, Browserless.loadSecret can resolve credentials from this integration during the session. Validated at session creation; a missing or expired integration rejects the request.
	object Maps caller aliases to 1Password op:// references, e.g. { "password": "op://Prod/GitHub/password" }. Reference strings are not secret; resolved values are never stored on the session.
allowedDomains	Array of strings Optionally narrows the integration's allowed-domain list for this session. Cannot widen it — the effective list is the intersection of the two.

Responses

Request samples

Payload

Content type

application/json

{"ttl": 0,
"processKeepAlive": 0,
"stealth": true,
"blockAds": true,
"headless": true,
"args": ["string"
],
"browser": "chrome",
"url": "string",
"proxy": {"type": "datacenter",
"sticky": true,
"country": "string",
"city": "string",
"state": "string",
"preset": "string"
},
"replay": true,
"extensions": ["string"
],
"profile": "string",
"integrationId": "string",
"credentials": {"property1": "string",
"property2": "string"
},
"allowedDomains": ["string"
]
}

Response samples

200

Content type

application/json

{"id": "string",
"connect": "string",
"ttl": 0,
"stop": "string",
"browserQL": "string",
"cloudEndpointId": "string"
}

/json/new

Returns a JSON payload that acts as a pass-through to the DevTools /json/new HTTP API in Chromium. Browserless mocks this payload so that remote clients can connect to the underlying "webSocketDebuggerUrl" which will cause Browserless to start the browser and proxy that request into a blank page.

Responses

Response samples

200

Content type

application/json

{"description": "string",
"devtoolsFrontendUrl": "string",
"id": "string",
"title": "string",
"type": "string",
"url": "string",
"webSocketDebuggerUrl": "string"
}

/json/version

Returns a JSON payload that acts as a pass-through to the DevTools /json/version protocol in Chrome and Chromium.

Responses

Response samples

200

Content type

application/json

{"description": "string",
"devtoolsFrontendUrl": "string",
"id": "string",
"title": "string",
"type": "string",
"url": "string",
"webSocketDebuggerUrl": "string"
}

/json/protocol

Returns Protocol JSON meta-data that Chrome and Chromium come with.

Responses

Response samples

200

Content type

application/json

{ }

/session/bql/*

Executes BrowserQL queries against an existing session. The session must be a stealth session to support BrowserQL.

BrowserQL is a GraphQL-based query language for browser automation that allows you to interact with web pages using a declarative syntax. Queries execute within the context of your existing session, maintaining browser state and session data across multiple operations.

query Parameters

blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object or string Launch options for the browser, either as a JSON object or a JSON string. Includes options like `headless`, `args`, `defaultViewport`, etc. Must be either JSON object, or a base64-encoded JSON object.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
replay	boolean
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier
allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true

Request Body schema: application/json

query required	string The GraphQL query string to execute against the browser session. Example queries: Get browser info: `query { version browser }` Navigate and get content: `mutation { goto(url: "https://example.com") { status } title { title } url { url } }` Fill form and submit: `mutation { goto(url: "https://example.com") { status } type(selector: "input[name='email']", text: "user@example.com") { time } click(selector: "button[type='submit']") { time } }` Extract data: `mutation { querySelector(selector: "h1") { innerHTML } querySelectorAll(selector: ".product") { innerHTML className } }`
	object Variables to pass to the GraphQL query. Useful for dynamic values. Example: `{ "url": "https://example.com", "selector": "h1", "text": "Hello World" }`
operationName	string The name of the operation to execute if the query contains multiple operations. Optional - only needed when query has multiple named operations.

Responses

Request samples

Payload

Content type

application/json

{"query": "string",
"variables": {"property1": null,
"property2": null
},
"operationName": "string"
}

Response samples

200

Content type

application/json

{"data": { },
"errors": [{"message": "string",
"locations": [{"line": 0,
"column": 0
}
],
"path": ["string"
]
}
]
}

/reconnect/*

Reconnect to an existing Chromium or Chrome session with a library like puppeteer or others that work over chrome-devtools-protocol.

query Parameters

blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
integrations	string
	object or object or string Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
replay	boolean
solveCaptchas	boolean
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier
allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true

Responses

/session/connect/*

Connect to an existing session with a library like puppeteer or playwright that work over chrome-devtools-protocol. See documentation for more details on how to start the session.

The browser type (Chrome/Chromium, stealth/regular) is determined from the session metadata when it was created initially.

query Parameters

	object or string
replay	boolean
timeout	number
token	string
allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true

Responses

/session/*

Deletes a session and its associated data. This will immediately terminate any active connections to the session if "force" is applied.

Query Parameters:

force (optional): If true, forces deletion even if the session has active connections

query Parameters

blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
force	boolean Whether to force the deletion of the session even if it has active connections. Defaults to false.
	object or object or string Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier

Responses

Browser Management

Inspect running sessions, terminate browsers, and retrieve server metadata. /active lists current sessions, /kill/:id terminates one, and /meta returns server configuration.

/active

Returns a simple "204" HTTP code, with no response, indicating that the service itself is up and running. Useful for liveliness probes or other external checks.

Responses

/kill/+([0-9a-zA-Z-_])

Kill running sessions based on BrowserId or TrackingId.

query Parameters

blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
browserId	string
	object or object or string Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier

Responses

Response samples

200

Content type

application/json

"string"

/meta

Returns a JSON payload of the current system versions, including the core API version.

Responses

Response samples

200

Content type

application/json

{"version": "string",
"chromium": null,
"webkit": null,
"firefox": null,
"playwright": ["string"
],
"puppeteer": ["string"
]
}

/browser/*

Terminates a browser instance by browserId. The browser must belong to the authenticated user.

Responses

Crawling

Launch, monitor, and cancel multi-page crawl jobs. POST /crawl starts a crawl, GET /crawl/:id polls for progress, and DELETE /crawl/:id cancels it.

/crawl

List all crawl jobs for the authenticated token. Returns an array of crawl summaries with status, progress counters, and timestamps. Supports cursor-based pagination via the nextCursor field.

query Parameters

cursor	string Cursor for fetching the next page of results.
limit	number Maximum number of crawls to return per page (1–100, default 20).
status	string Filter crawls by status: in-progress, completed, failed, or cancelled.
token	string The API token for authenticating the request.

Responses

Response samples

200

Content type

application/json

{"crawls": [{"id": "string",
"url": "string",
"status": "cancelled",
"total": 0,
"completed": 0,
"createdAt": "string",
"completedAt": "string"
}
],
"nextCursor": "string"
}

/crawl

Start an asynchronous crawl job that spiders a website and scrapes every discovered page. Returns a crawl ID and status URL for polling results via GET /crawl/{id}. Supports depth control, path filtering, sitemap strategies, and webhook notifications.

query Parameters

profile	string Optional name of an authentication profile to hydrate into the browser before each page is scraped. The profile's cookies, localStorage, and IndexedDB entries are loaded into the session before navigation. Forces the browser strategy for every page.
token	string The API token for authenticating the request.

Request Body schema: application/json

url required	string The URL to crawl. Must be a valid http or https URL.
limit	number >= 1 Default: 100 Maximum number of pages to crawl. Clamped to your plan's limit.
maxDepth	number >= 0 Default: 5 Maximum link-follow depth from the root URL.
maxRetries	number >= 0 Default: 1 Number of retry attempts per failed page.
allowExternalLinks	boolean Default: false Whether to follow links to external domains.
allowSubdomains	boolean Default: false Whether to follow links to subdomains of the root URL.
sitemap	string Default: "auto" Enum: "auto" "force" "skip" Sitemap handling strategy.
includePaths	Array of strings Default: [] Regex patterns for URL paths to include.
excludePaths	Array of strings Default: [] Regex patterns for URL paths to exclude.
delay	number >= 0 Default: 200 Delay between requests in milliseconds.
	object Options controlling how each page is scraped.
	object Webhook configuration for crawl event notifications.

Responses

Request samples

Payload

Content type

application/json

{"url": "string",
"limit": 100,
"maxDepth": 5,
"maxRetries": 1,
"allowExternalLinks": false,
"allowSubdomains": false,
"sitemap": "auto",
"includePaths": [ ],
"excludePaths": [ ],
"delay": 200,
"scrapeOptions": {"formats": ["markdown"
],
"onlyMainContent": true,
"includeTags": [ ],
"excludeTags": [ ],
"waitFor": 0,
"headers": {"property1": "string",
"property2": "string"
},
"timeout": 150000,
"proxy": "datacenter"
},
"webhook": {"url": "string",
"events": ["completed"
]
}
}

Response samples

200

Content type

application/json

{"success": true,
"id": "string",
"url": "string"
}

/crawl/*

Cancel a running crawl job by its ID. Any pages already completed remain available for retrieval. Returns a 409 if the crawl is already in a terminal state.

query Parameters

token

string

The API token for authenticating the request.

Responses

/crawl/*

Get the status of a crawl job and its paginated page results. Returns progress counters, per-page metadata with content URLs, and a next URL for offset-based pagination via the skip parameter.

query Parameters

skip	number The number of pages to skip for pagination.
token	string The API token for authenticating the request.

Responses

Response samples

200

Content type

application/json

{"status": "cancelled",
"total": 0,
"completed": 0,
"failed": 0,
"expiresAt": "string",
"next": "string",
"data": [{"status": "cancelled",
"contentUrl": "string",
"metadata": {"title": "string",
"description": "string",
"language": "string",
"scrapedAt": "string",
"sourceURL": "string",
"statusCode": 0,
"error": "string"
}
}
]
}

Unblock & Stealth

Bypass bot detection and anti-scraping measures. /unblock handles aggressive anti-bot challenges end-to-end. The BQL stealth variants (/chromium/bql, /chrome/bql) randomize browser fingerprints for longer-running automation.

/unblock

Unblocks the provided URL from being blocked due to bot detection. Returns a payload of Cookies, HTML, a base64 encoded screenshot, and a "browserWSEndpoint" to allow connecting to the browser when specified in the JSON Payload. Only supports CDP or Puppeteer like libraries when connecting to the "browserWSEndpoint".

Note: Also available at /chromium/unblock as a convenience alias.

query Parameters

allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
	object or string Launch options for the browser, either as a JSON object or a JSON string. Includes options like `headless`, `args`, `defaultViewport`, etc.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true
replay	boolean When true, records the unblock session for replay (rrweb) and uploads the captured replay on cleanup, reusing the same recording pipeline as BrowserQL. Like every other Browserless route, replay is a connection-level flag supplied via this `?replay=true` query parameter (the browser's recording config is resolved from the URL at launch). Defaults to false.
solveCaptchas	boolean When `browserWSEndpoint` is requested, persists captcha-solving on the kept-alive session so reconnections automatically solve captchas without having to re-add `?solveCaptchas=true` to the returned reconnect URL. Connection-level flag supplied via this `?solveCaptchas=true` query parameter, mirroring `replay`. Defaults to false.
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier

Request Body schema: application/json

bestAttempt	boolean When bestAttempt is set to true, browserless will attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more.
url required	string The URL of the site you want to unblock.
browserWSEndpoint	boolean Whether or not to keep the underlying browser alive and around for future reconnects. Defaults to false.
cookies	boolean Whether or not to to return cookies for the site, defaults to true.
content	boolean Whether or not to to return content for the site, defaults to true.
screenshot	boolean Whether or not to to return a full-page screenshot for the site, defaults to true.
ttl	number When the browserWSEndpoint is requested this tells browserless how long to keep this browser alive for re-connection until shutting it down completely. Maximum of 30000 for 30 seconds (30,000ms).
	object
	object Options for waiting for a specific event to be fired on the page.
	object Options for waiting for a JavaScript function to execute.
	object Options for waiting for a specific CSS selector to appear on the page.
waitForTimeout	number The amount of time in milliseconds to wait before proceeding.

Responses

Request samples

Payload

Content type

application/json

{"bestAttempt": true,
"url": "string",
"browserWSEndpoint": true,
"cookies": true,
"content": true,
"screenshot": true,
"ttl": 0,
"gotoOptions": {"referer": "string",
"referrerPolicy": "string",
"timeout": 0,
"waitUntil": ["domcontentloaded"
],
"signal": {"aborted": true,
"onabort": { },
"reason": null
}
},
"waitForEvent": {"event": "string",
"timeout": 0
},
"waitForFunction": {"fn": "string",
"polling": "string",
"timeout": 0
},
"waitForSelector": {"hidden": true,
"selector": "string",
"timeout": 0,
"visible": true
},
"waitForTimeout": 0
}

Response samples

200

Content type

application/json

{"cookies": [{"name": "string",
"value": "string",
"domain": "string",
"path": "string",
"expires": 0,
"httpOnly": true,
"secure": true,
"sameSite": "string",
"url": "string"
}
],
"content": "string",
"browserWSEndpoint": "string",
"ttl": 0,
"screenshot": "string"
}

/chrome/stealth

Launch and connect to Stealthy Chrome with a library like puppeteer or others that work over chrome-devtools-protocol for scraping in a more stealth-like fashion.

query Parameters

allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
integrations	string
	object or string Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true
record	boolean
replay	boolean
solveCaptchas	boolean
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier

Responses

/chromium/stealth

Launch and connect to Stealthy Chromium with a library like puppeteer or others that work over chrome-devtools-protocol for scraping in a more stealth-like fashion.

query Parameters

allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
integrations	string
	object or string Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true
record	boolean
replay	boolean
solveCaptchas	boolean
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier

Responses

/stealth

Launch and connect to Stealthy Chromium with a library like puppeteer or others that work over chrome-devtools-protocol for scraping in a more stealth-like fashion.

query Parameters

allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
integrations	string
	object or string Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true
record	boolean
replay	boolean
solveCaptchas	boolean
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier

Responses

Proxy

Discover available proxy locations and configure residential or datacenter routing for your sessions.

Residential proxies are only available on Enterprise and Cloud plans.

Add these parameters to your library or API calls:

?proxy=residential — residential proxy (6 units/MB).
?proxy=datacenter — datacenter proxy pool (2 units/MB). Cheaper but more easily detected.
?proxyCountry=us — two-digit ISO country code.
?proxySticky=true — keep the same IP for the entire session. Recommended for most cases.
?proxyPreset=px_gov01 — website-specific proxy configuration.

/proxy/cities

Returns a list of available cities for proxy connections.

This endpoint requires city proxying to be enabled on your plan.

Query Parameters:

country (optional): Filter cities by two-letter country code (e.g., 'US', 'GB', 'DE')

The response includes a list of available cities grouped by country code.

query Parameters

blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
country	string Optional two-letter country code to filter cities by country (e.g., 'US', 'GB', 'DE').
	object or object or string Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier

Responses

Response samples

200

Content type

application/json

{"countries": [{"code": "string",
"cities": ["string"
]
}
],
"totalCountries": 0,
"totalCities": 0,
"filters": {"country": "string"
}
}

Profiles

Create and manage persistent browser profiles that preserve cookies, localStorage, and IndexedDB across sessions. Capture a logged-in state once with Browserless.saveProfile, then rehydrate it on any future session with ?profile=<name>.

/profile

Launches a temporary browser session for creating an authenticated profile. Connect via the returned WebSocket URL, authenticate in the browser, then call Browserless.saveProfile via CDP to capture and persist the auth state. The profile is NOT saved automatically — you must explicitly call Browserless.saveProfile before disconnecting. The session expires after 10 minutes.

Request Body schema: application/json

name required	string A user-visible name for the profile. Must be unique per token.
stealth	boolean Whether or not to enable advanced stealth mode. Defaults to false.
browser	string Enum: "chrome" "chromium" "stealth" The type of browser to use. Defaults to 'stealth'.
args	Array of strings An array of command-line arguments to pass to the browser.
	object Proxy parameters for the profile creation session.
integrationId	string Optional 1Password integration id. When set, the profile-authoring session can fill credentials via Browserless.loadSecret.
	object Optional alias → op:// reference map for the integration above.
allowedDomains	Array of strings Optional per-session narrowing of the integration's allowed domains.

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"stealth": true,
"browser": "chrome",
"args": ["string"
],
"proxy": {"type": "datacenter",
"sticky": true,
"country": "string",
"city": "string",
"state": "string",
"preset": "string"
},
"integrationId": "string",
"credentials": {"property1": "string",
"property2": "string"
},
"allowedDomains": ["string"
]
}

Response samples

200

Content type

application/json

{"id": "string",
"name": "string",
"connect": "string",
"stop": "string"
}

/profiles

Lists authentication profiles owned by the requesting token. Paginated via "limit" (default 100, capped at 1000) and "offset" (default 0). Returns an empty array if the token has no profiles.

query Parameters

blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object or object or string Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.
limit	number Maximum number of profiles to return (1–1000). Defaults to 100.
offset	number Number of profiles to skip for pagination. Defaults to 0.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier

Responses

Response samples

200

Content type

application/json

[{"id": "string",
"name": "string",
"cookieCount": 0,
"originCount": 0,
"lastUsedAt": "string",
"createdAt": "string",
"updatedAt": "string"
}
]

/profile/*

Deletes an authentication profile and its captured state. The profile name is the URL-encoded path segment after "/profile/". Returns 404 if no profile with that name exists for this token.

Responses

Response samples

200

Content type

application/json

{"success": true,
"message": "string",
"name": "string"
}

/profile/*

Returns metadata for a specific authentication profile. The profile name is the URL-encoded path segment after "/profile/". Returns 404 if no profile with that name exists for this token.

Responses

Response samples

200

Content type

application/json

{"id": "string",
"name": "string",
"cookieCount": 0,
"originCount": 0,
"lastUsedAt": "string",
"createdAt": "string",
"updatedAt": "string"
}

/profile/*

Renames an authentication profile. The new name must be unique per token. The current name is the URL-encoded path segment after "/profile/". Returns 400 if the new name is already taken, 404 if the source profile is not found.

Request Body schema: application/json

name

required

string

The new name for the profile.

Responses

Request samples

Payload

Content type

application/json

{"name": "string"
}

Response samples

200

Content type

application/json

{"id": "string",
"name": "string",
"cookieCount": 0,
"originCount": 0,
"lastUsedAt": "string",
"createdAt": "string",
"updatedAt": "string"
}

/profile/refresh

Replaces the state of an existing authentication profile in place. The "name" must already exist for the requesting token. Counts of any dropped or truncated entries are surfaced under "diagnostics".

Request Body schema: application/json

name required	string Name of the existing profile to refresh. Must already exist for the requesting token.
state required	any Pre-captured authentication state. Same shape as `POST /profile/upload`.

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"state": null
}

Response samples

200

Content type

application/json

{"diagnostics": {"skippedMalformedCookies": 0,
"skippedPrivateCookies": 0,
"skippedMalformedOrigins": 0,
"skippedPrivateOrigins": 0,
"truncatedOrigins": 0,
"skippedMalformedIdbDatabases": 0,
"truncatedIdbDatabases": 0,
"skippedMalformedIdbStores": 0,
"truncatedIdbEntries": 0
},
"id": "string",
"name": "string",
"cookieCount": 0,
"originCount": 0,
"lastUsedAt": "string",
"createdAt": "string",
"updatedAt": "string"
}

/profile/upload

Creates a new authentication profile from a pre-captured "state" payload (cookies plus per-origin localStorage and IndexedDB). The "name" must be unique per token. Counts of any dropped or truncated entries are surfaced under "diagnostics".

Request Body schema: application/json

name required	string A user-visible name for the profile. Must be unique per token.
state required	any Pre-captured authentication state. An object with two arrays — `cookies` (browser cookies) and `origins` (per-origin localStorage and IndexedDB).

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"state": null
}

Response samples

200

Content type

application/json

{"diagnostics": {"skippedMalformedCookies": 0,
"skippedPrivateCookies": 0,
"skippedMalformedOrigins": 0,
"skippedPrivateOrigins": 0,
"truncatedOrigins": 0,
"skippedMalformedIdbDatabases": 0,
"truncatedIdbDatabases": 0,
"skippedMalformedIdbStores": 0,
"truncatedIdbEntries": 0
},
"id": "string",
"name": "string",
"cookieCount": 0,
"originCount": 0,
"lastUsedAt": "string",
"createdAt": "string",
"updatedAt": "string"
}

Integrations

Connect external services to browser sessions. Currently supports 1Password for injecting stored credentials into a session without exposing secrets in your code.

/integrations/onepassword

Registers a 1Password integration for the requesting token. The supplied service-account token is encrypted at rest and is never returned by this or any other endpoint. Returns the created integration without any token field.

Request Body schema: application/json

label required	string A user-visible label for the integration. Unique per token.
kind	string Enum: "connect" "service_account" Integration kind. Defaults to "service_account".
serviceAccountToken required	string The 1Password service-account token (or Connect access token when kind is "connect"). Encrypted at rest; never returned by any API.
allowedDomains	Array of strings Origins this integration may fill credentials into. Empty means no fills pass.
connectUrl	string Connect server URL. Required when kind is "connect", rejected otherwise.

Responses

Request samples

Payload

Content type

application/json

{"label": "string",
"kind": "connect",
"serviceAccountToken": "string",
"allowedDomains": ["string"
],
"connectUrl": "string"
}

Response samples

200

Content type

application/json

{"id": "string",
"label": "string",
"kind": "connect",
"allowedDomains": ["string"
],
"connectUrl": "string",
"expiresAt": "string",
"lastResolvedAt": "string",
"createdAt": "string",
"updatedAt": "string"
}

/integrations/onepassword

Lists the 1Password integrations owned by the requesting token. Paginated via "limit" (default 100, capped at 1000) and "offset" (default 0). Records never include any token material.

query Parameters

blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object or object or string Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.
limit	number Maximum number of integrations to return (1–1000). Defaults to 100.
offset	number Number of integrations to skip for pagination. Defaults to 0.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier

Responses

Response samples

200

Content type

application/json

[{"id": "string",
"label": "string",
"kind": "connect",
"allowedDomains": ["string"
],
"connectUrl": "string",
"expiresAt": "string",
"lastResolvedAt": "string",
"createdAt": "string",
"updatedAt": "string"
}
]

/integrations/onepassword/*

Deletes a 1Password integration owned by the requesting token. The id is the URL-encoded path segment after "/integrations/onepassword/". Returns 404 if no integration with that id exists for this token. Deleting an integration does not touch any authentication profile.

Responses

Response samples

200

Content type

application/json

{"success": true,
"message": "string",
"id": "string"
}

/integrations/onepassword/*

Returns metadata for a specific 1Password integration owned by the token. The id is the URL-encoded path segment after "/integrations/onepassword/". Returns 404 if no integration with that id exists for this token. The response never includes any token material.

Responses

Response samples

200

Content type

application/json

{"id": "string",
"label": "string",
"kind": "connect",
"allowedDomains": ["string"
],
"connectUrl": "string",
"expiresAt": "string",
"lastResolvedAt": "string",
"createdAt": "string",
"updatedAt": "string"
}

/integrations/onepassword/*/audit

Lists recent credential-fill activity for a single 1Password integration owned by the token, newest first. One entry per Browserless.loadSecret attempt: outcome, error code, the credential reference, and non-secret target metadata. A resolved secret value is never recorded or returned. Paginated via "limit" (default 100, capped at 1000) and "offset" (default 0). Returns 404 if no integration with that id exists for this token.

query Parameters

blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object or object or string Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.
limit	number Maximum number of audit entries to return (1–1000). Defaults to 100.
offset	number Number of audit entries to skip for pagination. Defaults to 0.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier

Responses

Response samples

200

Content type

application/json

[{"id": "string",
"integrationId": "string",
"profileId": "string",
"secretRef": "string",
"targetOrigin": "string",
"targetSelector": "string",
"targetDescriptor": "string",
"outcome": "failure",
"errorCode": "string",
"createdAt": "string"
}
]

/integrations/onepassword/profile

Kicks off an autologin task: a managed agent creates a browser profile by logging into the integration's domains, then saves it. Returns a taskId to poll via GET /integrations/onepassword/profile/:taskId. (POC: the integration is resolved from an in-memory fixture rather than a real 1Password record.)

Request Body schema: application/json

name required	string Name to save the resulting profile under. Unique per token.
integrationId required	string Integration id — resolved from the in-memory fixture in this POC.
allowedDomains	Array of strings Optional subset of the integration's allowed domains.

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"integrationId": "string",
"allowedDomains": ["string"
]
}

Response samples

200

Content type

application/json

{"taskId": "string"
}

/integrations/onepassword/profile/*

Poll an autologin task by id. Returns its state, the current live rationale, and (on success) the saved profile id plus a per-domain breakdown. Scoped to the requesting token — returns 404 for unknown ids or another token's task.

Responses

Response samples

200

Content type

application/json

{"taskId": "string",
"state": "failed",
"currentRationale": "string",
"profileId": "string",
"profileName": "string",
"domains": [{"origin": "string",
"status": "active",
"error": "string"
}
],
"errorCode": "string",
"errorMessage": "string",
"createdAt": "string",
"updatedAt": "string"
}

/integrations/onepassword/autologin/form

Returns the selectable references for building an autologin profile: the 1Password integration's login origins and, per origin, the field labels it fills (never values). Drives the create-profile form.

query Parameters

blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
integrationId	string Which registered 1Password integration's login items to return.
	object or object or string Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier

Responses

Response samples

200

Content type

application/json

{"integrationId": "string",
"domains": [{"origin": "string",
"credentialTypes": ["string"
]
}
]
}

WebSocket APIs

Connect Puppeteer, Playwright, or raw DevTools Protocol clients over WebSocket. Launch a browser with wss:// and get back a CDP session for full programmatic control.

/

Launch and connect to Chromium with a library like puppeteer or others that work over chrome-devtools-protocol.

Note: Also available at /chromium as a convenience alias.

query Parameters

allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
integrations	string
	object or string Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true
record	boolean
replay	boolean
solveCaptchas	boolean
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier

Responses

/chromium

Launch and connect to Chromium with a library like puppeteer or others that work over chrome-devtools-protocol.

Note: This endpoint is also available at: / for backwards compatibility.

query Parameters

blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object or string Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier
allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true

Responses

/chromium/playwright

Connect to Chromium with any playwright style library.

Note: Also available at /playwright as a convenience alias.

query Parameters

blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object or string Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier
allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true

Responses

/edge

Launch and connect to Chromium with a library like puppeteer or others that work over chrome-devtools-protocol.

query Parameters

allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
integrations	string
	object or string Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true
record	boolean
replay	boolean
solveCaptchas	boolean
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier

Responses

/edge/playwright

Connect to Chromium with any playwright style library.

query Parameters

blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object or string Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier
allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true

Responses

/firefox/playwright

Connect to Firefox with any playwright-compliant library.

Note: Also available at /playwright/firefox as a convenience alias.

query Parameters

blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier
allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true

Responses

/webkit/playwright

Connect to Webkit with any playwright-compliant library.

Note: Also available at /playwright/webkit as a convenience alias.

query Parameters

blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object or string Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier
allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true

Responses

/live/*

This API is only available on paid plans. Sign-up here.

Websocket back-end that powers the live session experience.

Note: Also available at /chromium/live/* as a convenience alias.

Responses

/chrome/live/*

This API is only available on paid plans. Sign-up here.

Websocket back-end that powers the live session experience.

Responses

CDP Extensions

Browserless-specific Chrome DevTools Protocol methods you call via cdp.send() in Puppeteer or Playwright sessions. These extend the standard CDP with live URLs, captcha solving, session reconnect, profile management, and page identification.

Usage

const browser = await puppeteer.connect({ browserWSEndpoint: '...' });
const [page] = await browser.pages();
const cdp = await page.createCDPSession();

// Example: Get a live URL for debugging
const { liveURL } = await cdp.send('Browserless.liveURL', { quality: 75 });

Browserless.liveURL

Returns a URL that opens a live, interactive view of the current browser session in any browser. Use this for debugging, QA, or human-in-the-loop workflows. The returned URL is temporary and tied to the session's lifetime.

Call via CDP: cdp.send('Browserless.liveURL', { quality: 75 })

Returns: { liveURL: 'https://...' }

Parameter	Type	Description
`quality`	`number`	JPEG quality for the live stream (1-100). Default 75.
`format`	`string`	Image format for the live stream frames.

Browserless.closeLiveURL

Closes a previously opened liveURL, freeing server resources. Called automatically when the browser session ends.

Call via CDP: cdp.send('Browserless.closeLiveURL')

Browserless.solveCaptcha

Detects any CAPTCHA challenges on the current page and attempts to solve them using third-party solving services. Supports reCAPTCHA v2/v3, hCaptcha, Cloudflare Turnstile, and more.

Call via CDP: cdp.send('Browserless.solveCaptcha', { type: 'hcaptcha', wait: true })

Returns: { solved: true, token: '...' }

Parameter	Type	Description
`type`	`string`	CAPTCHA type to solve. Omit to auto-detect.
`wait`	`boolean`	Wait for the CAPTCHA to be fully solved before returning. Default true.

Browserless.foundCaptcha

Scans the current page for known CAPTCHA patterns and returns detection results without solving.

Call via CDP: cdp.send('Browserless.foundCaptcha')

Returns: { found: true, type: 'hcaptcha' }

Browserless.reconnect

Returns a WebSocket URL for reconnecting to the current browser session after disconnecting. The session stays alive on the server for the duration of its TTL.

Call via CDP: cdp.send('Browserless.reconnect', { timeout: 60000 })

Returns: { browserWSEndpoint: 'wss://...' }

Parameter	Type	Description
`timeout`	`number`	How long (ms) to keep the session alive after disconnect. Default 60000.

Browserless.saveProfile

Captures the browser's current state (cookies, localStorage, IndexedDB) and saves it as a named profile. Reuse the profile on future sessions via the ?profile=<name> query parameter.

Call via CDP: cdp.send('Browserless.saveProfile', { name: 'my-login' })

Returns: { profileId: '...', name: 'my-login' }

Parameter	Type	Description
`name`	`string`	Profile name for retrieval on future sessions.

Browserless.refreshProfile

Overwrites an existing profile's saved state with the current browser state. Useful for rotating session tokens without creating a new profile.

Call via CDP: cdp.send('Browserless.refreshProfile')

Browserless.pageIdentifier

Returns a stable identifier for the current browser tab, useful for routing and session management.

Call via CDP: cdp.send('Browserless.pageIdentifier')

Returns: { id: '...' }

Chrome (licensed build)

The /chrome/* endpoints use the licensed Google Chrome binary, which includes proprietary codec and DRM support. Use these when a site requires Chrome-specific features, video codecs (Twitch, YouTube, Netflix), or enhanced bot detection evasion. For most automation tasks, the /chromium/* equivalents work identically.

/chrome/screenshot

Returns a screenshot binary from a url or html payload (Chrome, legacy). "url" or "html" payload in your request. Many options exist including cookies, user-agents, setting timers and network mocks.

query Parameters

blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object or string Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier
allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true

Request Body schema: application/json

	Array of objects
	Array of objects
	object or null Credentials for HTTP authentication. Contains `username` and `password` properties.
bestAttempt	boolean When bestAttempt is set to true, browserless attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more.
	Array of objects
emulateMediaType	string
	object
html	string
	object
rejectRequestPattern	Array of strings
rejectResourceTypes	Array of strings Items Enum: "cspviolationreport" "document" "eventsource" "fedcm" "fetch" "font" "image" "manifest" "media" "other" "ping" "prefetch" "preflight" "script" "signedexchange" "stylesheet" "texttrack" "websocket" "xhr"
	Array of objects
scrollPage	boolean
selector	string
	object
setJavaScriptEnabled	boolean
url	string
	object
	object or null The viewport dimensions and settings for the page. Includes properties like `width`, `height`, `deviceScaleFactor`, etc.
	object
	object
	object
waitForTimeout	number

Responses

Request samples

Payload

Content type

application/json

{"addScriptTag": [{"url": "string",
"path": "string",
"content": "string",
"type": "string",
"id": "string"
}
],
"addStyleTag": [{"url": "string",
"path": "string",
"content": "string"
}
],
"authenticate": {"username": "string",
"password": "string"
},
"bestAttempt": true,
"cookies": [{"name": "string",
"value": "string",
"url": "string",
"domain": "string",
"path": "string",
"secure": true,
"httpOnly": true,
"sameSite": "Default",
"expires": 0,
"priority": "High",
"sourceScheme": "NonSecure",
"partitionKey": {"sourceOrigin": "string",
"hasCrossSiteAncestor": true
}
}
],
"emulateMediaType": "string",
"gotoOptions": {"referer": "string",
"referrerPolicy": "string",
"timeout": 0,
"waitUntil": ["domcontentloaded"
],
"signal": {"aborted": true,
"onabort": { },
"reason": null
}
},
"html": "string",
"options": {"optimizeForSpeed": true,
"type": "jpeg",
"quality": 0,
"fromSurface": true,
"fullPage": true,
"omitBackground": true,
"path": "string",
"clip": {"scale": 0,
"width": 0,
"height": 0,
"x": 0,
"y": 0
},
"encoding": "base64",
"captureBeyondViewport": true
},
"rejectRequestPattern": ["string"
],
"rejectResourceTypes": ["cspviolationreport"
],
"requestInterceptors": [{"pattern": "string",
"response": {"headers": { },
"status": 0,
"contentType": "string",
"body": "string"
}
}
],
"scrollPage": true,
"selector": "string",
"setExtraHTTPHeaders": {"property1": "string",
"property2": "string"
},
"setJavaScriptEnabled": true,
"url": "string",
"userAgent": {"userAgent": "string",
"userAgentMetadata": {"brands": [{"brand": "string",
"version": "string"
}
],
"fullVersionList": [{"brand": "string",
"version": "string"
}
],
"fullVersion": "string",
"platform": "string",
"platformVersion": "string",
"architecture": "string",
"model": "string",
"mobile": true,
"bitness": "string",
"wow64": true,
"formFactors": ["string"
]
},
"platform": "string"
},
"viewport": {"width": 0,
"height": 0,
"deviceScaleFactor": 0,
"isMobile": true,
"isLandscape": true,
"hasTouch": true
},
"waitForEvent": {"event": "string",
"timeout": 0
},
"waitForFunction": {"fn": "string",
"polling": "string",
"timeout": 0
},
"waitForSelector": {"hidden": true,
"selector": "string",
"timeout": 0,
"visible": true
},
"waitForTimeout": 0
}

/chrome/pdf

Returns a PDF binary from a url or html payload (Chrome, legacy). "url" or "html" payload in your request. Many options exist for injecting cookies, request interceptors, user-agents and waiting for selectors, timers and more.

query Parameters

blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object or string Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier
allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true

Request Body schema: application/json

	Array of objects
	Array of objects
	object or null Credentials for HTTP authentication. Contains `username` and `password` properties.
bestAttempt	boolean When bestAttempt is set to true, browserless attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more.
	Array of objects
emulateMediaType	string
	object
html	string
	object PDF generation options based on Puppeteer's PDFOptions interface. Includes properties like `format`, `landscape`, `margin`, `scale`, etc.
rejectRequestPattern	Array of strings
rejectResourceTypes	Array of strings Items Enum: "cspviolationreport" "document" "eventsource" "fedcm" "fetch" "font" "image" "manifest" "media" "other" "ping" "prefetch" "preflight" "script" "signedexchange" "stylesheet" "texttrack" "websocket" "xhr"
	Array of objects
	object
setJavaScriptEnabled	boolean
url	string
	object
	object or null The viewport dimensions and settings for the page. Includes properties like `width`, `height`, `deviceScaleFactor`, etc.
	object
	object
	object
waitForTimeout	number

Responses

Request samples

Payload

Content type

application/json

{"addScriptTag": [{"url": "string",
"path": "string",
"content": "string",
"type": "string",
"id": "string"
}
],
"addStyleTag": [{"url": "string",
"path": "string",
"content": "string"
}
],
"authenticate": {"username": "string",
"password": "string"
},
"bestAttempt": true,
"cookies": [{"name": "string",
"value": "string",
"url": "string",
"domain": "string",
"path": "string",
"secure": true,
"httpOnly": true,
"sameSite": "Default",
"expires": 0,
"priority": "High",
"sourceScheme": "NonSecure",
"partitionKey": {"sourceOrigin": "string",
"hasCrossSiteAncestor": true
}
}
],
"emulateMediaType": "string",
"gotoOptions": {"referer": "string",
"referrerPolicy": "string",
"timeout": 0,
"waitUntil": ["domcontentloaded"
],
"signal": {"aborted": true,
"onabort": { },
"reason": null
}
},
"html": "string",
"options": {"scale": 0,
"displayHeaderFooter": true,
"headerTemplate": "string",
"footerTemplate": "string",
"printBackground": true,
"landscape": true,
"pageRanges": "string",
"format": "A0",
"width": "string",
"height": "string",
"preferCSSPageSize": true,
"margin": {"top": "string",
"bottom": "string",
"left": "string",
"right": "string"
},
"path": "string",
"omitBackground": true,
"tagged": true,
"outline": true,
"timeout": 0,
"waitForFonts": true,
"fullPage": true
},
"rejectRequestPattern": ["string"
],
"rejectResourceTypes": ["cspviolationreport"
],
"requestInterceptors": [{"pattern": "string",
"response": {"headers": { },
"status": 0,
"contentType": "string",
"body": "string"
}
}
],
"setExtraHTTPHeaders": {"property1": "string",
"property2": "string"
},
"setJavaScriptEnabled": true,
"url": "string",
"userAgent": {"userAgent": "string",
"userAgentMetadata": {"brands": [{"brand": "string",
"version": "string"
}
],
"fullVersionList": [{"brand": "string",
"version": "string"
}
],
"fullVersion": "string",
"platform": "string",
"platformVersion": "string",
"architecture": "string",
"model": "string",
"mobile": true,
"bitness": "string",
"wow64": true,
"formFactors": ["string"
]
},
"platform": "string"
},
"viewport": {"width": 0,
"height": 0,
"deviceScaleFactor": 0,
"isMobile": true,
"isLandscape": true,
"hasTouch": true
},
"waitForEvent": {"event": "string",
"timeout": 0
},
"waitForFunction": {"fn": "string",
"polling": "string",
"timeout": 0
},
"waitForSelector": {"hidden": true,
"selector": "string",
"timeout": 0,
"visible": true
},
"waitForTimeout": 0
}

/chrome/content

Given a url or html field, loads the page in Chrome and returns the fully rendered HTML.

query Parameters

blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object or string
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier
allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true

Request Body schema: application/json

	Array of objects
	Array of objects
	object or null Credentials for HTTP authentication. Contains `username` and `password` properties.
bestAttempt	boolean When bestAttempt is set to true, browserless attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more.
	Array of objects
emulateMediaType	string
	object
html	string
rejectRequestPattern	Array of strings
rejectResourceTypes	Array of strings Items Enum: "cspviolationreport" "document" "eventsource" "fedcm" "fetch" "font" "image" "manifest" "media" "other" "ping" "prefetch" "preflight" "script" "signedexchange" "stylesheet" "texttrack" "websocket" "xhr"
	Array of objects
	object
setJavaScriptEnabled	boolean Whether or not to allow JavaScript to run on the page.
url	string
	object
	object or null The viewport dimensions and settings for the page. Includes properties like `width`, `height`, `deviceScaleFactor`, etc.
	object
	object
	object
waitForTimeout	number

Responses

Request samples

Payload

Content type

application/json

{"addScriptTag": [{"url": "string",
"path": "string",
"content": "string",
"type": "string",
"id": "string"
}
],
"addStyleTag": [{"url": "string",
"path": "string",
"content": "string"
}
],
"authenticate": {"username": "string",
"password": "string"
},
"bestAttempt": true,
"cookies": [{"name": "string",
"value": "string",
"url": "string",
"domain": "string",
"path": "string",
"secure": true,
"httpOnly": true,
"sameSite": "Default",
"expires": 0,
"priority": "High",
"sourceScheme": "NonSecure",
"partitionKey": {"sourceOrigin": "string",
"hasCrossSiteAncestor": true
}
}
],
"emulateMediaType": "string",
"gotoOptions": {"referer": "string",
"referrerPolicy": "string",
"timeout": 0,
"waitUntil": ["domcontentloaded"
],
"signal": {"aborted": true,
"onabort": { },
"reason": null
}
},
"html": "string",
"rejectRequestPattern": ["string"
],
"rejectResourceTypes": ["cspviolationreport"
],
"requestInterceptors": [{"pattern": "string",
"response": {"headers": { },
"status": 0,
"contentType": "string",
"body": "string"
}
}
],
"setExtraHTTPHeaders": {"property1": "string",
"property2": "string"
},
"setJavaScriptEnabled": true,
"url": "string",
"userAgent": {"userAgent": "string",
"userAgentMetadata": {"brands": [{"brand": "string",
"version": "string"
}
],
"fullVersionList": [{"brand": "string",
"version": "string"
}
],
"fullVersion": "string",
"platform": "string",
"platformVersion": "string",
"architecture": "string",
"model": "string",
"mobile": true,
"bitness": "string",
"wow64": true,
"formFactors": ["string"
]
},
"platform": "string"
},
"viewport": {"width": 0,
"height": 0,
"deviceScaleFactor": 0,
"isMobile": true,
"isLandscape": true,
"hasTouch": true
},
"waitForEvent": {"event": "string",
"timeout": 0
},
"waitForFunction": {"fn": "string",
"polling": "string",
"timeout": 0
},
"waitForSelector": {"hidden": true,
"selector": "string",
"timeout": 0,
"visible": true
},
"waitForTimeout": 0
}

/chrome/scrape

Returns text, HTML, and metadata from a given list of CSS selectors against the rendered DOM (Chrome, legacy). Debugging information is available by sending in the appropriate flags in the "debugOpts" property. Responds with an array of JSON objects.

query Parameters

blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object or string
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier
allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true

Request Body schema: application/json

	Array of objects
	Array of objects
	object or null Credentials for HTTP authentication. Contains `username` and `password` properties.
bestAttempt	boolean When bestAttempt is set to true, browserless attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more.
	Array of objects
	object
required	Array of objects
emulateMediaType	string
	object
html	string
rejectRequestPattern	Array of strings
rejectResourceTypes	Array of strings Items Enum: "cspviolationreport" "document" "eventsource" "fedcm" "fetch" "font" "image" "manifest" "media" "other" "ping" "prefetch" "preflight" "script" "signedexchange" "stylesheet" "texttrack" "websocket" "xhr"
	Array of objects
	object
setJavaScriptEnabled	boolean
url	string
	object
	object or null The viewport dimensions and settings for the page. Includes properties like `width`, `height`, `deviceScaleFactor`, etc.
	object
	object
	object
waitForTimeout	number

Responses

Request samples

Payload

Content type

application/json

{"addScriptTag": [{"url": "string",
"path": "string",
"content": "string",
"type": "string",
"id": "string"
}
],
"addStyleTag": [{"url": "string",
"path": "string",
"content": "string"
}
],
"authenticate": {"username": "string",
"password": "string"
},
"bestAttempt": true,
"cookies": [{"name": "string",
"value": "string",
"url": "string",
"domain": "string",
"path": "string",
"secure": true,
"httpOnly": true,
"sameSite": "Default",
"expires": 0,
"priority": "High",
"sourceScheme": "NonSecure",
"partitionKey": {"sourceOrigin": "string",
"hasCrossSiteAncestor": true
}
}
],
"debugOpts": {"console": true,
"cookies": true,
"html": true,
"network": true,
"screenshot": true
},
"elements": [{"selector": "string",
"timeout": 0
}
],
"emulateMediaType": "string",
"gotoOptions": {"referer": "string",
"referrerPolicy": "string",
"timeout": 0,
"waitUntil": ["domcontentloaded"
],
"signal": {"aborted": true,
"onabort": { },
"reason": null
}
},
"html": "string",
"rejectRequestPattern": ["string"
],
"rejectResourceTypes": ["cspviolationreport"
],
"requestInterceptors": [{"pattern": "string",
"response": {"headers": { },
"status": 0,
"contentType": "string",
"body": "string"
}
}
],
"setExtraHTTPHeaders": {"property1": "string",
"property2": "string"
},
"setJavaScriptEnabled": true,
"url": "string",
"userAgent": {"userAgent": "string",
"userAgentMetadata": {"brands": [{"brand": "string",
"version": "string"
}
],
"fullVersionList": [{"brand": "string",
"version": "string"
}
],
"fullVersion": "string",
"platform": "string",
"platformVersion": "string",
"architecture": "string",
"model": "string",
"mobile": true,
"bitness": "string",
"wow64": true,
"formFactors": ["string"
]
},
"platform": "string"
},
"viewport": {"width": 0,
"height": 0,
"deviceScaleFactor": 0,
"isMobile": true,
"isLandscape": true,
"hasTouch": true
},
"waitForEvent": {"event": "string",
"timeout": 0
},
"waitForFunction": {"fn": "string",
"polling": "string",
"timeout": 0
},
"waitForSelector": {"hidden": true,
"selector": "string",
"timeout": 0,
"visible": true
},
"waitForTimeout": 0
}

Response samples

200

Content type

application/json

{"data": [{"results": [{"attributes": [{"name": "string",
"value": "string"
}
],
"height": 0,
"html": "string",
"left": 0,
"text": "string",
"top": 0,
"width": 0
}
],
"selector": "string"
}
],
"debug": {"console": ["string"
],
"cookies": [{"path": "string",
"expires": 0,
"size": 0,
"secure": true,
"session": true,
"partitionKeyOpaque": true,
"name": "string",
"value": "string",
"domain": "string",
"httpOnly": true,
"sameSite": "Default",
"priority": "High",
"sourceScheme": "NonSecure",
"partitionKey": {"sourceOrigin": "string",
"hasCrossSiteAncestor": true
}
}
],
"html": null,
"network": {"inbound": [{"headers": null,
"status": 0,
"url": "string"
}
],
"outbound": [{"headers": null,
"method": "string",
"url": "string"
}
]
},
"screenshot": null
}
}

/chrome/performance

Run lighthouse performance audits with a supplied "url" in your JSON payload.

query Parameters

blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object or string Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier
allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true

Request Body schema: application/json

budgets	Array of objects
config	object
url required	string

Responses

Request samples

Payload

Content type

application/json

{"budgets": [{ }
],
"config": { },
"url": "string"
}

Response samples

200

Content type

application/json

{ }

/chrome/function

Executes a Puppeteer or Playwright script in the Chrome browser context and returns the result. Browserless sets up a blank page, injects your puppeteer code, and runs it. You can optionally load external libraries via the "import" module that are meant for browser usage. Values returned from the function are checked and an appropriate content-type and response is sent back to your HTTP call.

query Parameters

blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object or string Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier
allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true

Request Body schema:
application/json

code required	string
	object An object of variables to inject into your Puppeteer function scope. Each key becomes a variable name accessible inside the function body. Use this to pass dynamic values (URLs, selectors, credentials) without hardcoding them in the code string.

Responses

Request samples

Payload

Content type

application/json

{"code": "string",
"context": {"property1": [null
],
"property2": [null
]
}
}

/chrome/download

Runs a Puppeteer or Playwright script in Chrome and returns any files the browser downloaded during execution. the execution of puppeteer code, which is ran inside context of the browser. Browserless sets up a blank page, a fresh download directory, injects your puppeteer code, and then executes it. You can load external libraries via the "import" syntax, and import ESM-style modules that are written for execution inside of the browser. Once your script is finished, any downloaded files from Chromium are returned back with the appropriate content-type header.

query Parameters

blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object or string Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier
allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true

Request Body schema:
application/json

code required	string
	object An object of variables to inject into your Puppeteer function scope. Each key becomes a variable name accessible inside the function body. Use this to pass dynamic values (URLs, selectors, credentials) without hardcoding them in the code string.

Responses

Request samples

Payload

Content type

application/json

{"code": "string",
"context": {"property1": [null
],
"property2": [null
]
}
}

/chrome/export

Exports a webpage to a PDF or image format. This API is useful for generating reports, screenshots, or PDFs of web pages.

query Parameters

allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
	object or string Launch options for the browser, either as a JSON object or a JSON string. Includes options like `headless`, `args`, `defaultViewport`, etc.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier

Request Body schema: application/json

bestAttempt	boolean When bestAttempt is set to true, browserless will attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more.
url required	string The URL of the site you want to archive.
	object
	object Options for waiting for a specific event to be fired on the page.
	object Options for waiting for a JavaScript function to execute.
	object Options for waiting for a specific CSS selector to appear on the page.
waitForTimeout	number The amount of time in milliseconds to wait before proceeding.
	object An object containing additional HTTP headers to send with every request.
includeResources	boolean Whether to include all linked resources (images, CSS, JS) in a zip file. When true, the response will be a zip file containing the HTML and all resources. When false or not provided, the response will be the raw content (default behavior).

Responses

Request samples

Payload

Content type

application/json

{"bestAttempt": true,
"url": "string",
"gotoOptions": {"referer": "string",
"referrerPolicy": "string",
"timeout": 0,
"waitUntil": ["domcontentloaded"
],
"signal": {"aborted": true,
"onabort": { },
"reason": null
}
},
"waitForEvent": {"event": "string",
"timeout": 0
},
"waitForFunction": {"fn": "string",
"polling": "string",
"timeout": 0
},
"waitForSelector": {"hidden": true,
"selector": "string",
"timeout": 0,
"visible": true
},
"waitForTimeout": 0,
"headers": {"property1": "string",
"property2": "string"
},
"includeResources": true
}

Response samples

200

Content type

application/json

{"html": "string"
}

/chrome/unblock

Unblocks the provided URL from being blocked due to bot detection. Returns a payload of Cookies, HTML, a base64 encoded screenshot, and a "browserWSEndpoint" to allow connecting to the browser when specified in the JSON Payload. Only supports CDP or Puppeteer like libraries when connecting to the "browserWSEndpoint".

query Parameters

allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
	object or string Launch options for the browser, either as a JSON object or a JSON string. Includes options like `headless`, `args`, `defaultViewport`, etc.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true
replay	boolean When true, records the unblock session for replay (rrweb) and uploads the captured replay on cleanup, reusing the same recording pipeline as BrowserQL. Like every other Browserless route, replay is a connection-level flag supplied via this `?replay=true` query parameter (the browser's recording config is resolved from the URL at launch). Defaults to false.
solveCaptchas	boolean When `browserWSEndpoint` is requested, persists captcha-solving on the kept-alive session so reconnections automatically solve captchas without having to re-add `?solveCaptchas=true` to the returned reconnect URL. Connection-level flag supplied via this `?solveCaptchas=true` query parameter, mirroring `replay`. Defaults to false.
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier

Request Body schema: application/json

bestAttempt	boolean When bestAttempt is set to true, browserless will attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more.
url required	string The URL of the site you want to unblock.
browserWSEndpoint	boolean Whether or not to keep the underlying browser alive and around for future reconnects. Defaults to false.
cookies	boolean Whether or not to to return cookies for the site, defaults to true.
content	boolean Whether or not to to return content for the site, defaults to true.
screenshot	boolean Whether or not to to return a full-page screenshot for the site, defaults to true.
ttl	number When the browserWSEndpoint is requested this tells browserless how long to keep this browser alive for re-connection until shutting it down completely. Maximum of 30000 for 30 seconds (30,000ms).
	object
	object Options for waiting for a specific event to be fired on the page.
	object Options for waiting for a JavaScript function to execute.
	object Options for waiting for a specific CSS selector to appear on the page.
waitForTimeout	number The amount of time in milliseconds to wait before proceeding.

Responses

Request samples

Payload

Content type

application/json

{"bestAttempt": true,
"url": "string",
"browserWSEndpoint": true,
"cookies": true,
"content": true,
"screenshot": true,
"ttl": 0,
"gotoOptions": {"referer": "string",
"referrerPolicy": "string",
"timeout": 0,
"waitUntil": ["domcontentloaded"
],
"signal": {"aborted": true,
"onabort": { },
"reason": null
}
},
"waitForEvent": {"event": "string",
"timeout": 0
},
"waitForFunction": {"fn": "string",
"polling": "string",
"timeout": 0
},
"waitForSelector": {"hidden": true,
"selector": "string",
"timeout": 0,
"visible": true
},
"waitForTimeout": 0
}

Response samples

200

Content type

application/json

{"cookies": [{"name": "string",
"value": "string",
"domain": "string",
"path": "string",
"expires": 0,
"httpOnly": true,
"secure": true,
"sameSite": "string",
"url": "string"
}
],
"content": "string",
"browserWSEndpoint": "string",
"ttl": 0,
"screenshot": "string"
}

/chrome

Launch and connect to Chromium with a library like puppeteer or others that work over chrome-devtools-protocol.

query Parameters

allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
integrations	string
	object or string Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true
record	boolean
replay	boolean
solveCaptchas	boolean
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier

Responses

/chrome/playwright

Connect to Chromium with any playwright style library.

query Parameters

blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
	object or string Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier
allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true

Responses

/chrome/bql?(/*)

Parses and executes BrowserQL requests, powered by the BrowserQL Editor or by other API integrations. See the BrowserQL Editor for more documentation on this API.

query Parameters

acceptInsecureCerts	boolean Whether to ignore TLS certificate errors (e.g. self-signed or untrusted authorities) so the browser navigates to sites with invalid certificates.
allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
blockConsentModals	boolean Whether to automatically block cookie consent modals and popups.
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
humanlike	boolean Whether to enable human-like behavior for interactions. When true, actions like typing and clicking will have randomized delays.
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
	object or string Launch options for the browser, either as a JSON object or a JSON string. Includes options like `headless`, `args`, `defaultViewport`, etc. Must be either JSON object, or a base64-encoded JSON object.
os	string SCRAP-473: present a coherent Windows desktop identity (User-Agent, UA Client Hints and `navigator.platform`) instead of the host's native Linux one. Opt-in: some OS-sensitive risk engines (e.g. Auth0) flag a Linux desktop, but a Windows UA over Linux fonts can itself be flagged by font-fingerprinting detectors — so enable it only when the target rewards it. Value: "windows"
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true
replay	boolean Whether to enable session recording for replay. When true, the session will be recorded and can be replayed later.
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier

Request Body schema: application/json

query required	string The BrowserQL query string to execute.
operationName	string The name of the operation to execute if the query contains multiple operations.
	object Variables to pass to the BrowserQL query.

Responses

Request samples

Payload

Content type

application/json

{"query": "string",
"operationName": "string",
"variables": {"property1": null,
"property2": null
}
}

/chrome/bql?(/*)

WebSocket endpoint for BrowserQL. Connect to establish a persistent browser session, then send multiple GraphQL operations as JSON messages. The browser and page state persist across all messages for the connection duration.

Messages use the same JSON format as the HTTP POST endpoint: Send: { "query": "mutation { goto(url: "..") { status } }", "variables": {} } Receive: { "data": { "goto": { "status": 200 } } }

query Parameters

acceptInsecureCerts	boolean Whether to ignore TLS certificate errors (e.g. self-signed or untrusted authorities) so the browser navigates to sites with invalid certificates.
allowedDomains	Array of strings Optional per-connection narrowing of the integration's allowed-domain list. Extracted from the JSON `allowedDomains` query parameter. Can only narrow the integration's domains, never widen them.
blockAds	boolean Whether or not to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.
blockConsentModals	boolean
	object
externalProxyServer	string External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.
humanlike	boolean
integrationId	string Optional 1Password integration id for credential filling on a non-persistent connection. Extracted from the `integrationId` query parameter; the persistent session path carries the same data on session metadata instead.
	object or string Launch options for the browser, either as a JSON object or a JSON string. Includes options like `headless`, `args`, `defaultViewport`, etc. Must be either JSON object, or a base64-encoded JSON object.
os	string SCRAP-473: present a coherent Windows desktop identity (User-Agent, UA Client Hints and `navigator.platform`) instead of the host's native Linux one. Opt-in: some OS-sensitive risk engines (e.g. Auth0) flag a Linux desktop, but a Windows UA over Linux fonts can itself be flagged by font-fingerprinting detectors — so enable it only when the target rewards it. Value: "windows"
profile	string Name of an authenticated profile to hydrate into the browser at launch. The profile's cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.
proxy	string Enum: "datacenter" "residential" The proxy networks the platform can route through. `residential` uses the built-in residential vendors; `datacenter` uses the Geonode datacenter network (cheaper, billed at a lower per-MB rate).
proxyCity	string The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
proxyCountry	string A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type
proxyLocaleMatch	string Enum: "0" "1" "false" "true" Sets the browser's language to match the proxy's geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).
proxyPreset	string A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")
proxyState	string The state or province to use for the proxy, whitespace must be replaced with underscores
proxySticky	string Enum: "0" "1" "false" "true" Whether or not to use the same IP for all requests, defaults to true
replay	boolean
timeout	number Override the system-level timeout for this request. Accepts a value in milliseconds.
token	string The authorization token
trackingId	string Custom session identifier