customSiteTitle: Browserless Documentation definitions: FrameAddScriptTagOptions: type: object properties: url: description: URL of the script to be added. type: string path: description: Path to a JavaScript file to be injected into the frame. type: string content: description: JavaScript to be injected into the frame. type: string type: description: >- Sets the `type` of the script. Use `module` in order to load an ES2015 module. type: string id: description: Sets the `id` of the script. type: string additionalProperties: false FrameAddStyleTagOptions: type: object properties: url: description: the URL of the CSS file to be added. type: string path: description: The path to a CSS file to be injected into the frame. type: string content: description: Raw CSS content to be injected into the frame. type: string additionalProperties: false Credentials: type: object properties: username: type: string password: type: string additionalProperties: false required: - password - username CookieParam: description: |- Cookie parameter object used to set cookies in the page-level cookies API. type: object properties: name: description: Cookie name. type: string value: description: Cookie value. type: string url: description: >- The request-URI to associate with the setting of the cookie. This value can affect the default domain, path, and source scheme values of the created cookie. type: string domain: description: Cookie domain. type: string path: description: Cookie path. type: string secure: description: True if cookie is secure. type: boolean httpOnly: description: True if cookie is http-only. type: boolean sameSite: description: Cookie SameSite type. enum: - Default - Lax - None - Strict type: string expires: description: Cookie expiration date, session cookie if not set type: number priority: description: Cookie Priority. Supported only in Chrome. enum: - High - Low - Medium type: string sameParty: type: boolean sourceScheme: description: Cookie source scheme type. Supported only in Chrome. enum: - NonSecure - Secure - Unset type: string partitionKey: description: >- Cookie partition key. In Chrome, it matches the top-level site the partitioned cookie is available in. In Firefox, it matches the source origin in the {@link https://w3c.github.io/webdriver-bidi/#type-storage-PartitionKey PartitionKey}. anyOf: - $ref: '#/definitions/CookiePartitionKey' - type: string additionalProperties: false required: - name - value CookiePartitionKey: description: Represents a cookie partition key in Chrome. type: object properties: sourceOrigin: description: >- The site of the top-level URL the browser was visiting at the start of the request to the endpoint that set the cookie. In Chrome, maps to the CDP's `topLevelSite` partition key. type: string hasCrossSiteAncestor: description: |- Indicates if the cookie has any ancestors that are cross-site to the topLevelSite. Supported only in Chrome. type: boolean additionalProperties: false required: - sourceOrigin GoToOptions: type: object properties: referer: description: >- If provided, it will take preference over the referer header value set by {@link Page.setExtraHTTPHeaderspage.setExtraHTTPHeaders()}. type: string referrerPolicy: description: >- If provided, it will take preference over the referer-policy header value set by {@link Page.setExtraHTTPHeaderspage.setExtraHTTPHeaders()}. type: string timeout: description: >- Maximum wait time in milliseconds. Pass 0 to disable the timeout. The default value can be changed by using the {@link Page.setDefaultTimeout} or {@link Page.setDefaultNavigationTimeout} methods. type: number waitUntil: description: >- When to consider waiting succeeds. Given an array of event strings, waiting is considered to be successful after all events have been fired. anyOf: - type: array items: $ref: '#/definitions/PuppeteerLifeCycleEvent' - enum: - domcontentloaded - load - networkidle0 - networkidle2 type: string signal: description: A signal object that allows you to cancel the call. $ref: '#/definitions/AbortSignal' additionalProperties: false PuppeteerLifeCycleEvent: enum: - domcontentloaded - load - networkidle0 - networkidle2 type: string AbortSignal: type: object properties: aborted: type: boolean onabort: anyOf: - type: object additionalProperties: false - type: 'null' reason: {} additionalProperties: false required: - aborted - onabort - reason Record: type: object additionalProperties: false Protocol.Emulation.UserAgentMetadata: description: >- Used to specify User Agent Client Hints to emulate. See https://wicg.github.io/ua-client-hints Missing optional values will be filled in by the target with what it would normally use. type: object properties: brands: description: Brands appearing in Sec-CH-UA. type: array items: $ref: '#/definitions/Protocol.Emulation.UserAgentBrandVersion' fullVersionList: description: Brands appearing in Sec-CH-UA-Full-Version-List. type: array items: $ref: '#/definitions/Protocol.Emulation.UserAgentBrandVersion' fullVersion: type: string platform: type: string platformVersion: type: string architecture: type: string model: type: string mobile: type: boolean bitness: type: string wow64: type: boolean formFactors: description: |- Used to specify User Agent form-factor values. See https://wicg.github.io/ua-client-hints/#sec-ch-ua-form-factors type: array items: type: string additionalProperties: false required: - architecture - mobile - model - platform - platformVersion Protocol.Emulation.UserAgentBrandVersion: description: >- Used to specify User Agent Client Hints to emulate. See https://wicg.github.io/ua-client-hints type: object properties: brand: type: string version: type: string additionalProperties: false required: - brand - version Viewport: type: object properties: width: description: The page width in CSS pixels. type: number height: description: The page height in CSS pixels. type: number deviceScaleFactor: description: >- Specify device scale factor. See {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/devicePixelRatio devicePixelRatio} for more info. type: number isMobile: description: Whether the `meta viewport` tag is taken into account. type: boolean isLandscape: description: Specifies if the viewport is in landscape mode. type: boolean hasTouch: description: Specify if the viewport supports touch events. type: boolean additionalProperties: false required: - height - width CDPLaunchOptions: type: object properties: args: type: array items: type: string defaultViewport: type: object properties: deviceScaleFactor: type: number hasTouch: type: boolean height: type: number isLandscape: type: boolean isMobile: type: boolean width: type: number additionalProperties: false required: - height - width devtools: type: boolean dumpio: type: boolean headless: enum: - false - shell - true ignoreDefaultArgs: anyOf: - type: array items: type: string - type: boolean ignoreHTTPSErrors: type: boolean acceptInsecureCerts: type: boolean slowMo: type: number stealth: type: boolean timeout: type: number userDataDir: type: string waitForInitialPage: type: boolean additionalProperties: false BrowserServerOptions: type: object properties: args: type: array items: type: string chromiumSandbox: type: boolean devtools: type: boolean downloadsPath: type: string headless: type: boolean ignoreDefaultArgs: anyOf: - type: array items: type: string - type: boolean proxy: type: object properties: bypass: type: string password: type: string server: type: string username: type: string additionalProperties: false required: - server timeout: type: number tracesDir: type: string additionalProperties: false JSONSchema: type: object properties: code: type: string context: type: object additionalProperties: $ref: '#/definitions/ContextValue' additionalProperties: false required: - code ContextValue: anyOf: - type: array items: $ref: '#/definitions/ContextValue' - type: object additionalProperties: $ref: '#/definitions/ContextValue' - type: - 'null' - string - number - boolean PDFMargin: type: object properties: top: type: - string - number bottom: type: - string - number left: type: - string - number right: type: - string - number additionalProperties: false ScrapeDebugOptions: type: object properties: console: type: boolean cookies: type: boolean html: type: boolean network: type: boolean screenshot: type: boolean additionalProperties: false ScrapeElementSelector: type: object properties: selector: type: string timeout: type: number additionalProperties: false required: - selector Cookie: description: Represents a cookie object. type: object properties: path: description: Cookie path. type: string expires: description: >- Cookie expiration date as the number of seconds since the UNIX epoch. Set to `-1` for session cookies type: number size: description: Cookie size. type: number secure: description: True if cookie is secure. type: boolean session: description: True in case of session cookie. type: boolean partitionKeyOpaque: description: True if cookie partition key is opaque. Supported only in Chrome. type: boolean name: description: Cookie name. type: string value: description: Cookie value. type: string domain: description: Cookie domain. type: string httpOnly: description: True if cookie is http-only. type: boolean sameSite: description: Cookie SameSite type. enum: - Default - Lax - None - Strict type: string priority: description: Cookie Priority. Supported only in Chrome. enum: - High - Low - Medium type: string sameParty: type: boolean sourceScheme: description: Cookie source scheme type. Supported only in Chrome. enum: - NonSecure - Secure - Unset type: string partitionKey: description: >- Cookie partition key. In Chrome, it matches the top-level site the partitioned cookie is available in. In Firefox, it matches the source origin in the {@link https://w3c.github.io/webdriver-bidi/#type-storage-PartitionKey PartitionKey}. anyOf: - $ref: '#/definitions/CookiePartitionKey' - type: string additionalProperties: false required: - domain - expires - name - path - secure - session - size - value InBoundRequest: type: object properties: headers: {} status: type: number url: type: string additionalProperties: false required: - headers - status - url OutBoundRequest: type: object properties: headers: {} method: type: string url: type: string additionalProperties: false required: - headers - method - url ScreenshotOptions: type: object properties: optimizeForSpeed: type: boolean type: enum: - jpeg - png - webp type: string quality: description: Quality of the image, between 0-100. Not applicable to `png` images. type: number fromSurface: description: Capture the screenshot from the surface, rather than the view. type: boolean fullPage: description: When `true`, takes a screenshot of the full page. type: boolean omitBackground: description: >- Hides default white background and allows capturing screenshots with transparency. type: boolean path: description: >- The file path to save the image to. The screenshot type will be inferred from file extension. If path is a relative path, then it is resolved relative to current working directory. If no path is provided, the image won't be saved to the disk. type: string clip: description: Specifies the region of the page/element to clip. $ref: '#/definitions/ScreenshotClip' encoding: description: Encoding of the image. enum: - base64 - binary type: string captureBeyondViewport: description: Capture the screenshot beyond the viewport. type: boolean additionalProperties: false ScreenshotClip: type: object properties: scale: type: number width: description: the width of the element in pixels. type: number height: description: the height of the element in pixels. type: number x: type: number 'y': type: number additionalProperties: false required: - height - width - x - 'y' import("/home/runner/work/enterprise/enterprise/node_modules/@browserless.io/browserless/build/types",{with:{"resolution-mode":"import"}}).CDPLaunchOptions: type: object properties: args: type: array items: type: string defaultViewport: type: object properties: deviceScaleFactor: type: number hasTouch: type: boolean height: type: number isLandscape: type: boolean isMobile: type: boolean width: type: number additionalProperties: false required: - height - width devtools: type: boolean dumpio: type: boolean headless: enum: - false - shell - true ignoreDefaultArgs: anyOf: - type: array items: type: string - type: boolean ignoreHTTPSErrors: type: boolean acceptInsecureCerts: type: boolean slowMo: type: number stealth: type: boolean timeout: type: number userDataDir: type: string waitForInitialPage: type: boolean additionalProperties: false CookieSameSite: description: |- Represents the cookie's 'SameSite' status: https://tools.ietf.org/html/draft-west-first-party-cookies enum: - Default - Lax - None - Strict type: string CookiePriority: description: |- Represents the cookie's 'Priority' status: https://tools.ietf.org/html/draft-west-cookie-priority-00 enum: - High - Low - Medium type: string CookieSourceScheme: description: >- Represents the source scheme of the origin that originally set the cookie. A value of "Unset" allows protocol clients to emulate legacy cookie scope for the scheme. This is a temporary ability and it will be removed in the future. enum: - NonSecure - Secure - Unset type: string import("/home/runner/work/enterprise/enterprise/node_modules/@browserless.io/browserless/build/types",{with:{"resolution-mode":"import"}}).BrowserServerOptions: type: object properties: args: type: array items: type: string chromiumSandbox: type: boolean devtools: type: boolean downloadsPath: type: string headless: type: boolean ignoreDefaultArgs: anyOf: - type: array items: type: string - type: boolean proxy: type: object properties: bypass: type: string password: type: string server: type: string username: type: string additionalProperties: false required: - server timeout: type: number tracesDir: type: string additionalProperties: false PaperFormat: description: All the valid paper format types when printing a PDF. enum: - A0 - A1 - A2 - A3 - A4 - A5 - A6 - LEDGER - LEGAL - LETTER - Ledger - Legal - Letter - TABLOID - Tabloid - a0 - a1 - a2 - a3 - a4 - a5 - a6 - ledger - legal - letter - tabloid type: string ImageFormat: enum: - jpeg - png - webp type: string TimeBasedOptions: type: string enum: - day - week - month - year - day - week - month - year Record: type: object additionalProperties: false Record: type: object additionalProperties: false CrawlStatus: enum: - cancelled - completed - failed - in-progress type: string CrawlPageResponse: type: object properties: status: $ref: '#/definitions/PageStatus' contentUrl: type: string metadata: type: object properties: title: type: string description: type: string language: type: string scrapedAt: type: string sourceURL: type: string statusCode: type: number error: type: string additionalProperties: false required: - description - error - language - scrapedAt - sourceURL - statusCode - title additionalProperties: false required: - contentUrl - metadata - status PageStatus: enum: - cancelled - completed - failed - in-progress - queued type: string CrawlListItem: type: object properties: id: type: string url: type: string status: $ref: '#/definitions/CrawlStatus' total: type: number completed: type: number createdAt: type: string completedAt: type: string additionalProperties: false required: - completed - completedAt - createdAt - id - status - total - url RefreshResponseDiagnostics: description: |- Per-entry counts of cookies, origins, and IndexedDB items the server dropped or truncated before persisting. All zero on a clean refresh. type: object properties: skippedMalformedCookies: description: Cookies dropped because required fields were missing or wrong type. type: number skippedPrivateCookies: description: >- Cookies dropped because their domain pointed at a private/internal host. type: number skippedMalformedOrigins: description: Origins dropped because they were malformed or non-http(s). type: number skippedPrivateOrigins: description: Origins dropped because they targeted a private/internal network. type: number truncatedOrigins: description: Origins dropped because the per-profile cap was exceeded. type: number skippedMalformedIdbDatabases: description: IndexedDB databases dropped because required fields were missing. type: number truncatedIdbDatabases: description: IndexedDB databases dropped because the per-origin cap was exceeded. type: number skippedMalformedIdbStores: description: IndexedDB object-stores dropped because required fields were missing. type: number truncatedIdbEntries: description: IndexedDB entries dropped because the per-store cap was exceeded. type: number additionalProperties: false required: - skippedMalformedCookies - skippedMalformedIdbDatabases - skippedMalformedIdbStores - skippedMalformedOrigins - skippedPrivateCookies - skippedPrivateOrigins - truncatedIdbDatabases - truncatedIdbEntries - truncatedOrigins UploadResponseDiagnostics: description: |- Per-entry counts of cookies, origins, and IndexedDB items the server dropped or truncated before persisting. All zero on a clean upload. type: object properties: skippedMalformedCookies: description: Cookies dropped because required fields were missing or wrong type. type: number skippedPrivateCookies: description: >- Cookies dropped because their domain pointed at a private/internal host. type: number skippedMalformedOrigins: description: Origins dropped because they were malformed or non-http(s). type: number skippedPrivateOrigins: description: Origins dropped because they targeted a private/internal network. type: number truncatedOrigins: description: Origins dropped because the per-profile cap was exceeded. type: number skippedMalformedIdbDatabases: description: IndexedDB databases dropped because required fields were missing. type: number truncatedIdbDatabases: description: IndexedDB databases dropped because the per-origin cap was exceeded. type: number skippedMalformedIdbStores: description: IndexedDB object-stores dropped because required fields were missing. type: number truncatedIdbEntries: description: IndexedDB entries dropped because the per-store cap was exceeded. type: number additionalProperties: false required: - skippedMalformedCookies - skippedMalformedIdbDatabases - skippedMalformedIdbStores - skippedMalformedOrigins - skippedPrivateCookies - skippedPrivateOrigins - truncatedIdbDatabases - truncatedIdbEntries - truncatedOrigins info: title: Browserless version: 2.49.0 x-logo: altText: browserless logo url: ./docs/browserless-logo-inline.svg description: > # Browserless.io This service extends the Browserless open-source image with many features and enhancements for teams automating at scale. Notable features include: - A Chrome-devtools-protocol based API for extending and enhancing libraries in a cross-language way. - A new hybrid-automation toolkit with live session interactivity. - Robust session management: connect, reconnect, kill and limit what a browser can do. - Bleeding features like multiplexing numerous clients into a single Chrome process in an isolated way. - The ability to upload and run custom extensions. - Run multiple tokens, with access controls on each. - Multi-browser with all the robust capabilities already in the open-source images. There's a lot to cover here so let's get started! # Software Keys The Enterprise image supports time-limited software keys that allow usage for a specific period without requiring any external connections or callbacks. These keys are cryptographically secure and cannot be reverse engineered. When a key expires, the container will exit with a semantic error code. ## Using a Software Key To use a software key, set the `KEY` environment variable when running the container: ```bash docker run -e KEY=your-generated-key browserless/enterprise ``` # Using the Browserless Proxy > The Residential proxy is only available for Enterprise and Cloud plans. Browserless comes with a built-in mechanism to proxy to what's called "residential" IPs. These are IP addresses are sourced from real-users running a proxy server on their home networking machines. Residential proxying is especially useful for things like bypassing certain bot blockages and more. Using a residential proxy is as straightforward as adding a few parameters to your library or API calls. Here's the required parameters and the values they support: - `?proxy=residential`: Specifies that you want to use the residential proxy for this request. Data-center coming soon. - `?proxyCountry=us`: Specifies a country you wish to use for the request. A two-digit ISO code. - `?proxySticky=true`: If you want to use the same IP address for the entirety of the session. Generally recommended for most cases. - `?proxyPreset=px_gov01`: Website-specific proxy configuration. Use `px_gov01` for government websites to ensure optimal proxy vendor selection. Simply append these to your connection call, REST API calls, or any library call: `wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN&proxy=residential&proxyCountry=us&proxySticky` `https://production-sfo.browserless.io/chromium/unblock?token=YOUR-API-TOKEN&proxy=residential&proxyCountry=us&proxySticky` Please do note that using a proxy will increase the amount of units consumed. Every megabyte of data transferred consumes 6 units. # The Browserless CDP API In order to enhance the experience with open source libraries like Puppeteer, we decided to take a new approach to extending these libraries in a language-agnostic way. We call it the Browserless CDP API. Here's a quick list of what it can do: - Generate and give back live URLs for hybrid automation. - Solve Captchas. - Return your page's unique identifier created by Chrome. - Way more coming! Since most libraries come with a way to issue "raw" CDP commands, it's an easy way to drop-in custom behaviors without having to write and maintain a library. Plus you can continue to enjoy using the same packages you've already come to know. Getting started with this API is pretty simple. For instance, if you want to use the live viewer for a particular page, simply do the following: ```js import puppeteer from 'puppeteer-core'; (async () => { const browserWSEndpoint = 'wss://production-sfo.browserless.io/chromium'; const browser = await puppeteer.connect({ browserWSEndpoint }); const page = await browser.newPage(); const cdp = await page.createCDPSession(); await page.goto('https://example.com'); const { liveURL } = await cdp.send('Browserless.liveURL'); // liveURL = 'http://localhost:5555/live/?i=98e83bbfd396241a6963425b1feeba2f'; })(); ``` You can then visit this URL in any browser to interact with the headless Chrome running someplace else. See more below for a full list of the available APIs and features. ## Browserless.liveURL > This API is available on all plans except the Free plan. [Contact us for more information here.](https://www.browserless.io/contact/) Returns a fully-qualified URL to load into a web-browser. This URL allows for clicking, typing and other interactions with the underlying page. This URL doesn't require an authorization token, so you're free to share it externally with your own users or employees. If security is a concern, you can set a `timeout` parameter to limit the amount of time this URL is valid for. By default no `timeout` is set and the URL is good as long as the underlying browser is open. Programmatic control of the session is also available, so you can close the live session once your code has detected a selector, network call, or whatever else. See the below example for programmatic control. **Basic example** ```js import puppeteer from 'puppeteer-core'; (async () => { const browserWSEndpoint = 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN'; const browser = await puppeteer.connect({ browserWSEndpoint }); const page = await browser.newPage(); const cdp = await page.createCDPSession(); await page.goto('https://example.com'); const { liveURL } = await cdp.send('Browserless.liveURL'); // liveURL = 'https://production-sfo.browserless.io/live/?i=98e83bbfd396241a6963425b1feeba2f'; })(); ``` **Timeout example** ```js import puppeteer from 'puppeteer-core'; (async () => { const browserWSEndpoint = 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN'; const browser = await puppeteer.connect({ browserWSEndpoint }); const page = await browser.newPage(); const cdp = await page.createCDPSession(); await page.goto('https://example.com'); const { liveURL } = await cdp.send('Browserless.liveURL', { timeout: 10000, // 10 seconds to connect! }); // liveURL = 'https://production-sfo.browserless.io/live/?i=98e83bbfd396241a6963425b1feeba2f'; })(); ``` **Maintaining the width and height** By default, Browserless will dynamically change the width and height of the browser to match an end-users screen. This isn't always ideal and can be disabled by setting a `resizable` value to `false`. When this is done, only your script can alter the width and height of the browser: ```js import puppeteer from 'puppeteer-core'; (async () => { const browserWSEndpoint = 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN'; const browser = await puppeteer.connect({ browserWSEndpoint }); const page = await browser.newPage(); // Width and height will always be 1920x1080 // and the Live URL will maintain this aspect ratio await page.setViewport({ width: 1920, height: 1080 }); const cdp = await page.createCDPSession(); await page.goto('https://example.com'); const { liveURL } = await cdp.send('Browserless.liveURL', { resizable: false, }); // liveURL = 'https://production-sfo.browserless.io/live/?i=98e83bbfd396241a6963425b1feeba2f'; })(); ``` **Setting a Quality and Type** Setting a "quality" and "type" effects the streamed quality of the live URL's client-side resolution. By default, Browserless sets these to quality: 70 and type of "jpeg". You can experiment different settings to get an ideal resolutions while keep latency slow. The closer to 100 quality is, the potential for higher perceived latency. ```js import puppeteer from 'puppeteer-core'; (async () => { const browserWSEndpoint = 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN'; const browser = await puppeteer.connect({ browserWSEndpoint }); const page = await browser.newPage(); const cdp = await page.createCDPSession(); await page.goto('https://example.com'); const { liveURL } = await cdp.send('Browserless.liveURL', { quality: 70, // Can be 1 - 100. Default is 70 type: 'jpeg', // Can be 'jpeg' or 'png'. Default is 'jpeg' compressed: true, // Whether to compress each frame of the streamed image data }); // liveURL = 'https://production-sfo.browserless.io/live/?i=98e83bbfd396241a6963425b1feeba2f'; })(); ``` It's also helpful to "wait" until the user is done doing what's needed. For that reason, Browserless will fire a custom event when the page is closed as well: **Wait for close** > Custom CDP Events are not supported in all libraries, including .NET Playwright. ```js import puppeteer from 'puppeteer-core'; (async () => { const browserWSEndpoint = 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN'; const browser = await puppeteer.connect({ browserWSEndpoint }); const page = await browser.newPage(); const cdp = await page.createCDPSession(); await page.goto('https://example.com'); const { liveURL } = await cdp.send('Browserless.liveURL'); console.log(liveURL); // Wait for the Browserless.liveComplete event when the live page is closed. // Please not that not all libraries support custom CDP events. await new Promise((r) => cdp.on('Browserless.liveComplete', r)); console.log('Done!'); await browser.close(); })(); ``` **Programmatic Control** ```js import puppeteer from 'puppeteer-core'; (async () => { const browserWSEndpoint = 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN'; const browser = await puppeteer.connect({ browserWSEndpoint }); const page = await browser.newPage(); const cdp = await page.createCDPSession(); await page.goto('https://example.com'); // Having the liveURLId is required in order to close it later const { liveURL, liveURLId } = await cdp.send('Browserless.liveURL'); await page.waitForSelector('.my-selector'); // Calling this CDP API with the "liveURLId" will close the session, and terminate the client // further usage of the liveURL will fail and no more human-control is possible await cdp.send('Browserless.closeLiveURL', { liveURLId }); // Continue to process or interact with the browser, then: await browser.close(); })(); ``` It's recommended that you double check the page prior to executing further code to make sure the page is where it should be, elements are present, and so forth. This approach makes it easy to solve hard things like second-factor authentication and more in a trivial fashion. **Read-only LiveURL Sessions** The `interactive: false` option allows you to create read-only LiveURL sessions where users can view the browser but cannot interact with it. This is useful for monitoring or demonstration purposes without allowing user input. ```js import puppeteer from 'puppeteer-core'; (async () => { const browserWSEndpoint = 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN'; const browser = await puppeteer.connect({ browserWSEndpoint }); const page = await browser.newPage(); const cdp = await page.createCDPSession(); await page.goto('https://example.com'); // Create a read-only LiveURL session that users can view but not interact with const { liveURL } = await cdp.send('Browserless.liveURL', { interactive: false, }); console.log('Read-only LiveURL:', liveURL); await browser.close(); })(); ``` ## Browserless.reconnect > This API is only available for Enterprise plans. [Contact us for more information here.](https://www.browserless.io/contact/) Reconnecting allows for the underlying Chrome or Chromium process to continue to run for a specified amount of time, and subsequent reconnecting back to it. With this approach you can also "share" this connection URL to other clients to connect to the same browser process, allowing you to parallelize via a single Browser process. Once a reconnection URL is retrieved, Browserless will intercept close-based commands and stop them from terminating the browser process itself. This prevents clients from accidentally closing the process via `browser.close` or similar. In order to use this API, simply call `Browserless.reconnect` as a CDP command. You can, optionally, set a `timeout` or an `auth` property. See the below examples for details **Basic example with timeout** ```js import puppeteer from 'puppeteer-core'; (async () => { const browserWSEndpoint = 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN'; const browser = await puppeteer.connect({ browserWSEndpoint }); const page = await browser.newPage(); const cdp = await page.createCDPSession(); await page.goto('https://example.com'); // Allow this browser to run for 10 seconds, then shut down if nothing connects to it. // Defaults to the overall timeout set on the instance, which is 5 minutes if not specified. const { error, browserWSEndpoint } = await cdp.send('Browserless.reconnect', { timeout: 10000, }); if (error) throw error; await browser.close(); // browserWSEndpoint = 'https://production-sfo.browserless.io/reconnect/98e83bbfd396241a6963425b1feeba2f'; })(); ``` If you want to enforce authentication, you can pass in an optional `auth` property that clients will need to use in order to connect with. Similar to how authentication works in general, a `token` query-string parameter will need to be applied. **Authentication example** ```js import puppeteer from 'puppeteer-core'; (async () => { const browserWSEndpoint = 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN'; const browser = await puppeteer.connect({ browserWSEndpoint }); const page = await browser.newPage(); const cdp = await page.createCDPSession(); await page.goto('https://example.com'); // Set a custom authentication token that clients have to use in order to connect, or otherwise // receive a 401 Response. const { error, browserWSEndpoint } = await cdp.send('Browserless.reconnect', { auth: 'secret-auth-token', }); if (error) throw error; await browser.close(); // NOTE the URL here doesn't include the auth token! // browserWSEndpoint = 'https://production-sfo.browserless.io/reconnect/98e83bbfd396241a6963425b1feeba2f'; })(); ``` **Recursive Example** ```js import puppeteer from 'puppeteer-core'; const job = async (reconnectURL) => { const browserWSEndpoint = reconnectURL ?? 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN'; const browser = await puppeteer.connect({ browserWSEndpoint }); const [page] = await browser.page(); const cdp = await page.createCDPSession(); await page.goto('https://example.com'); // Anytime Browserless.reconnect is called, this restarts the timer back to the provided value, // effectively "bumping" the timer forward. const res = await cdp.send('Browserless.reconnect', { timeout: 30000, }); if (res.error) throw error; await browser.close(); // Continuously reconnect back... return job(res.browserWSEndpoint); }; job().catch((e) => console.error(e)); ``` ## Browserless.solveCaptcha > This API is only available for Enterprise and Scale and above plans on Cloud. [Contact us for more information here.](https://www.browserless.io/contact/). Only the `/chrome` and `/chromium` routes support Captcha solving. Browserless comes with built-in captcha solving capabilities. We use a variety of techniques to try and mitigate the chances of captchas coming up, but if you happen to run into one you can simply call on our API to solve it. Given the amount of possibilities during a captcha solve, the API returns many properties and information in order to help your script be more informed as to what happened. See the below code example for all details and fields returned by the API. Please be aware that solving a captcha can take a few seconds up to several minutes, so you'll want to increase your timeouts accordingly for your scripts. Captcha's solved, or attempted to solve, cost 10 units. ```js import puppeteer from 'puppeteer-core'; (async () => { const browser = await puppeteer.connect({ browserWSEndpoint: 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN&timeout=300000', }); const page = await browser.newPage(); const cdp = await page.createCDPSession(); await page.goto('https://www.google.com/recaptcha/api2/demo', { waitUntil: 'networkidle0', }); const { // A simple boolean indicating whether the script can proceed ok, // Whether or not a captcha was found captchaFound, // A human-readable description of what occurred. message, // Whether a solve was attempted or not solveAttempted, // If the Captcha was solved, only true if found AND solved solved, } = await cdp.send('Browserless.solveCaptcha', { // How long to wait for a Captcha to appear to solve. // Defaults to 10,000ms, or 10 seconds. appearTimeout: 30000, }); console.log(message); if (ok) { await page.click('#recaptcha-demo-submit'); } else { console.error(`Error solving captcha!`); } await browser.close(); })().catch((e) => { console.error(e); process.exit(1); }); ``` In general, if an `ok` response is sent back from this API, then your script is good to proceed with further actions. If a captcha is to suddenly appears after an action then you might want to listen for the `Browserless.foundCaptcha` event (see below) and retry solving. ## Browserless.foundCaptcha > This API is only available for Enterprise and Scale and above plans on Cloud. [Contact us for more information here.](https://www.browserless.io/contact/). Only the `/chrome` and `/chromium` routes support Captcha solving. > Custom CDP Events are not supported in all libraries, including .NET Playwright. Emitted whenever a captcha widget is found on the page. Useful for checking if there's a captcha and deciding whether or not to proceed with solving. The example below stops until a captcha is found, which may or may not be the case with every website out there. ```js import puppeteer from 'puppeteer-core'; // Recaptcha (async () => { const browser = await puppeteer.connect({ browserWSEndpoint: 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN&timeout=300000', }); const page = await browser.newPage(); const cdp = await page.createCDPSession(); await page.goto('https://www.google.com/recaptcha/api2/demo', { waitUntil: 'networkidle0', }); // Please note that not all libraries support custom CDP events. await new Promise((resolve) => cdp.on('Browserless.captchaFound', (params) => { console.log('Found a captcha!'); return resolve(); }), ); const { solved, error } = await cdp.send('Browserless.solveCaptcha'); console.log({ solved, error, }); // Continue... await page.click('#recaptcha-demo-submit'); })().catch((e) => { console.error(e); process.exit(1); }); ``` ### Event Parameters | Parameter | Type | Description | | --------- | -------- | ---------------------------------------------- | | `type` | `string` | Captcha type (`recaptcha`, `cloudflare`, etc.) | | `status` | `string` | Status: `"found"` or `"solving"` | ## Browserless.captchaAutoSolved > This API is only available for Enterprise and Scale and above plans on Cloud. [Contact us for more information here.](https://www.browserless.io/contact/). Only the `/chrome` and `/chromium` routes support Captcha solving. > Custom CDP Events are not supported in all libraries, including .NET Playwright. Emitted whenever a captcha widget is solved in the page by the auto-solving feature. Note that this event is not emitted when a captcha is solved manually. To enable this feature, you need to set the `solveCaptchas` option to `true` in your query parameters while connecting to the browser. ```js import puppeteer from 'puppeteer-core'; // Helper function to wait for a captcha to be solved const waitForCaptchaResolved = (cdp) => { return new Promise((resolve) => { const onCaptchaFound = (params) => { console.log('Captcha found, type:', params.type, params.status); cdp.on('Browserless.captchaAutoSolved', resolve); }; cdp.on('Browserless.captchaFound', onCaptchaFound); }); }; // Recaptcha (async () => { const browser = await puppeteer.connect({ browserWSEndpoint: 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN&solveCaptchas=true', }); const page = await browser.newPage(); const cdp = await page.target().createCDPSession(); await page.goto('https://www.google.com/recaptcha/api2/demo', { waitUntil: 'networkidle0', }); const captchaEvent = await waitForCaptchaResolved(cdp); console.log(captchaEvent); await browser.close(); // Continue... await page.click('#recaptcha-demo-submit'); })().catch((e) => { console.error(e); process.exit(1); }); ``` ### Event Parameters | Parameter | Type | Description | | ------------ | ---------------- | ------------------------------------------- | | `autoSolved` | `true` | Whether captcha was auto-solved | | `token` | `null \| string` | Captcha token if solved | | `found` | `boolean` | Whether a captcha was found | | `solved` | `boolean` | Whether the captcha was successfully solved | | `time` | `number` | Time taken to solve (in milliseconds) | ## Browserless.heartbeat > This API is only available for Enterprise hosted and Starter and above plans on Cloud. [Contact us for more information here.](https://www.browserless.io/contact/). > Custom CDP Events are not supported in all libraries, including .NET Playwright. A custom event emitted every several seconds, signaling a live connection. This is useful for a few reasons: - It ensure that your connection with the browser is still good. - Sending data can trigger some load-balancing technologies to not kill the connection. Today this event is emitted every 30 seconds. ```js import puppeteer from 'puppeteer-core'; const browserWSEndpoint = `wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN`; (async () => { const browser = await puppeteer.connect({ browserWSEndpoint }); const page = await browser.newPage(); await page.goto('https://example.com/'); const client = await page.createCDPSession(); client.on('Browserless.heartbeat', () => { console.log('Browserless.heartbeat'); }); })(); ``` ## Browserless.pageId > This API is only available for Enterprise hosted and Starter and above plans on Cloud. [Contact us for more information here.](https://www.browserless.io/contact/). A simple helper utility to return the page's unique ID. Since most libraries treat this ID as opaque, and some even hide it, knowing the page's ID can be of great help when interacting with other parts of Browserless. ```js import puppeteer from 'puppeteer-core'; (async () => { const browserWSEndpoint = 'wss://production-sfo.browserless.io/chromium'; const browser = await puppeteer.connect({ browserWSEndpoint }); const page = await browser.newPage(); const cdp = await page.createCDPSession(); const { pageId } = await cdp.send('Browserless.pageId'); // pageId = 'ABC12354AFDC123'; })(); ``` You can, optionally, try and "find" this ID in puppeteer or similar libraries. Given that puppeteer has this property underscored, it's likely to change or be unavailable in the future, and requires the infamous `// @ts-ignore` comment to allow TypeScript compilation. ```ts const getPageId = (page: Page): string => { // @ts-ignore return page.target()._targetId; }; ``` # Changelog

Note that these changes are only for Browserless' cloud, Enterprise and self-hosted Enterprise deployments. For information on the open-source container please refer to this link.

Latest

  • Dependency updates.

v2.95.2

  • Fix in-page WebSocket connections for /function and /download endpoints being blocked on HTTPS deployments due to mixed-content restrictions.

v2.95.1

  • Dependency updates.
  • Add Browserless.refreshProfile CDP method to update an existing profile's auth state in place without creating a duplicate.
  • Updates to @browserless.io/browserless at v2.49.0.
  • Reduce production Docker image size by removing development tooling from the final image.

v2.95.0

  • Dependency updates.
  • Fix billing and Browser Session Ended tracking for persistent session and reconnect WebSocket connections (/session/connect/:id and /reconnect/:id); each WebSocket connection is now billed independently, restoring usage accounting for persistent-session traffic.
  • Add POST /profile/upload and POST /profile/refresh endpoints to create a profile from a pre-captured auth state or replace an existing profile's state in place, with server-side sanitization of cookies, origins, and IndexedDB plus a diagnostics field describing what was filtered or truncated.
  • Fix LiveURL OAuth login for authenticated profiles, and default the browser type to stealth when creating a profile without specifying one.

v2.94.1

  • Dependency updates.
  • Cap live viewers at 5 per session ID on /live/<id> and return 429 Too Many Requests once exceeded, freeing slots automatically when viewers disconnect.
  • Include captcha detection and classification in snapshot captures, giving agents better visibility into security challenges encountered during automation.
  • Add an optional profile parameter to crawl requests for authenticated scraping; crawls now end early on critical errors, truncate oversized error messages, and return 503 if the profile service is unavailable.

v2.94.0

  • Updates to @browserless.io/browserless at v2.48.3.
  • Dependency updates.
  • Fix agent snapshot generation when pages contain malformed or empty HTML attributes, so snapshots no longer fail on attribute encoding edge cases.
  • Add an optional profile parameter to /scrape requests for server-side hydration of authenticated browser profiles; requests that use a profile now require an API token and return clearer validation errors.
  • LiveURL sessions now show distinct end-of-session messages for timeouts versus manual closures, and the message is delivered before the socket disconnects so users actually see it.
  • Credit limit error messages now link to https://browserless.io/account/upgrade instead of the generic account page, and have minor grammar fixes.

v2.93.0

  • Update @browserless.io/browserless to v2.48.2
  • Improve proxy city targeting
  • Add tab management methods for agents

v2.92.3

  • Add Akamai captcha solving support.

v2.92.2

  • Improve browser fingerprint consistency for CPU architecture and font rendering in Docker images.
  • Dependency updates

v2.92.1

  • Enable agentic browsing for all accounts
  • Dependency updates

v2.92.0

  • Add authenticated profiles: capture a logged-in browser's cookies, localStorage, and IndexedDB once via Browserless.saveProfile, then reuse on any session with ?profile=<name>.
  • Add HTTP API for profile lifecycle: POST /profile, GET /profiles, GET|PUT|DELETE /profile/:name.

v2.91.0

  • Add route for agentic browsing

v2.90.6

  • Set default /crawl scrape timeout to 150s.
  • Add customer.id to OpenTelemetry resource attributes.
  • Add Content-Disposition header for PDF API responses.
  • Improve hCaptcha handling by hiding the auto-challenge.
  • Cache uBOL-home release metadata in the adblock build.

v2.90.5

  • Update search limits: Free 1→3, Prototyping 3→5, Starter 5→10, Scale 10→20.
  • Dependency updates.

v2.90.4

  • Improve DataDome captcha solving reliability.

v2.90.3

  • Add captcha solving support for browser-use sessions.

v2.90.2

  • Add DataDome captcha solving support.
  • Improve smart-scrape captcha detection and post-challenge navigation.
  • Add captcha solving support for browser-use sessions.
  • Improve /crawl API with enhanced orchestration and documentation.
  • Fix timeout override for applicable routes.
  • Fix session TTL display for browser sessions.
  • Bug fixes and improvements.

v2.90.1

  • Bug fixes and improvements.

v2.90.0

  • New crawl API for scalable web crawling.
  • Fix BQL close() overwriting reconnect keepUntil with zero TTL.

v2.89.2

  • Updates to @browserless.io/browserless at v2.46.0.
  • Fix 400 errors caused by strict Record<string,string> types in API schemas.
  • Fix Docker multi-heavy base image tagging.
  • Dependency updates.

v2.89.1

  • Updates to @browserless.io/browserless at v2.45.0.
  • Fix proxy SSL certificate errors (ERR_CERT_AUTHORITY_INVALID).
  • Improve proxy vendor health checks and failover reliability.
  • Harden URL validation against SSRF and DNS rebinding.
  • Fix session TTL management.
  • Fix stopRecording hanging in certain error conditions.
  • Fix recording quality for VHS sessions.
  • Unify scrape format types across REST API schemas.

v2.89.0

  • Add metadata enrichment for /map endpoint.
  • Add option to transfer base64 instead of binary for recordings.
  • Fix liveURL blank screen.
  • Fix bypass CSP for virtual keyboard and emulated <select>s.
  • Fix high CPU consumption for /map.
  • Add --disable-component-extensions-with-background-pages to stealth args.

v2.88.2

  • Updates to browserless.io/browserless at v2.43.0.

v2.88.1

  • New /map API.
  • Add emulateComponents option for liveURL.
  • Dependency updates.

v2.87.0

  • Deprecate codes in waitForResponse mutation, favoring statuses instead.
  • Fix <select /> elements in liveURL view.
  • Enable uploaded extensions cache.
  • New /search API.

v2.86.1

  • Power-scrape endpoint is now smart-scrape.
  • Improve Turnstile captcha detection and solving.
  • Improve session replay in reconnect sessions.
  • Improve stealth chromium for persistent sessions.

v2.86.0

  • Updates to browserless.io/browserless at v2.42.0.
  • Updates NodeJS to 24.14.0.
  • Supports puppeteer-core version 24.37.5.
  • Dependency updates.
  • Added support for loading extensions from session metadata.

v2.85.1

  • Supports HTTPs third party proxies in BQL
  • Fixes mobile typing bug in liveURL

v2.85.0

  • Updates to browserless.io/browserless at v2.41.0.
  • Supports puppeteer-core version 24.37.4.
  • OTEL support.

v2.84.2

  • Fix power scraper initialization bug

v2.84.1

  • Fix query param validation bug

v2.84.0

  • New power scrape endpoint for intelligent content extraction.
  • Fix external proxies in BQL incorrectly charging proxy units.

v2.83.0

  • Fix proxy consumption bug
  • Fix screencasting video dimensions
  • Improve docker image size

v2.82.1

  • Bug fixes.

v2.82.0

  • Added new proxy vendor.
  • New processKeepAlive flag.
  • Fix screencasting video dimensions.
  • liveURL connection issues.

v2.81.0

  • Updates to browserless.io/browserless at v2.39.0.
  • Session replay improvements.
  • Improve proxy mutations in BQL.
  • Additional captchas support.
  • Supports playwright-core versions 1.41.2, 1.42.1, 1.43.1, 1.44.1, 1.45.3, 1.46.1, 1.47.2, 1.48.2, 1.49.1, 1.50.1, 1.51.1, 1.52.0, 1.53.2, 1.54.2, 1.55.1, 1.56.1, 1.57.0 and 1.58.1.
  • Supports puppeteer-core version 24.36.1.

v2.80.1

  • Improve CAPTCHA detection and solving.
  • Support for external proxy server parameter.

v2.80.0

  • Updates to browserless.io/browserless at v2.38.4.
  • Updates NodeJS to 24.13.0.
  • Improve captcha solving performance.
  • Additional captchas support.
  • Supports playwright-core versions 1.41.2, 1.42.1, 1.43.1, 1.44.1, 1.45.3, 1.46.1, 1.47.2, 1.48.2, 1.49.1, 1.50.1, 1.51.1, 1.52.0, 1.53.2, 1.54.2, 1.55.1, 1.56.1 and 1.57.0.
  • Supports puppeteer-core version 24.36.0.

v2.79.2

  • Improve CAPTCHA detection and solving.

v2.79.1

  • Improve liveURL rendering in high DPI displays.
  • Bug fixes.

v2.79.0

  • Improve CAPTCHA detection mechanism.
  • Fix bug where deeply nested elements weren't found in nested shadow DOMs

v2.78.3

  • Improved BQL proxy URL regeneration on reconnects
  • Streamlined event logging

v2.78.2

  • Improved proxy connection reliability

v2.78.1

  • Upgraded browser tracking TTL

v2.78.0

  • Improved stealth and bot detection evasion capabilities

v2.77.1

  • Fix black screen issue with live urls

v2.77.0

  • New MAX_RECONNECT_TIME launch flag
  • Ensure the WS connection is always closed when using the /kill endpoint
  • Improve captcha detection
  • Fix bug in live URL that added an offset to mouse events

v2.76.0

  • Improve proxy reliability and performance
  • Fix third party proxies for BQL
  • Improve captcha solving performance

v2.75.0

  • Improved proxy reliability and performance
  • Enhanced captcha detection
  • Better stealth mode compatibility
  • Session replay improvements

v2.74.4

  • Stealth route enhancements
  • Connection stability improvements

v2.74.3

  • Enhanced captcha handling

v2.74.2

  • Bug fixes and improvements

v2.74.1

  • Added proxy provider configuration options

v2.74.0

  • Dependency updates
  • Improved captcha support for BQL
  • Performance optimizations

v2.73.2

  • Improve Resdential Proxy Quaility

v2.73.1

  • Minor improvements in liveURL client

v2.73.0

  • Add proxyLocaleMatch parameter to set browser language based on proxy country
  • Fix BQL session replay

v2.72.1

  • Deprecate verify mutation
  • Improve captcha callback function caller
  • Improve internal logs

v2.72.0

  • Added new proxy vendor
  • New solveImageCaptcha mutation
  • Better handle proxy requests that contains cities

v2.71.1

  • Fix bug in /unblock API where it errored if the screenshot parameter was not set
  • Allow all paid accounts to use the screencasting API

v2.71.0

  • Implemented new proxy provider
  • Improved Cloudflare CAPTCHA solver

v2.70.2

  • Updated proxy provider priority

v2.70.1

  • Improved recaptcha-v3 solver for speed and reliability improvements
  • Added /proxy/cities API endpoint for getting a list of supported proxy cities
  • Improved selectors for normal captcha, and Cloudflare captcha

v2.70.0

  • Improved recaptcha v3 support
  • Add fallback between captcha solvers
  • Improve event logging

v2.69.1

  • Dependency updates.
  • Improved recaptcha v2 support in stealth routes

v2.69.0

  • Match the browsers to the stealth endpoints.
  • Cloudflare captcha tracking improvements

v2.68.5

  • Added support for Turnstile Cloudflare captcha
  • Fixed amplitude attempt events to track Cloudflare captchas correctly
  • Added captcha subtype to amplitude events

v2.68.4

  • clean disk space before building docker images

v2.68.3

  • Restore automation of timezone and add proxy city validation changes

v2.68.1

  • Dependency updates.
  • Bug fixes and improvements

v2.68.0

  • Dependency updates.
  • Allow --disable-bundled-ppapi-flash, --disable-dev-shm-usage, --disable-domain-reliability, --disable-gpu, --disable-speech-api, --disable-webgl, and --wm-window-animations-disabled flags to be used.
  • Improve CAPTCHA solvers.

v2.67.1

  • Bug fixes and improvements

v2.67.0

  • Updates to browserless.io/browserless at v2.38.2.
  • Supports playwright-core versions 1.41.2, 1.42.1, 1.43.1, 1.44.1, 1.45.3, 1.46.1, 1.47.2, 1.48.2, 1.49.1, 1.50.1, 1.51.1, 1.52.0, 1.53.2, 1.54.2, and 1.55.1.
  • Supports puppeteer-core version 24.26.1.
  • Allow using Brave on BQL
  • Captcha selector fixes

v2.66.2

  • Critical security bug fix

v2.66.1

  • Critical security bug fix

v2.66.0

  • Revert proxy city and timezone changes
  • Upgrade Playwright, Puppeteer and Browserless
  • Upgrade Chrome to 141.0
  • Support for Capy challenges

v2.65.2

  • Improve CAPTCHA detection and solving.

v2.65.1

  • Add city database for proxy validation
  • Validate cities against supported proxy providers
  • Automate timezone based on proxy location

v2.65.0

  • Dependency updates
  • New @export directive
  • Fix timeout in solve captcha mutations
  • Normalize allowed cities for proxies
  • Fix Amplitude IDs for sessions

v2.64.3

  • Fix Amplitude logging error

v2.64.1

  • Allow using solveCaptchas on stealth routes.

v2.64.0

  • Dependency updates.
  • New feature: auto solve captcha.
  • Improve captcha resolution state polling.
  • Fix captcha solving edge cases.

v2.63.3

  • Dependency updates.
  • Log more event properties on Captcha Solve Error events.
  • Allow sending acceptInsecureCerts as query param.
  • Improve captcha-solving parameter sanitation.

v2.63.2

  • Dependency updates.
  • Updates to @browserless.io/browserless 2.37.1.

v2.63.1

  • Dependency updates.
  • Switches to ioredis for cloud-unit platform.

v2.63.0

  • Dependency updates.
  • Major /stealth route enhancements.
  • Many testing updates for internal stability.
  • Fixes BrowserQL goto calls that return a chrome-related error.
  • Other fixes and updates for stealth and captcha solving.

v2.62.1

  • Dependency updates.
  • Better timeout messages on cloud platform.
  • Other testing fixes.

v2.62.0

  • Dependency updates.
  • Update to @browserless.io/browserless 2.37.0.
  • Minor build updates and unit-test enhancements.
  • BrowserQL click mutation fixes and reliability improvements.
  • Fix /pdf, /screenshot and other REST APIs with requestInterceptors that contain base64 responses.
  • Other minor fixes and improvements.

v2.61.2

  • Dependency updates.
  • Cleanup of internal docs.
  • Fixes and issue with /unblock API's waitForFn properties.

v2.61.1

  • Dependency updates.
  • Fixes an issue where /unblock might orphan the browser process.
  • Logging and analytics improvements in cloud.

v2.61.0

  • Dependency updates.
  • Update to Ubuntu 24.04.
  • Update @browserless.io/browserless to 2.36.0.
  • New switchToWindow BrowserQL API.
  • Stealth enhancements and updates.
  • Prettier changes on source, logging cleanup.

v2.60.1

  • Dependency updates.
  • BrowserQL documentation updates and enhancements.
  • Analytical improvements on the cloud-unit platform.

v2.60.0

  • Dependency updates.
  • Replay feature is now shipped for cloud-unit.
  • Documentation cleanup and updates.
  • Updated request parsing and parameter handling.
  • Hybrid URL logging clean up.
  • Stealth enhancements and improvements.

v2.59.0

  • Dependency updates.
  • Stealth updates to all stealth enabled routes.
  • Fixes and updates to our captcha-solving capabilities.
  • Use npm ci for production builds (prevents unintentional package updates).
  • Other fixes and updates.

v2.57.0

  • New fingerprint management and rotation for browserless' /stealth CDP routes!
  • Updates to browserless.io/browserless@2.34.1
  • Supports playwright-core versions 1.41.2, 1.42.1, 1.43.1, 1.44.1, 1.45.3, 1.46.1, 1.47.2, 1.48.2, 1.49.1, 1.50.1, 1.51.1, 1.52.0, 1.53.1, and 1.54.2.
  • Supports puppeteer-core version 24.16.2.
  • Captcha solving updates and improvements.

v2.56.0

  • Updates to browserless.io/browserless at v2.34.0.
  • Supports playwright-core versions 1.41.2, 1.42.1, 1.43.1, 1.44.1, 1.45.3, 1.46.1, 1.47.2, 1.48.2, 1.49.1, 1.50.1, 1.51.1, 1.52.0, 1.53.1, and 1.54.2.
  • Supports puppeteer-core version 24.16.1.
  • Supports using of Chrome Extensions in cloud-unit products. Please refer to documentation on how to use this new feature.
  • Sessions API now support interoperability with BrowserQL.
  • Introduces a new vendor for Captcha Solving.
  • New environment variables:
    • EXTENSIONS_DIR The directory to store extensions onto.
    • LOAD_EXTENSIONS_FROM_CLOUD Whether or not to load extensions from a S3 compatible URL.
    • EXTENSIONS_CLOUD_BUCKET The bucket for extensions to be loaded from.
    • EXTENSIONS_CLOUD_REGION The region to load extensions from.
    • CAPSOLVER_API_KEY An API key to use for when Capsolver is used for captcha solving.

v2.55.0

  • Dependency updates.
  • Reverts some breaking stealth changes in favor of stability.
  • Adds a "mode" option in BQL's removeAttributes parameter for better HTML parsing.

v2.54.0

  • Dependency updates.
  • New LiveURL updates that include an optional showBrowserInterface for rendering all the tabs.
  • Fixes some issues with stealth and headers that Chrome generates.

v2.53.1

  • Revert live-URL updates until they're backwards compatible.

v2.53.0

  • Dependency updates.g
  • New viewport API for BQL.
  • Consolidation of some internal utilities for consistency sake.
  • Big improvements to the /stealth routes for CDP libraries.
  • You can solveCaptcha without specifying the vendor in BQL.
  • Support for proxying through residential proxy providers.
  • Fixes an issue in BQL that can cause a browser to stay open when navigating.
  • LiveURL can now support multi-tabs workflows.
  • Testing fixes.

v2.52.4

  • Fixes an issue when deleting sessions

v2.52.3

  • Updates to proxying for future compatibility

v2.52.2

  • Fixes an issue where proxying can cause un-necessary latency

v2.52.1

  • Fix BQL navigation not filtering out iframe page events.

v2.52.0

  • Dependency updates.
  • Fixes navigation (goto, back, forward) issues in BQL for goto, forward and backward actions.
  • blockConsentModal is now default to false in BQL as it sometimes causes sites to hang indefinitely when loading.
  • New amazonWaf for BQL captcha solving.
  • New downloading handling forcing all downloads to be in a configurable path by setting a DOWNLOAD_DIR.
  • Fix page's created by playwright's context object hanging.
  • Fix issues with CDP-based screen-recording.
  • Other fixes, improvements, and reliability enhancements.
  • Bumps puppeteer-core to 24.12.1.
  • Bumps playwright-core to 1.54.1.
  • Drops support for playwright-core at 1.49.
  • Supports:
    • puppeteer-core: 24.12.1
    • playwright-core: 1.41.2, 1.42.1, 1.43.1, 1.44.1, 1.45.3, 1.46.1, 1.47.2, 1.48.2, 1.49.1, 1.50.1, 1.51.1, 1.52.0,
    • Chromium: 139.0.7258.5
    • Firefox: 140.0.2
    • Webkit: 26.0
    • Chrome: 138.0.7204.101 (amd64 only)
    • Edge: 138.0.3351.83 (amd64 only)
openapi: 3.0.0 paths: /chrome/content: post: definitions: {} description: >- A JSON-based API. Given a "url" or "html" field, runs and returns HTML content after the page has loaded and JavaScript has parsed. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: launch schema: anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: application/json: schema: properties: addScriptTag: type: array items: $ref: '#/definitions/FrameAddScriptTagOptions' addStyleTag: type: array items: $ref: '#/definitions/FrameAddStyleTagOptions' authenticate: anyOf: - $ref: '#/definitions/Credentials' - type: 'null' bestAttempt: description: >- When bestAttempt is set to true, browserless attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more. type: boolean cookies: type: array items: $ref: '#/definitions/CookieParam' emulateMediaType: type: string gotoOptions: $ref: '#/definitions/GoToOptions' html: type: string rejectRequestPattern: type: array items: type: string rejectResourceTypes: type: array items: enum: - cspviolationreport - document - eventsource - fedcm - fetch - font - image - manifest - media - other - ping - prefetch - preflight - script - signedexchange - stylesheet - texttrack - websocket - xhr type: string requestInterceptors: type: array items: description: >- An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests. type: object properties: pattern: description: >- An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests. type: string response: additionalProperties: false type: object properties: headers: description: >- Optional response headers. The record values will be converted to string following: Arrays' values will be mapped to String (Used when you need multiple headers with the same name). Non-arrays will be converted to String. $ref: '#/definitions/Record%3Cstring%2Cunknown%3E' status: type: number contentType: type: string body: description: >- A string representation of the body to return. Can be a base64-encoded string but please omit any leading content-type data (eg "data:image/png;base64,"). type: string additionalProperties: false required: - pattern - response setExtraHTTPHeaders: type: object additionalProperties: type: string setJavaScriptEnabled: description: Whether or not to allow JavaScript to run on the page. type: boolean url: type: string userAgent: type: object properties: userAgent: type: string userAgentMetadata: description: >- Used to specify User Agent Client Hints to emulate. See https://wicg.github.io/ua-client-hints Missing optional values will be filled in by the target with what it would normally use. $ref: '#/definitions/Protocol.Emulation.UserAgentMetadata' platform: type: string additionalProperties: false viewport: anyOf: - $ref: '#/definitions/Viewport' - type: 'null' waitForEvent: type: object properties: event: type: string timeout: type: number additionalProperties: false required: - event waitForFunction: type: object properties: fn: description: >- The function, or statement, to be evaluated in browser context type: string polling: description: >- An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values: "raf" or "mutation" type: - string - number timeout: description: >- Maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout. type: number additionalProperties: false required: - fn waitForSelector: type: object properties: hidden: type: boolean selector: type: string timeout: type: number visible: type: boolean additionalProperties: false required: - selector waitForTimeout: type: number type: object responses: '200': content: text/html: schema: description: |- An HTML payload of the website or HTML after JavaScript parsing and execution. type: string $schema: http://json-schema.org/draft-07/schema# description: |- An HTML payload of the website or HTML after JavaScript parsing and execution. '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /chrome/content tags: - Browser REST APIs /chrome/download: post: definitions: {} description: >- A JSON or JavaScript content-type API for returning files Chrome has downloaded during 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. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: launch schema: description: |- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: application/json: schema: $ref: '#/definitions/JSONSchema' application/javascript: schema: type: string responses: '200': content: '*/*': schema: description: >- Responses are determined by the returned value of the downloads themselves, so there isn't a static response type for this API. $schema: http://json-schema.org/draft-07/schema# description: |- Responses are determined by the returned value of the downloads themselves, so there isn't a static response type for this API. '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /chrome/download tags: - Browser REST APIs /chrome/function: post: definitions: {} description: >- A JSON or JavaScript content-type API for running puppeteer code in the browser's context. 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. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: launch schema: description: |- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: application/json: schema: $ref: '#/definitions/JSONSchema' application/javascript: schema: type: string responses: '200': content: '*/*': schema: description: >- Responses are determined by the returned value of the function itself. Binary responses (PDF's, screenshots) are returned back as binary data, and primitive JavaScript values are returned back by type (HTML data is "text/html", Objects are "application/json") $schema: http://json-schema.org/draft-07/schema# description: |- Responses are determined by the returned value of the function itself. Binary responses (PDF's, screenshots) are returned back as binary data, and primitive JavaScript values are returned back by type (HTML data is "text/html", Objects are "application/json") '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /chrome/function tags: - Browser REST APIs /json/new: put: definitions: {} description: >- 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. parameters: [] requestBody: content: {} responses: '200': content: application/json: schema: type: object properties: description: description: The description of the target. Generally the page's title. type: string devtoolsFrontendUrl: description: The fully-qualified URL of the Devtools inspector app. type: string id: description: A Unique Id for the underlying target. type: string title: description: >- The title of the target. For pages this is the page's title. type: string type: description: The type of target, generally "page" or "background_page". type: string url: description: The current URL the target is consuming or visiting. type: string webSocketDebuggerUrl: description: >- The target or page's WebSocket Debugger URL. Primarily used for legacy libraries to connect and inspect or remote automate this target. type: string additionalProperties: false required: - description - devtoolsFrontendUrl - id - title - type - url - webSocketDebuggerUrl $schema: http://json-schema.org/draft-07/schema# '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /json/new tags: - Browser REST APIs /json/protocol: get: definitions: {} description: Returns Protocol JSON meta-data that Chrome and Chromium come with. parameters: [] requestBody: content: {} responses: '200': content: application/json: schema: type: object properties: {} additionalProperties: true $schema: http://json-schema.org/draft-07/schema# '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /json/protocol tags: - Browser REST APIs /json/version: get: definitions: {} description: >- Returns a JSON payload that acts as a pass-through to the DevTools /json/version protocol in Chrome and Chromium. parameters: [] requestBody: content: {} responses: '200': content: application/json: schema: type: object properties: description: description: The description of the target. Generally the page's title. type: string devtoolsFrontendUrl: description: The fully-qualified URL of the Devtools inspector app. type: string id: description: A Unique Id for the underlying target. type: string title: description: >- The title of the target. For pages this is the page's title. type: string type: description: The type of target, generally "page" or "background_page". type: string url: description: The current URL the target is consuming or visiting. type: string webSocketDebuggerUrl: description: >- The target or page's WebSocket Debugger URL. Primarily used for legacy libraries to connect and inspect or remote automate this target. type: string additionalProperties: false required: - description - devtoolsFrontendUrl - id - title - type - url - webSocketDebuggerUrl $schema: http://json-schema.org/draft-07/schema# '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /json/version tags: - Browser REST APIs /chrome/pdf: post: definitions: {} description: |- A JSON-based API for getting a PDF binary from either a supplied "url" or "html" payload in your request. Many options exist for injecting cookies, request interceptors, user-agents and waiting for selectors, timers and more. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: launch schema: description: |- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: application/json: schema: properties: addScriptTag: type: array items: $ref: '#/definitions/FrameAddScriptTagOptions' addStyleTag: type: array items: $ref: '#/definitions/FrameAddStyleTagOptions' authenticate: anyOf: - $ref: '#/definitions/Credentials' - type: 'null' bestAttempt: description: >- When bestAttempt is set to true, browserless attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more. type: boolean cookies: type: array items: $ref: '#/definitions/CookieParam' emulateMediaType: type: string gotoOptions: $ref: '#/definitions/GoToOptions' html: type: string options: additionalProperties: false type: object properties: scale: description: >- Scales the rendering of the web page. Amount must be between `0.1` and `2`. type: number displayHeaderFooter: description: Whether to show the header and footer. type: boolean headerTemplate: description: >- HTML template for the print header. Should be valid HTML with the following classes used to inject values into them: - `date` formatted print date - `title` document title - `url` document location - `pageNumber` current page number - `totalPages` total pages in the document type: string footerTemplate: description: >- HTML template for the print footer. Has the same constraints and support for special classes as {@link PDFOptions.headerTemplate}. type: string printBackground: description: Set to `true` to print background graphics. type: boolean landscape: description: Whether to print in landscape orientation. type: boolean pageRanges: description: Paper ranges to print, e.g. `1-5, 8, 11-13`. type: string format: description: All the valid paper format types when printing a PDF. enum: - A0 - A1 - A2 - A3 - A4 - A5 - A6 - LEDGER - LEGAL - LETTER - Ledger - Legal - Letter - TABLOID - Tabloid - a0 - a1 - a2 - a3 - a4 - a5 - a6 - ledger - legal - letter - tabloid type: string width: description: >- Sets the width of paper. You can pass in a number or a string with a unit. type: - string - number height: description: >- Sets the height of paper. You can pass in a number or a string with a unit. type: - string - number preferCSSPageSize: description: >- Give any CSS `@page` size declared in the page priority over what is declared in the `width` or `height` or `format` option. type: boolean margin: description: Set the PDF margins. $ref: '#/definitions/PDFMargin' path: description: The path to save the file to. type: string omitBackground: description: >- Hides default white background and allows generating pdfs with transparency. type: boolean tagged: description: Generate tagged (accessible) PDF. type: boolean outline: description: Generate document outline. type: boolean timeout: description: >- Timeout in milliseconds. Pass `0` to disable timeout. The default value can be changed by using {@link Page.setDefaultTimeout} type: number waitForFonts: description: >- If true, waits for `document.fonts.ready` to resolve. This might require activating the page using {@link Page.bringToFront} if the page is in the background. type: boolean fullPage: type: boolean rejectRequestPattern: type: array items: type: string rejectResourceTypes: type: array items: enum: - cspviolationreport - document - eventsource - fedcm - fetch - font - image - manifest - media - other - ping - prefetch - preflight - script - signedexchange - stylesheet - texttrack - websocket - xhr type: string requestInterceptors: type: array items: description: >- An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests. type: object properties: pattern: description: >- An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests. type: string response: additionalProperties: false type: object properties: headers: description: >- Optional response headers. The record values will be converted to string following: Arrays' values will be mapped to String (Used when you need multiple headers with the same name). Non-arrays will be converted to String. $ref: '#/definitions/Record%3Cstring%2Cunknown%3E' status: type: number contentType: type: string body: description: >- A string representation of the body to return. Can be a base64-encoded string but please omit any leading content-type data (eg "data:image/png;base64,"). type: string additionalProperties: false required: - pattern - response setExtraHTTPHeaders: type: object additionalProperties: type: string setJavaScriptEnabled: type: boolean url: type: string userAgent: type: object properties: userAgent: type: string userAgentMetadata: description: >- Used to specify User Agent Client Hints to emulate. See https://wicg.github.io/ua-client-hints Missing optional values will be filled in by the target with what it would normally use. $ref: '#/definitions/Protocol.Emulation.UserAgentMetadata' platform: type: string additionalProperties: false viewport: anyOf: - $ref: '#/definitions/Viewport' - type: 'null' waitForEvent: type: object properties: event: type: string timeout: type: number additionalProperties: false required: - event waitForFunction: type: object properties: fn: description: >- The function, or statement, to be evaluated in browser context type: string polling: description: >- An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values: "raf" or "mutation" type: - string - number timeout: description: >- Maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout. type: number additionalProperties: false required: - fn waitForSelector: type: object properties: hidden: type: boolean selector: type: string timeout: type: number visible: type: boolean additionalProperties: false required: - selector waitForTimeout: type: number type: object responses: '200': content: application/pdf: schema: description: Responds with an application/pdf content-type and a binary PDF type: string $schema: http://json-schema.org/draft-07/schema# description: Responds with an application/pdf content-type and a binary PDF '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /chrome/pdf tags: - Browser REST APIs /chrome/performance: post: definitions: {} description: >- Run lighthouse performance audits with a supplied "url" in your JSON payload. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: launch schema: description: |- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: application/json: schema: properties: budgets: type: array items: type: object properties: {} additionalProperties: true config: type: object properties: {} additionalProperties: true url: type: string type: object required: - url responses: '200': content: application/json: schema: description: |- The response of the lighthouse stats. Response objects are determined by the type of budgets and config in the POST JSON body type: object properties: {} additionalProperties: true $schema: http://json-schema.org/draft-07/schema# description: |- The response of the lighthouse stats. Response objects are determined by the type of budgets and config in the POST JSON body '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /chrome/performance tags: - Browser REST APIs /chrome/scrape: post: definitions: {} description: >- A JSON-based API that returns text, html, and meta-data from a given list of selectors. Debugging information is available by sending in the appropriate flags in the "debugOpts" property. Responds with an array of JSON objects. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: launch schema: anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: application/json: schema: properties: addScriptTag: type: array items: $ref: '#/definitions/FrameAddScriptTagOptions' addStyleTag: type: array items: $ref: '#/definitions/FrameAddStyleTagOptions' authenticate: anyOf: - $ref: '#/definitions/Credentials' - type: 'null' bestAttempt: description: >- When bestAttempt is set to true, browserless attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more. type: boolean cookies: type: array items: $ref: '#/definitions/CookieParam' debugOpts: $ref: '#/definitions/ScrapeDebugOptions' elements: type: array items: $ref: '#/definitions/ScrapeElementSelector' emulateMediaType: type: string gotoOptions: $ref: '#/definitions/GoToOptions' html: type: string rejectRequestPattern: type: array items: type: string rejectResourceTypes: type: array items: enum: - cspviolationreport - document - eventsource - fedcm - fetch - font - image - manifest - media - other - ping - prefetch - preflight - script - signedexchange - stylesheet - texttrack - websocket - xhr type: string requestInterceptors: type: array items: description: >- An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests. type: object properties: pattern: description: >- An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests. type: string response: additionalProperties: false type: object properties: headers: description: >- Optional response headers. The record values will be converted to string following: Arrays' values will be mapped to String (Used when you need multiple headers with the same name). Non-arrays will be converted to String. $ref: '#/definitions/Record%3Cstring%2Cunknown%3E' status: type: number contentType: type: string body: description: >- A string representation of the body to return. Can be a base64-encoded string but please omit any leading content-type data (eg "data:image/png;base64,"). type: string additionalProperties: false required: - pattern - response setExtraHTTPHeaders: type: object additionalProperties: type: string setJavaScriptEnabled: type: boolean url: type: string userAgent: type: object properties: userAgent: type: string userAgentMetadata: description: >- Used to specify User Agent Client Hints to emulate. See https://wicg.github.io/ua-client-hints Missing optional values will be filled in by the target with what it would normally use. $ref: '#/definitions/Protocol.Emulation.UserAgentMetadata' platform: type: string additionalProperties: false viewport: anyOf: - $ref: '#/definitions/Viewport' - type: 'null' waitForEvent: type: object properties: event: type: string timeout: type: number additionalProperties: false required: - event waitForFunction: type: object properties: fn: description: >- The function, or statement, to be evaluated in browser context type: string polling: description: >- An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values: "raf" or "mutation" type: - string - number timeout: description: >- Maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout. type: number additionalProperties: false required: - fn waitForSelector: type: object properties: hidden: type: boolean selector: type: string timeout: type: number visible: type: boolean additionalProperties: false required: - selector waitForTimeout: type: number type: object required: - elements responses: '200': content: application/json: schema: description: The JSON response body type: object properties: data: anyOf: - type: array items: type: object properties: results: type: array items: type: object properties: attributes: description: A list of HTML attributes of the element type: array items: type: object properties: name: description: >- The name of the HTML attribute for the element type: string value: description: >- The value of the HTML attribute for the element type: string additionalProperties: false required: - name - value height: description: The height the element type: number html: description: The HTML the element type: string left: description: >- The amount of pixels from the left of the page type: number text: description: The text the element type: string top: description: >- The amount of pixels from the top of the page type: number width: description: The width the element type: number additionalProperties: false required: - attributes - height - html - left - text - top - width selector: description: The DOM selector of the element type: string additionalProperties: false required: - results - selector - type: 'null' debug: description: When debugOpts options are present, results are here anyOf: - type: object properties: console: description: A list of console messages from the browser type: array items: type: string cookies: description: List of cookies for the site or null anyOf: - type: array items: $ref: '#/definitions/Cookie' - type: 'null' html: description: The HTML string of the website or null type: - 'null' - string network: type: object properties: inbound: type: array items: $ref: '#/definitions/InBoundRequest' outbound: type: array items: $ref: '#/definitions/OutBoundRequest' additionalProperties: false required: - inbound - outbound screenshot: description: A base64-encoded string of the site or null type: - 'null' - string additionalProperties: false required: - console - cookies - html - network - screenshot - type: 'null' additionalProperties: false required: - data - debug definitions: Cookie: description: Represents a cookie object. type: object properties: path: description: Cookie path. type: string expires: description: >- Cookie expiration date as the number of seconds since the UNIX epoch. Set to `-1` for session cookies type: number size: description: Cookie size. type: number secure: description: True if cookie is secure. type: boolean session: description: True in case of session cookie. type: boolean partitionKeyOpaque: description: >- True if cookie partition key is opaque. Supported only in Chrome. type: boolean name: description: Cookie name. type: string value: description: Cookie value. type: string domain: description: Cookie domain. type: string httpOnly: description: True if cookie is http-only. type: boolean sameSite: description: Cookie SameSite type. enum: - Default - Lax - None - Strict type: string priority: description: Cookie Priority. Supported only in Chrome. enum: - High - Low - Medium type: string sameParty: type: boolean sourceScheme: description: Cookie source scheme type. Supported only in Chrome. enum: - NonSecure - Secure - Unset type: string partitionKey: description: >- Cookie partition key. In Chrome, it matches the top-level site the partitioned cookie is available in. In Firefox, it matches the source origin in the {@link https://w3c.github.io/webdriver-bidi/#type-storage-PartitionKey PartitionKey}. anyOf: - $ref: '#/definitions/CookiePartitionKey' - type: string additionalProperties: false required: - domain - expires - name - path - secure - session - size - value CookiePartitionKey: description: Represents a cookie partition key in Chrome. type: object properties: sourceOrigin: description: >- The site of the top-level URL the browser was visiting at the start of the request to the endpoint that set the cookie. In Chrome, maps to the CDP's `topLevelSite` partition key. type: string hasCrossSiteAncestor: description: >- Indicates if the cookie has any ancestors that are cross-site to the topLevelSite. Supported only in Chrome. type: boolean additionalProperties: false required: - sourceOrigin InBoundRequest: type: object properties: headers: {} status: type: number url: type: string additionalProperties: false required: - headers - status - url OutBoundRequest: type: object properties: headers: {} method: type: string url: type: string additionalProperties: false required: - headers - method - url $schema: http://json-schema.org/draft-07/schema# description: The JSON response body '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /chrome/scrape tags: - Browser REST APIs /chrome/screenshot: post: definitions: {} description: |- A JSON-based API for getting a screenshot binary from either a supplied "url" or "html" payload in your request. Many options exist including cookies, user-agents, setting timers and network mocks. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: launch schema: description: |- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: application/json: schema: properties: addScriptTag: type: array items: $ref: '#/definitions/FrameAddScriptTagOptions' addStyleTag: type: array items: $ref: '#/definitions/FrameAddStyleTagOptions' authenticate: anyOf: - $ref: '#/definitions/Credentials' - type: 'null' bestAttempt: description: >- When bestAttempt is set to true, browserless attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more. type: boolean cookies: type: array items: $ref: '#/definitions/CookieParam' emulateMediaType: type: string gotoOptions: $ref: '#/definitions/GoToOptions' html: type: string options: $ref: '#/definitions/ScreenshotOptions' rejectRequestPattern: type: array items: type: string rejectResourceTypes: type: array items: enum: - cspviolationreport - document - eventsource - fedcm - fetch - font - image - manifest - media - other - ping - prefetch - preflight - script - signedexchange - stylesheet - texttrack - websocket - xhr type: string requestInterceptors: type: array items: description: >- An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests. type: object properties: pattern: description: >- An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests. type: string response: additionalProperties: false type: object properties: headers: description: >- Optional response headers. The record values will be converted to string following: Arrays' values will be mapped to String (Used when you need multiple headers with the same name). Non-arrays will be converted to String. $ref: '#/definitions/Record%3Cstring%2Cunknown%3E' status: type: number contentType: type: string body: description: >- A string representation of the body to return. Can be a base64-encoded string but please omit any leading content-type data (eg "data:image/png;base64,"). type: string additionalProperties: false required: - pattern - response scrollPage: type: boolean selector: type: string setExtraHTTPHeaders: type: object additionalProperties: type: string setJavaScriptEnabled: type: boolean url: type: string userAgent: type: object properties: userAgent: type: string userAgentMetadata: description: >- Used to specify User Agent Client Hints to emulate. See https://wicg.github.io/ua-client-hints Missing optional values will be filled in by the target with what it would normally use. $ref: '#/definitions/Protocol.Emulation.UserAgentMetadata' platform: type: string additionalProperties: false viewport: anyOf: - $ref: '#/definitions/Viewport' - type: 'null' waitForEvent: type: object properties: event: type: string timeout: type: number additionalProperties: false required: - event waitForFunction: type: object properties: fn: description: >- The function, or statement, to be evaluated in browser context type: string polling: description: >- An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values: "raf" or "mutation" type: - string - number timeout: description: >- Maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout. type: number additionalProperties: false required: - fn waitForSelector: type: object properties: hidden: type: boolean selector: type: string timeout: type: number visible: type: boolean additionalProperties: false required: - selector waitForTimeout: type: number type: object responses: '200': content: image/png: schema: type: text image/jpeg: schema: type: text text/plain: schema: type: text description: |- Response can either be a text/plain base64 encoded body or a binary stream with png/jpeg as a content-type '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /chrome/screenshot tags: - Browser REST APIs /chromium/content: post: definitions: {} description: >- A JSON-based API. Given a "url" or "html" field, runs and returns HTML content after the page has loaded and JavaScript has parsed. **Note:** This endpoint is also available at: `/content` for backwards compatibility. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: launch schema: anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: application/json: schema: properties: addScriptTag: type: array items: $ref: '#/definitions/FrameAddScriptTagOptions' addStyleTag: type: array items: $ref: '#/definitions/FrameAddStyleTagOptions' authenticate: anyOf: - $ref: '#/definitions/Credentials' - type: 'null' bestAttempt: description: >- When bestAttempt is set to true, browserless attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more. type: boolean cookies: type: array items: $ref: '#/definitions/CookieParam' emulateMediaType: type: string gotoOptions: $ref: '#/definitions/GoToOptions' html: type: string rejectRequestPattern: type: array items: type: string rejectResourceTypes: type: array items: enum: - cspviolationreport - document - eventsource - fedcm - fetch - font - image - manifest - media - other - ping - prefetch - preflight - script - signedexchange - stylesheet - texttrack - websocket - xhr type: string requestInterceptors: type: array items: description: >- An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests. type: object properties: pattern: description: >- An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests. type: string response: additionalProperties: false type: object properties: headers: description: >- Optional response headers. The record values will be converted to string following: Arrays' values will be mapped to String (Used when you need multiple headers with the same name). Non-arrays will be converted to String. $ref: '#/definitions/Record%3Cstring%2Cunknown%3E' status: type: number contentType: type: string body: description: >- A string representation of the body to return. Can be a base64-encoded string but please omit any leading content-type data (eg "data:image/png;base64,"). type: string additionalProperties: false required: - pattern - response setExtraHTTPHeaders: type: object additionalProperties: type: string setJavaScriptEnabled: description: Whether or not to allow JavaScript to run on the page. type: boolean url: type: string userAgent: type: object properties: userAgent: type: string userAgentMetadata: description: >- Used to specify User Agent Client Hints to emulate. See https://wicg.github.io/ua-client-hints Missing optional values will be filled in by the target with what it would normally use. $ref: '#/definitions/Protocol.Emulation.UserAgentMetadata' platform: type: string additionalProperties: false viewport: anyOf: - $ref: '#/definitions/Viewport' - type: 'null' waitForEvent: type: object properties: event: type: string timeout: type: number additionalProperties: false required: - event waitForFunction: type: object properties: fn: description: >- The function, or statement, to be evaluated in browser context type: string polling: description: >- An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values: "raf" or "mutation" type: - string - number timeout: description: >- Maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout. type: number additionalProperties: false required: - fn waitForSelector: type: object properties: hidden: type: boolean selector: type: string timeout: type: number visible: type: boolean additionalProperties: false required: - selector waitForTimeout: type: number type: object responses: '200': content: text/html: schema: description: |- An HTML payload of the website or HTML after JavaScript parsing and execution. type: string $schema: http://json-schema.org/draft-07/schema# description: |- An HTML payload of the website or HTML after JavaScript parsing and execution. '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /chromium/content tags: - Browser REST APIs /chromium/download: post: definitions: {} description: >- A JSON or JavaScript content-type API for returning files Chrome has downloaded during 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:** This endpoint is also available at: `/download` for backwards compatibility. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: launch schema: description: |- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: application/json: schema: $ref: '#/definitions/JSONSchema' application/javascript: schema: type: string responses: '200': content: '*/*': schema: description: >- Responses are determined by the returned value of the downloads themselves, so there isn't a static response type for this API. $schema: http://json-schema.org/draft-07/schema# description: |- Responses are determined by the returned value of the downloads themselves, so there isn't a static response type for this API. '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /chromium/download tags: - Browser REST APIs /chromium/function: post: definitions: {} description: >- A JSON or JavaScript content-type API for running puppeteer code in the browser's context. 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:** This endpoint is also available at: `/function` for backwards compatibility. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: launch schema: description: |- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: application/json: schema: $ref: '#/definitions/JSONSchema' application/javascript: schema: type: string responses: '200': content: '*/*': schema: description: >- Responses are determined by the returned value of the function itself. Binary responses (PDF's, screenshots) are returned back as binary data, and primitive JavaScript values are returned back by type (HTML data is "text/html", Objects are "application/json") $schema: http://json-schema.org/draft-07/schema# description: |- Responses are determined by the returned value of the function itself. Binary responses (PDF's, screenshots) are returned back as binary data, and primitive JavaScript values are returned back by type (HTML data is "text/html", Objects are "application/json") '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /chromium/function tags: - Browser REST APIs /chromium/performance: post: definitions: {} description: >- Run lighthouse performance audits with a supplied "url" in your JSON payload. **Note:** This endpoint is also available at: `/performance` for backwards compatibility. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: launch schema: description: |- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: application/json: schema: properties: budgets: type: array items: type: object properties: {} additionalProperties: true config: type: object properties: {} additionalProperties: true url: type: string type: object required: - url responses: '200': content: application/json: schema: description: |- The response of the lighthouse stats. Response objects are determined by the type of budgets and config in the POST JSON body type: object properties: {} additionalProperties: true $schema: http://json-schema.org/draft-07/schema# description: |- The response of the lighthouse stats. Response objects are determined by the type of budgets and config in the POST JSON body '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /chromium/performance tags: - Browser REST APIs /chromium/scrape: post: definitions: {} description: >- A JSON-based API that returns text, html, and meta-data from a given list of selectors. Debugging information is available by sending in the appropriate flags in the "debugOpts" property. Responds with an array of JSON objects. **Note:** This endpoint is also available at: `/scrape` for backwards compatibility. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: launch schema: anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: application/json: schema: properties: addScriptTag: type: array items: $ref: '#/definitions/FrameAddScriptTagOptions' addStyleTag: type: array items: $ref: '#/definitions/FrameAddStyleTagOptions' authenticate: anyOf: - $ref: '#/definitions/Credentials' - type: 'null' bestAttempt: description: >- When bestAttempt is set to true, browserless attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more. type: boolean cookies: type: array items: $ref: '#/definitions/CookieParam' debugOpts: $ref: '#/definitions/ScrapeDebugOptions' elements: type: array items: $ref: '#/definitions/ScrapeElementSelector' emulateMediaType: type: string gotoOptions: $ref: '#/definitions/GoToOptions' html: type: string rejectRequestPattern: type: array items: type: string rejectResourceTypes: type: array items: enum: - cspviolationreport - document - eventsource - fedcm - fetch - font - image - manifest - media - other - ping - prefetch - preflight - script - signedexchange - stylesheet - texttrack - websocket - xhr type: string requestInterceptors: type: array items: description: >- An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests. type: object properties: pattern: description: >- An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests. type: string response: additionalProperties: false type: object properties: headers: description: >- Optional response headers. The record values will be converted to string following: Arrays' values will be mapped to String (Used when you need multiple headers with the same name). Non-arrays will be converted to String. $ref: '#/definitions/Record%3Cstring%2Cunknown%3E' status: type: number contentType: type: string body: description: >- A string representation of the body to return. Can be a base64-encoded string but please omit any leading content-type data (eg "data:image/png;base64,"). type: string additionalProperties: false required: - pattern - response setExtraHTTPHeaders: type: object additionalProperties: type: string setJavaScriptEnabled: type: boolean url: type: string userAgent: type: object properties: userAgent: type: string userAgentMetadata: description: >- Used to specify User Agent Client Hints to emulate. See https://wicg.github.io/ua-client-hints Missing optional values will be filled in by the target with what it would normally use. $ref: '#/definitions/Protocol.Emulation.UserAgentMetadata' platform: type: string additionalProperties: false viewport: anyOf: - $ref: '#/definitions/Viewport' - type: 'null' waitForEvent: type: object properties: event: type: string timeout: type: number additionalProperties: false required: - event waitForFunction: type: object properties: fn: description: >- The function, or statement, to be evaluated in browser context type: string polling: description: >- An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values: "raf" or "mutation" type: - string - number timeout: description: >- Maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout. type: number additionalProperties: false required: - fn waitForSelector: type: object properties: hidden: type: boolean selector: type: string timeout: type: number visible: type: boolean additionalProperties: false required: - selector waitForTimeout: type: number type: object required: - elements responses: '200': content: application/json: schema: description: The JSON response body type: object properties: data: anyOf: - type: array items: type: object properties: results: type: array items: type: object properties: attributes: description: A list of HTML attributes of the element type: array items: type: object properties: name: description: >- The name of the HTML attribute for the element type: string value: description: >- The value of the HTML attribute for the element type: string additionalProperties: false required: - name - value height: description: The height the element type: number html: description: The HTML the element type: string left: description: >- The amount of pixels from the left of the page type: number text: description: The text the element type: string top: description: >- The amount of pixels from the top of the page type: number width: description: The width the element type: number additionalProperties: false required: - attributes - height - html - left - text - top - width selector: description: The DOM selector of the element type: string additionalProperties: false required: - results - selector - type: 'null' debug: description: When debugOpts options are present, results are here anyOf: - type: object properties: console: description: A list of console messages from the browser type: array items: type: string cookies: description: List of cookies for the site or null anyOf: - type: array items: $ref: '#/definitions/Cookie' - type: 'null' html: description: The HTML string of the website or null type: - 'null' - string network: type: object properties: inbound: type: array items: $ref: '#/definitions/InBoundRequest' outbound: type: array items: $ref: '#/definitions/OutBoundRequest' additionalProperties: false required: - inbound - outbound screenshot: description: A base64-encoded string of the site or null type: - 'null' - string additionalProperties: false required: - console - cookies - html - network - screenshot - type: 'null' additionalProperties: false required: - data - debug definitions: Cookie: description: Represents a cookie object. type: object properties: path: description: Cookie path. type: string expires: description: >- Cookie expiration date as the number of seconds since the UNIX epoch. Set to `-1` for session cookies type: number size: description: Cookie size. type: number secure: description: True if cookie is secure. type: boolean session: description: True in case of session cookie. type: boolean partitionKeyOpaque: description: >- True if cookie partition key is opaque. Supported only in Chrome. type: boolean name: description: Cookie name. type: string value: description: Cookie value. type: string domain: description: Cookie domain. type: string httpOnly: description: True if cookie is http-only. type: boolean sameSite: description: Cookie SameSite type. enum: - Default - Lax - None - Strict type: string priority: description: Cookie Priority. Supported only in Chrome. enum: - High - Low - Medium type: string sameParty: type: boolean sourceScheme: description: Cookie source scheme type. Supported only in Chrome. enum: - NonSecure - Secure - Unset type: string partitionKey: description: >- Cookie partition key. In Chrome, it matches the top-level site the partitioned cookie is available in. In Firefox, it matches the source origin in the {@link https://w3c.github.io/webdriver-bidi/#type-storage-PartitionKey PartitionKey}. anyOf: - $ref: '#/definitions/CookiePartitionKey' - type: string additionalProperties: false required: - domain - expires - name - path - secure - session - size - value CookiePartitionKey: description: Represents a cookie partition key in Chrome. type: object properties: sourceOrigin: description: >- The site of the top-level URL the browser was visiting at the start of the request to the endpoint that set the cookie. In Chrome, maps to the CDP's `topLevelSite` partition key. type: string hasCrossSiteAncestor: description: >- Indicates if the cookie has any ancestors that are cross-site to the topLevelSite. Supported only in Chrome. type: boolean additionalProperties: false required: - sourceOrigin InBoundRequest: type: object properties: headers: {} status: type: number url: type: string additionalProperties: false required: - headers - status - url OutBoundRequest: type: object properties: headers: {} method: type: string url: type: string additionalProperties: false required: - headers - method - url $schema: http://json-schema.org/draft-07/schema# description: The JSON response body '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /chromium/scrape tags: - Browser REST APIs /edge/content: post: definitions: {} description: >- A JSON-based API. Given a "url" or "html" field, runs and returns HTML content after the page has loaded and JavaScript has parsed. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: launch schema: anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: application/json: schema: properties: addScriptTag: type: array items: $ref: '#/definitions/FrameAddScriptTagOptions' addStyleTag: type: array items: $ref: '#/definitions/FrameAddStyleTagOptions' authenticate: anyOf: - $ref: '#/definitions/Credentials' - type: 'null' bestAttempt: description: >- When bestAttempt is set to true, browserless attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more. type: boolean cookies: type: array items: $ref: '#/definitions/CookieParam' emulateMediaType: type: string gotoOptions: $ref: '#/definitions/GoToOptions' html: type: string rejectRequestPattern: type: array items: type: string rejectResourceTypes: type: array items: enum: - cspviolationreport - document - eventsource - fedcm - fetch - font - image - manifest - media - other - ping - prefetch - preflight - script - signedexchange - stylesheet - texttrack - websocket - xhr type: string requestInterceptors: type: array items: description: >- An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests. type: object properties: pattern: description: >- An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests. type: string response: additionalProperties: false type: object properties: headers: description: >- Optional response headers. The record values will be converted to string following: Arrays' values will be mapped to String (Used when you need multiple headers with the same name). Non-arrays will be converted to String. $ref: '#/definitions/Record%3Cstring%2Cunknown%3E' status: type: number contentType: type: string body: description: >- A string representation of the body to return. Can be a base64-encoded string but please omit any leading content-type data (eg "data:image/png;base64,"). type: string additionalProperties: false required: - pattern - response setExtraHTTPHeaders: type: object additionalProperties: type: string setJavaScriptEnabled: description: Whether or not to allow JavaScript to run on the page. type: boolean url: type: string userAgent: type: object properties: userAgent: type: string userAgentMetadata: description: >- Used to specify User Agent Client Hints to emulate. See https://wicg.github.io/ua-client-hints Missing optional values will be filled in by the target with what it would normally use. $ref: '#/definitions/Protocol.Emulation.UserAgentMetadata' platform: type: string additionalProperties: false viewport: anyOf: - $ref: '#/definitions/Viewport' - type: 'null' waitForEvent: type: object properties: event: type: string timeout: type: number additionalProperties: false required: - event waitForFunction: type: object properties: fn: description: >- The function, or statement, to be evaluated in browser context type: string polling: description: >- An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values: "raf" or "mutation" type: - string - number timeout: description: >- Maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout. type: number additionalProperties: false required: - fn waitForSelector: type: object properties: hidden: type: boolean selector: type: string timeout: type: number visible: type: boolean additionalProperties: false required: - selector waitForTimeout: type: number type: object responses: '200': content: text/html: schema: description: |- An HTML payload of the website or HTML after JavaScript parsing and execution. type: string $schema: http://json-schema.org/draft-07/schema# description: |- An HTML payload of the website or HTML after JavaScript parsing and execution. '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /edge/content tags: - Browser REST APIs /edge/download: post: definitions: {} description: >- A JSON or JavaScript content-type API for returning files Chrome has downloaded during 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. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: launch schema: description: |- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: application/json: schema: $ref: '#/definitions/JSONSchema' application/javascript: schema: type: string responses: '200': content: '*/*': schema: description: >- Responses are determined by the returned value of the downloads themselves, so there isn't a static response type for this API. $schema: http://json-schema.org/draft-07/schema# description: |- Responses are determined by the returned value of the downloads themselves, so there isn't a static response type for this API. '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /edge/download tags: - Browser REST APIs /edge/function: post: definitions: {} description: >- A JSON or JavaScript content-type API for running puppeteer code in the browser's context. 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. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: launch schema: description: |- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: application/json: schema: $ref: '#/definitions/JSONSchema' application/javascript: schema: type: string responses: '200': content: '*/*': schema: description: >- Responses are determined by the returned value of the function itself. Binary responses (PDF's, screenshots) are returned back as binary data, and primitive JavaScript values are returned back by type (HTML data is "text/html", Objects are "application/json") $schema: http://json-schema.org/draft-07/schema# description: |- Responses are determined by the returned value of the function itself. Binary responses (PDF's, screenshots) are returned back as binary data, and primitive JavaScript values are returned back by type (HTML data is "text/html", Objects are "application/json") '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /edge/function tags: - Browser REST APIs /edge/pdf: post: definitions: {} description: |- A JSON-based API for getting a PDF binary from either a supplied "url" or "html" payload in your request. Many options exist for injecting cookies, request interceptors, user-agents and waiting for selectors, timers and more. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: launch schema: description: |- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: application/json: schema: properties: addScriptTag: type: array items: $ref: '#/definitions/FrameAddScriptTagOptions' addStyleTag: type: array items: $ref: '#/definitions/FrameAddStyleTagOptions' authenticate: anyOf: - $ref: '#/definitions/Credentials' - type: 'null' bestAttempt: description: >- When bestAttempt is set to true, browserless attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more. type: boolean cookies: type: array items: $ref: '#/definitions/CookieParam' emulateMediaType: type: string gotoOptions: $ref: '#/definitions/GoToOptions' html: type: string options: additionalProperties: false type: object properties: scale: description: >- Scales the rendering of the web page. Amount must be between `0.1` and `2`. type: number displayHeaderFooter: description: Whether to show the header and footer. type: boolean headerTemplate: description: >- HTML template for the print header. Should be valid HTML with the following classes used to inject values into them: - `date` formatted print date - `title` document title - `url` document location - `pageNumber` current page number - `totalPages` total pages in the document type: string footerTemplate: description: >- HTML template for the print footer. Has the same constraints and support for special classes as {@link PDFOptions.headerTemplate}. type: string printBackground: description: Set to `true` to print background graphics. type: boolean landscape: description: Whether to print in landscape orientation. type: boolean pageRanges: description: Paper ranges to print, e.g. `1-5, 8, 11-13`. type: string format: description: All the valid paper format types when printing a PDF. enum: - A0 - A1 - A2 - A3 - A4 - A5 - A6 - LEDGER - LEGAL - LETTER - Ledger - Legal - Letter - TABLOID - Tabloid - a0 - a1 - a2 - a3 - a4 - a5 - a6 - ledger - legal - letter - tabloid type: string width: description: >- Sets the width of paper. You can pass in a number or a string with a unit. type: - string - number height: description: >- Sets the height of paper. You can pass in a number or a string with a unit. type: - string - number preferCSSPageSize: description: >- Give any CSS `@page` size declared in the page priority over what is declared in the `width` or `height` or `format` option. type: boolean margin: description: Set the PDF margins. $ref: '#/definitions/PDFMargin' path: description: The path to save the file to. type: string omitBackground: description: >- Hides default white background and allows generating pdfs with transparency. type: boolean tagged: description: Generate tagged (accessible) PDF. type: boolean outline: description: Generate document outline. type: boolean timeout: description: >- Timeout in milliseconds. Pass `0` to disable timeout. The default value can be changed by using {@link Page.setDefaultTimeout} type: number waitForFonts: description: >- If true, waits for `document.fonts.ready` to resolve. This might require activating the page using {@link Page.bringToFront} if the page is in the background. type: boolean fullPage: type: boolean rejectRequestPattern: type: array items: type: string rejectResourceTypes: type: array items: enum: - cspviolationreport - document - eventsource - fedcm - fetch - font - image - manifest - media - other - ping - prefetch - preflight - script - signedexchange - stylesheet - texttrack - websocket - xhr type: string requestInterceptors: type: array items: description: >- An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests. type: object properties: pattern: description: >- An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests. type: string response: additionalProperties: false type: object properties: headers: description: >- Optional response headers. The record values will be converted to string following: Arrays' values will be mapped to String (Used when you need multiple headers with the same name). Non-arrays will be converted to String. $ref: '#/definitions/Record%3Cstring%2Cunknown%3E' status: type: number contentType: type: string body: description: >- A string representation of the body to return. Can be a base64-encoded string but please omit any leading content-type data (eg "data:image/png;base64,"). type: string additionalProperties: false required: - pattern - response setExtraHTTPHeaders: type: object additionalProperties: type: string setJavaScriptEnabled: type: boolean url: type: string userAgent: type: object properties: userAgent: type: string userAgentMetadata: description: >- Used to specify User Agent Client Hints to emulate. See https://wicg.github.io/ua-client-hints Missing optional values will be filled in by the target with what it would normally use. $ref: '#/definitions/Protocol.Emulation.UserAgentMetadata' platform: type: string additionalProperties: false viewport: anyOf: - $ref: '#/definitions/Viewport' - type: 'null' waitForEvent: type: object properties: event: type: string timeout: type: number additionalProperties: false required: - event waitForFunction: type: object properties: fn: description: >- The function, or statement, to be evaluated in browser context type: string polling: description: >- An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values: "raf" or "mutation" type: - string - number timeout: description: >- Maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout. type: number additionalProperties: false required: - fn waitForSelector: type: object properties: hidden: type: boolean selector: type: string timeout: type: number visible: type: boolean additionalProperties: false required: - selector waitForTimeout: type: number type: object responses: '200': content: application/pdf: schema: description: Responds with an application/pdf content-type and a binary PDF type: string $schema: http://json-schema.org/draft-07/schema# description: Responds with an application/pdf content-type and a binary PDF '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /edge/pdf tags: - Browser REST APIs /edge/performance: post: definitions: {} description: >- Run lighthouse performance audits with a supplied "url" in your JSON payload. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: launch schema: description: |- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: application/json: schema: properties: budgets: type: array items: type: object properties: {} additionalProperties: true config: type: object properties: {} additionalProperties: true url: type: string type: object required: - url responses: '200': content: application/json: schema: description: |- The response of the lighthouse stats. Response objects are determined by the type of budgets and config in the POST JSON body type: object properties: {} additionalProperties: true $schema: http://json-schema.org/draft-07/schema# description: |- The response of the lighthouse stats. Response objects are determined by the type of budgets and config in the POST JSON body '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /edge/performance tags: - Browser REST APIs /edge/scrape: post: definitions: {} description: >- A JSON-based API that returns text, html, and meta-data from a given list of selectors. Debugging information is available by sending in the appropriate flags in the "debugOpts" property. Responds with an array of JSON objects. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: launch schema: anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: application/json: schema: properties: addScriptTag: type: array items: $ref: '#/definitions/FrameAddScriptTagOptions' addStyleTag: type: array items: $ref: '#/definitions/FrameAddStyleTagOptions' authenticate: anyOf: - $ref: '#/definitions/Credentials' - type: 'null' bestAttempt: description: >- When bestAttempt is set to true, browserless attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more. type: boolean cookies: type: array items: $ref: '#/definitions/CookieParam' debugOpts: $ref: '#/definitions/ScrapeDebugOptions' elements: type: array items: $ref: '#/definitions/ScrapeElementSelector' emulateMediaType: type: string gotoOptions: $ref: '#/definitions/GoToOptions' html: type: string rejectRequestPattern: type: array items: type: string rejectResourceTypes: type: array items: enum: - cspviolationreport - document - eventsource - fedcm - fetch - font - image - manifest - media - other - ping - prefetch - preflight - script - signedexchange - stylesheet - texttrack - websocket - xhr type: string requestInterceptors: type: array items: description: >- An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests. type: object properties: pattern: description: >- An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests. type: string response: additionalProperties: false type: object properties: headers: description: >- Optional response headers. The record values will be converted to string following: Arrays' values will be mapped to String (Used when you need multiple headers with the same name). Non-arrays will be converted to String. $ref: '#/definitions/Record%3Cstring%2Cunknown%3E' status: type: number contentType: type: string body: description: >- A string representation of the body to return. Can be a base64-encoded string but please omit any leading content-type data (eg "data:image/png;base64,"). type: string additionalProperties: false required: - pattern - response setExtraHTTPHeaders: type: object additionalProperties: type: string setJavaScriptEnabled: type: boolean url: type: string userAgent: type: object properties: userAgent: type: string userAgentMetadata: description: >- Used to specify User Agent Client Hints to emulate. See https://wicg.github.io/ua-client-hints Missing optional values will be filled in by the target with what it would normally use. $ref: '#/definitions/Protocol.Emulation.UserAgentMetadata' platform: type: string additionalProperties: false viewport: anyOf: - $ref: '#/definitions/Viewport' - type: 'null' waitForEvent: type: object properties: event: type: string timeout: type: number additionalProperties: false required: - event waitForFunction: type: object properties: fn: description: >- The function, or statement, to be evaluated in browser context type: string polling: description: >- An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values: "raf" or "mutation" type: - string - number timeout: description: >- Maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout. type: number additionalProperties: false required: - fn waitForSelector: type: object properties: hidden: type: boolean selector: type: string timeout: type: number visible: type: boolean additionalProperties: false required: - selector waitForTimeout: type: number type: object required: - elements responses: '200': content: application/json: schema: description: The JSON response body type: object properties: data: anyOf: - type: array items: type: object properties: results: type: array items: type: object properties: attributes: description: A list of HTML attributes of the element type: array items: type: object properties: name: description: >- The name of the HTML attribute for the element type: string value: description: >- The value of the HTML attribute for the element type: string additionalProperties: false required: - name - value height: description: The height the element type: number html: description: The HTML the element type: string left: description: >- The amount of pixels from the left of the page type: number text: description: The text the element type: string top: description: >- The amount of pixels from the top of the page type: number width: description: The width the element type: number additionalProperties: false required: - attributes - height - html - left - text - top - width selector: description: The DOM selector of the element type: string additionalProperties: false required: - results - selector - type: 'null' debug: description: When debugOpts options are present, results are here anyOf: - type: object properties: console: description: A list of console messages from the browser type: array items: type: string cookies: description: List of cookies for the site or null anyOf: - type: array items: $ref: '#/definitions/Cookie' - type: 'null' html: description: The HTML string of the website or null type: - 'null' - string network: type: object properties: inbound: type: array items: $ref: '#/definitions/InBoundRequest' outbound: type: array items: $ref: '#/definitions/OutBoundRequest' additionalProperties: false required: - inbound - outbound screenshot: description: A base64-encoded string of the site or null type: - 'null' - string additionalProperties: false required: - console - cookies - html - network - screenshot - type: 'null' additionalProperties: false required: - data - debug definitions: Cookie: description: Represents a cookie object. type: object properties: path: description: Cookie path. type: string expires: description: >- Cookie expiration date as the number of seconds since the UNIX epoch. Set to `-1` for session cookies type: number size: description: Cookie size. type: number secure: description: True if cookie is secure. type: boolean session: description: True in case of session cookie. type: boolean partitionKeyOpaque: description: >- True if cookie partition key is opaque. Supported only in Chrome. type: boolean name: description: Cookie name. type: string value: description: Cookie value. type: string domain: description: Cookie domain. type: string httpOnly: description: True if cookie is http-only. type: boolean sameSite: description: Cookie SameSite type. enum: - Default - Lax - None - Strict type: string priority: description: Cookie Priority. Supported only in Chrome. enum: - High - Low - Medium type: string sameParty: type: boolean sourceScheme: description: Cookie source scheme type. Supported only in Chrome. enum: - NonSecure - Secure - Unset type: string partitionKey: description: >- Cookie partition key. In Chrome, it matches the top-level site the partitioned cookie is available in. In Firefox, it matches the source origin in the {@link https://w3c.github.io/webdriver-bidi/#type-storage-PartitionKey PartitionKey}. anyOf: - $ref: '#/definitions/CookiePartitionKey' - type: string additionalProperties: false required: - domain - expires - name - path - secure - session - size - value CookiePartitionKey: description: Represents a cookie partition key in Chrome. type: object properties: sourceOrigin: description: >- The site of the top-level URL the browser was visiting at the start of the request to the endpoint that set the cookie. In Chrome, maps to the CDP's `topLevelSite` partition key. type: string hasCrossSiteAncestor: description: >- Indicates if the cookie has any ancestors that are cross-site to the topLevelSite. Supported only in Chrome. type: boolean additionalProperties: false required: - sourceOrigin InBoundRequest: type: object properties: headers: {} status: type: number url: type: string additionalProperties: false required: - headers - status - url OutBoundRequest: type: object properties: headers: {} method: type: string url: type: string additionalProperties: false required: - headers - method - url $schema: http://json-schema.org/draft-07/schema# description: The JSON response body '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /edge/scrape tags: - Browser REST APIs /edge/screenshot: post: definitions: {} description: |- A JSON-based API for getting a screenshot binary from either a supplied "url" or "html" payload in your request. Many options exist including cookies, user-agents, setting timers and network mocks. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: launch schema: description: |- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: application/json: schema: properties: addScriptTag: type: array items: $ref: '#/definitions/FrameAddScriptTagOptions' addStyleTag: type: array items: $ref: '#/definitions/FrameAddStyleTagOptions' authenticate: anyOf: - $ref: '#/definitions/Credentials' - type: 'null' bestAttempt: description: >- When bestAttempt is set to true, browserless attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more. type: boolean cookies: type: array items: $ref: '#/definitions/CookieParam' emulateMediaType: type: string gotoOptions: $ref: '#/definitions/GoToOptions' html: type: string options: $ref: '#/definitions/ScreenshotOptions' rejectRequestPattern: type: array items: type: string rejectResourceTypes: type: array items: enum: - cspviolationreport - document - eventsource - fedcm - fetch - font - image - manifest - media - other - ping - prefetch - preflight - script - signedexchange - stylesheet - texttrack - websocket - xhr type: string requestInterceptors: type: array items: description: >- An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests. type: object properties: pattern: description: >- An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests. type: string response: additionalProperties: false type: object properties: headers: description: >- Optional response headers. The record values will be converted to string following: Arrays' values will be mapped to String (Used when you need multiple headers with the same name). Non-arrays will be converted to String. $ref: '#/definitions/Record%3Cstring%2Cunknown%3E' status: type: number contentType: type: string body: description: >- A string representation of the body to return. Can be a base64-encoded string but please omit any leading content-type data (eg "data:image/png;base64,"). type: string additionalProperties: false required: - pattern - response scrollPage: type: boolean selector: type: string setExtraHTTPHeaders: type: object additionalProperties: type: string setJavaScriptEnabled: type: boolean url: type: string userAgent: type: object properties: userAgent: type: string userAgentMetadata: description: >- Used to specify User Agent Client Hints to emulate. See https://wicg.github.io/ua-client-hints Missing optional values will be filled in by the target with what it would normally use. $ref: '#/definitions/Protocol.Emulation.UserAgentMetadata' platform: type: string additionalProperties: false viewport: anyOf: - $ref: '#/definitions/Viewport' - type: 'null' waitForEvent: type: object properties: event: type: string timeout: type: number additionalProperties: false required: - event waitForFunction: type: object properties: fn: description: >- The function, or statement, to be evaluated in browser context type: string polling: description: >- An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values: "raf" or "mutation" type: - string - number timeout: description: >- Maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout. type: number additionalProperties: false required: - fn waitForSelector: type: object properties: hidden: type: boolean selector: type: string timeout: type: number visible: type: boolean additionalProperties: false required: - selector waitForTimeout: type: number type: object responses: '200': content: image/png: schema: type: text image/jpeg: schema: type: text text/plain: schema: type: text description: |- Response can either be a text/plain base64 encoded body or a binary stream with png/jpeg as a content-type '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /edge/screenshot tags: - Browser REST APIs /active: get: definitions: {} description: >- 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. parameters: [] requestBody: content: {} responses: '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /active tags: - Management REST APIs /kill/+([0-9a-zA-Z-_]): get: definitions: {} description: Kill running sessions based on BrowserId or TrackingId. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: browserId schema: type: string - in: query name: launch schema: description: |- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - $ref: '#/definitions/BrowserServerOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: {} responses: '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /kill/+([0-9a-zA-Z-_]) tags: - Management REST APIs /meta: get: definitions: {} description: >- Returns a JSON payload of the current system versions, including the core API version. parameters: [] requestBody: content: {} responses: '200': content: application/json: schema: type: object properties: version: description: The semantic version of the Browserless API type: string chromium: description: >- The version of Chromium installed, or null if not installed type: - 'null' - string webkit: description: The version of Webkit installed, or null if not installed type: - 'null' - string firefox: description: The version of Firefox installed, or null if not installed type: - 'null' - string playwright: description: The supported version(s) of puppeteer type: array items: type: string puppeteer: description: The supported version(s) of playwright type: array items: type: string additionalProperties: false required: - chromium - firefox - playwright - puppeteer - version - webkit $schema: http://json-schema.org/draft-07/schema# '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /meta tags: - Management REST APIs /: get: definitions: {} description: >- 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: `/chromium` for backwards compatibility. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: externalProxyServer schema: description: >- 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. type: string - in: query name: integrations schema: type: string - in: query name: launch schema: description: |- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: proxy schema: description: >- The type of proxy to use, currently just 'residential' is supported type: string const: residential - in: query name: proxyCity schema: description: >- 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 type: string - in: query name: proxyCountry schema: description: >- 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 type: string - in: query name: proxyLocaleMatch schema: description: >- 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). enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: proxyPreset schema: description: >- 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") type: string - in: query name: proxyState schema: description: >- The state or province to use for the proxy, whitespace must be replaced with underscores type: string - in: query name: proxySticky schema: description: >- Whether or not to use the same IP for all requests, defaults to true enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: record schema: type: boolean - in: query name: replay schema: type: boolean - in: query name: solveCaptchas schema: type: boolean - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: {} responses: '101': description: Indicates successful WebSocket upgrade. '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: / tags: - Browser WebSocket APIs /devtools/browser/*: get: definitions: {} description: |- Connect to an already-running Chromium process with a library like puppeteer, or others, that work over chrome-devtools-protocol. Chromium must already be launched in order to not return a 404. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: launch schema: description: |- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: {} responses: '101': description: Indicates successful WebSocket upgrade. '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /devtools/browser/* tags: - Browser WebSocket APIs /chrome: get: definitions: {} description: >- Launch and connect to Chromium with a library like puppeteer or others that work over chrome-devtools-protocol. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: externalProxyServer schema: description: >- 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. type: string - in: query name: integrations schema: type: string - in: query name: launch schema: description: |- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: proxy schema: description: >- The type of proxy to use, currently just 'residential' is supported type: string const: residential - in: query name: proxyCity schema: description: >- 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 type: string - in: query name: proxyCountry schema: description: >- 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 type: string - in: query name: proxyLocaleMatch schema: description: >- 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). enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: proxyPreset schema: description: >- 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") type: string - in: query name: proxyState schema: description: >- The state or province to use for the proxy, whitespace must be replaced with underscores type: string - in: query name: proxySticky schema: description: >- Whether or not to use the same IP for all requests, defaults to true enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: record schema: type: boolean - in: query name: replay schema: type: boolean - in: query name: solveCaptchas schema: type: boolean - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: {} responses: '101': description: Indicates successful WebSocket upgrade. '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /chrome tags: - Browser WebSocket APIs /function/connect/*: get: definitions: {} description: >- Internally used by the POST /function API to connect the underlying client-side code to. Not intended for direct use but documented for completeness and to distinguish between other reconnect style calls. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: launch schema: description: |- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: {} responses: '101': description: Indicates successful WebSocket upgrade. '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /function/connect/* tags: - Browser WebSocket APIs /devtools/page/*: get: definitions: {} description: |- Connect to an existing page in Chromium with a library like chrome-remote-interface or others that work the page websocketDebugger URL. You can get this unique URL by calling the /json/list API or by finding the page's unique ID from your library of choice. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: launch schema: description: |- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: {} responses: '101': description: Indicates successful WebSocket upgrade. '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /devtools/page/* tags: - Browser WebSocket APIs /chrome/playwright: get: definitions: {} description: Connect to Chromium with any playwright style library. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: launch schema: description: |- 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. anyOf: - $ref: '#/definitions/BrowserServerOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: {} responses: '101': description: Indicates successful WebSocket upgrade. '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /chrome/playwright tags: - Browser WebSocket APIs /chromium: get: definitions: {} description: >- 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. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: launch schema: description: |- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: {} responses: '101': description: Indicates successful WebSocket upgrade. '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /chromium tags: - Browser WebSocket APIs /chromium/playwright: get: definitions: {} description: >- Connect to Chromium with any playwright style library. **Note:** This endpoint is also available at: `/playwright/chromium` for backwards compatibility. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: launch schema: description: |- 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. anyOf: - $ref: '#/definitions/BrowserServerOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: {} responses: '101': description: Indicates successful WebSocket upgrade. '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /chromium/playwright tags: - Browser WebSocket APIs /edge: get: definitions: {} description: >- Launch and connect to Chromium with a library like puppeteer or others that work over chrome-devtools-protocol. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: externalProxyServer schema: description: >- 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. type: string - in: query name: integrations schema: type: string - in: query name: launch schema: description: |- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: proxy schema: description: >- The type of proxy to use, currently just 'residential' is supported type: string const: residential - in: query name: proxyCity schema: description: >- 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 type: string - in: query name: proxyCountry schema: description: >- 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 type: string - in: query name: proxyLocaleMatch schema: description: >- 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). enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: proxyPreset schema: description: >- 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") type: string - in: query name: proxyState schema: description: >- The state or province to use for the proxy, whitespace must be replaced with underscores type: string - in: query name: proxySticky schema: description: >- Whether or not to use the same IP for all requests, defaults to true enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: record schema: type: boolean - in: query name: replay schema: type: boolean - in: query name: solveCaptchas schema: type: boolean - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: {} responses: '101': description: Indicates successful WebSocket upgrade. '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /edge tags: - Browser WebSocket APIs /edge/playwright: get: definitions: {} description: Connect to Chromium with any playwright style library. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: launch schema: description: |- 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. anyOf: - $ref: '#/definitions/BrowserServerOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: {} responses: '101': description: Indicates successful WebSocket upgrade. '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /edge/playwright tags: - Browser WebSocket APIs /firefox/playwright: get: definitions: {} description: >- Connect to Firefox with any playwright-compliant library. **Note:** This endpoint is also available at: `/playwright/firefox` for backwards compatibility. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: launch schema: description: |- 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. additionalProperties: false type: object properties: args: type: array items: type: string chromiumSandbox: type: boolean devtools: type: boolean downloadsPath: type: string headless: type: boolean ignoreDefaultArgs: anyOf: - type: array items: type: string - type: boolean proxy: type: object properties: bypass: type: string password: type: string server: type: string username: type: string additionalProperties: false required: - server timeout: type: number tracesDir: type: string firefoxUserPrefs: type: object additionalProperties: type: - string - number - boolean - in: query name: profile schema: description: >- 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. type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: {} responses: '101': description: Indicates successful WebSocket upgrade. '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /firefox/playwright tags: - Browser WebSocket APIs /webkit/playwright: get: definitions: {} description: >- Connect to Webkit with any playwright-compliant library. **Note:** This endpoint is also available at: `/playwright/webkit` for backwards compatibility. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: launch schema: description: |- 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. anyOf: - $ref: '#/definitions/BrowserServerOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: {} responses: '101': description: Indicates successful WebSocket upgrade. '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /webkit/playwright tags: - Browser WebSocket APIs /browser/*: delete: definitions: {} description: >- Terminates a browser instance by browserId. The browser must belong to the authenticated user. parameters: [] requestBody: content: {} responses: '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /browser/* tags: - Management REST APIs - Browser REST APIs /chrome/export: post: definitions: {} description: >- Exports a webpage to a PDF or image format. This API is useful for generating reports, screenshots, or PDFs of web pages. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: externalProxyServer schema: description: >- 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. type: string - in: query name: launch schema: description: >- Launch options for the browser, either as a JSON object or a JSON string. Includes options like `headless`, `args`, `defaultViewport`, etc. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: proxy schema: description: >- The type of proxy to use, currently just 'residential' is supported type: string const: residential - in: query name: proxyCity schema: description: >- 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 type: string - in: query name: proxyCountry schema: description: >- 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 type: string - in: query name: proxyLocaleMatch schema: description: >- 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). enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: proxyPreset schema: description: >- 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") type: string - in: query name: proxyState schema: description: >- The state or province to use for the proxy, whitespace must be replaced with underscores type: string - in: query name: proxySticky schema: description: >- Whether or not to use the same IP for all requests, defaults to true enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: application/json: schema: properties: bestAttempt: description: >- 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. type: boolean url: description: The URL of the site you want to archive. type: string gotoOptions: $ref: '#/definitions/GoToOptions' description: >- An optional goto parameter object for considering when the page is done loading. waitForEvent: description: >- Options for waiting for a specific event to be fired on the page. type: object properties: event: type: string timeout: type: number additionalProperties: false required: - event waitForFunction: description: Options for waiting for a JavaScript function to execute. type: object properties: fn: description: >- The function, or statement, to be evaluated in browser context type: string polling: description: >- An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values: "raf" or "mutation" type: - string - number timeout: description: >- Maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout. type: number additionalProperties: false required: - fn waitForSelector: description: >- Options for waiting for a specific CSS selector to appear on the page. type: object properties: hidden: type: boolean selector: type: string timeout: type: number visible: type: boolean additionalProperties: false required: - selector waitForTimeout: description: >- The amount of time in milliseconds to wait before proceeding. type: number headers: description: >- An object containing additional HTTP headers to send with every request. type: object additionalProperties: type: string includeResources: description: >- 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). type: boolean type: object required: - url responses: '200': content: application/json: schema: type: object properties: html: description: The HTML content of the page. type: string additionalProperties: false required: - html $schema: http://json-schema.org/draft-07/schema# '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /chrome/export tags: - Browser REST APIs /chrome/unblock: post: definitions: {} description: |- 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". parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: externalProxyServer schema: description: >- 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. type: string - in: query name: launch schema: description: >- Launch options for the browser, either as a JSON object or a JSON string. Includes options like `headless`, `args`, `defaultViewport`, etc. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: proxy schema: description: >- The type of proxy to use, currently just 'residential' is supported type: string const: residential - in: query name: proxyCity schema: description: >- 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 type: string - in: query name: proxyCountry schema: description: >- 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 type: string - in: query name: proxyLocaleMatch schema: description: >- 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). enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: proxyPreset schema: description: >- 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") type: string - in: query name: proxyState schema: description: >- The state or province to use for the proxy, whitespace must be replaced with underscores type: string - in: query name: proxySticky schema: description: >- Whether or not to use the same IP for all requests, defaults to true enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: application/json: schema: properties: bestAttempt: description: >- 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. type: boolean url: description: The URL of the site you want to unblock. type: string browserWSEndpoint: description: >- Whether or not to keep the underlying browser alive and around for future reconnects. Defaults to false. type: boolean cookies: description: >- Whether or not to to return cookies for the site, defaults to true. type: boolean content: description: >- Whether or not to to return content for the site, defaults to true. type: boolean screenshot: description: >- Whether or not to to return a full-page screenshot for the site, defaults to true. type: boolean ttl: description: |- 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). type: number gotoOptions: $ref: '#/definitions/GoToOptions' description: >- An optional goto parameter object for considering when the page is done loading. waitForEvent: description: >- Options for waiting for a specific event to be fired on the page. type: object properties: event: type: string timeout: type: number additionalProperties: false required: - event waitForFunction: description: Options for waiting for a JavaScript function to execute. type: object properties: fn: description: >- The function, or statement, to be evaluated in browser context type: string polling: description: >- An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values: "raf" or "mutation" type: - string - number timeout: description: >- Maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout. type: number additionalProperties: false required: - fn waitForSelector: description: >- Options for waiting for a specific CSS selector to appear on the page. type: object properties: hidden: type: boolean selector: type: string timeout: type: number visible: type: boolean additionalProperties: false required: - selector waitForTimeout: description: >- The amount of time in milliseconds to wait before proceeding. type: number type: object required: - url responses: '200': content: application/json: schema: type: object properties: cookies: description: >- A list of cookies which can be used for new connections or for usage elsewhere. Value is "null" when the request body specifies cookies: false. type: array items: $ref: '#/definitions/Cookie' content: description: >- The HTML content of the page once it is passed bot detection. Value is "null" when the request body specifies cookies: false. type: string browserWSEndpoint: description: >- The browserWSEndpoint of the response when the POST body contains a browserWSEndpoint: true property type: string ttl: description: >- The time the browser will remain alive until it is shutdown. Zero when browserWSEndpoint: false is set in the request payload. The limit is 30000 or 30 seconds, which is the maximum allowed time. type: number screenshot: description: A base64 encoded JPEG of the of the final site page. type: string additionalProperties: false required: - browserWSEndpoint - content - cookies - screenshot - ttl definitions: Cookie: description: Represents a cookie object. type: object properties: path: description: Cookie path. type: string expires: description: >- Cookie expiration date as the number of seconds since the UNIX epoch. Set to `-1` for session cookies type: number size: description: Cookie size. type: number secure: description: True if cookie is secure. type: boolean session: description: True in case of session cookie. type: boolean partitionKeyOpaque: description: >- True if cookie partition key is opaque. Supported only in Chrome. type: boolean name: description: Cookie name. type: string value: description: Cookie value. type: string domain: description: Cookie domain. type: string httpOnly: description: True if cookie is http-only. type: boolean sameSite: $ref: '#/definitions/CookieSameSite' description: Cookie SameSite type. priority: $ref: '#/definitions/CookiePriority' description: Cookie Priority. Supported only in Chrome. sameParty: type: boolean sourceScheme: $ref: '#/definitions/CookieSourceScheme' description: Cookie source scheme type. Supported only in Chrome. partitionKey: description: >- Cookie partition key. In Chrome, it matches the top-level site the partitioned cookie is available in. In Firefox, it matches the source origin in the {@link https://w3c.github.io/webdriver-bidi/#type-storage-PartitionKey PartitionKey}. anyOf: - $ref: '#/definitions/CookiePartitionKey' - type: string additionalProperties: false required: - domain - expires - name - path - secure - session - size - value CookieSameSite: description: |- Represents the cookie's 'SameSite' status: https://tools.ietf.org/html/draft-west-first-party-cookies enum: - Default - Lax - None - Strict type: string CookiePriority: description: |- Represents the cookie's 'Priority' status: https://tools.ietf.org/html/draft-west-cookie-priority-00 enum: - High - Low - Medium type: string CookieSourceScheme: description: >- Represents the source scheme of the origin that originally set the cookie. A value of "Unset" allows protocol clients to emulate legacy cookie scope for the scheme. This is a temporary ability and it will be removed in the future. enum: - NonSecure - Secure - Unset type: string CookiePartitionKey: description: Represents a cookie partition key in Chrome. type: object properties: sourceOrigin: description: >- The site of the top-level URL the browser was visiting at the start of the request to the endpoint that set the cookie. In Chrome, maps to the CDP's `topLevelSite` partition key. type: string hasCrossSiteAncestor: description: >- Indicates if the cookie has any ancestors that are cross-site to the topLevelSite. Supported only in Chrome. type: boolean additionalProperties: false required: - sourceOrigin $schema: http://json-schema.org/draft-07/schema# '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /chrome/unblock tags: - Browser REST APIs /chromium/export: post: definitions: {} description: >- Exports a webpage to a PDF or image format. This API is useful for generating reports, screenshots, or PDFs of web pages. **Note:** This endpoint is also available at: `/export` for backwards compatibility. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: externalProxyServer schema: description: >- 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. type: string - in: query name: launch schema: description: >- Launch options for the browser, either as a JSON object or a JSON string. Includes options like `headless`, `args`, `defaultViewport`, etc. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: proxy schema: description: >- The type of proxy to use, currently just 'residential' is supported type: string const: residential - in: query name: proxyCity schema: description: >- 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 type: string - in: query name: proxyCountry schema: description: >- 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 type: string - in: query name: proxyLocaleMatch schema: description: >- 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). enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: proxyPreset schema: description: >- 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") type: string - in: query name: proxyState schema: description: >- The state or province to use for the proxy, whitespace must be replaced with underscores type: string - in: query name: proxySticky schema: description: >- Whether or not to use the same IP for all requests, defaults to true enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: application/json: schema: properties: bestAttempt: description: >- 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. type: boolean url: description: The URL of the site you want to archive. type: string gotoOptions: $ref: '#/definitions/GoToOptions' description: >- An optional goto parameter object for considering when the page is done loading. waitForEvent: description: >- Options for waiting for a specific event to be fired on the page. type: object properties: event: type: string timeout: type: number additionalProperties: false required: - event waitForFunction: description: Options for waiting for a JavaScript function to execute. type: object properties: fn: description: >- The function, or statement, to be evaluated in browser context type: string polling: description: >- An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values: "raf" or "mutation" type: - string - number timeout: description: >- Maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout. type: number additionalProperties: false required: - fn waitForSelector: description: >- Options for waiting for a specific CSS selector to appear on the page. type: object properties: hidden: type: boolean selector: type: string timeout: type: number visible: type: boolean additionalProperties: false required: - selector waitForTimeout: description: >- The amount of time in milliseconds to wait before proceeding. type: number headers: description: >- An object containing additional HTTP headers to send with every request. type: object additionalProperties: type: string includeResources: description: >- 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). type: boolean type: object required: - url responses: '200': content: application/json: schema: type: object properties: html: description: The HTML content of the page. type: string additionalProperties: false required: - html $schema: http://json-schema.org/draft-07/schema# '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /chromium/export tags: - Browser REST APIs /unblock: post: definitions: {} description: >- 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:** This endpoint is also available at: `/chromium/unblock` for backwards compatibility. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: externalProxyServer schema: description: >- 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. type: string - in: query name: launch schema: description: >- Launch options for the browser, either as a JSON object or a JSON string. Includes options like `headless`, `args`, `defaultViewport`, etc. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: proxy schema: description: >- The type of proxy to use, currently just 'residential' is supported type: string const: residential - in: query name: proxyCity schema: description: >- 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 type: string - in: query name: proxyCountry schema: description: >- 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 type: string - in: query name: proxyLocaleMatch schema: description: >- 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). enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: proxyPreset schema: description: >- 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") type: string - in: query name: proxyState schema: description: >- The state or province to use for the proxy, whitespace must be replaced with underscores type: string - in: query name: proxySticky schema: description: >- Whether or not to use the same IP for all requests, defaults to true enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: application/json: schema: properties: bestAttempt: description: >- 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. type: boolean url: description: The URL of the site you want to unblock. type: string browserWSEndpoint: description: >- Whether or not to keep the underlying browser alive and around for future reconnects. Defaults to false. type: boolean cookies: description: >- Whether or not to to return cookies for the site, defaults to true. type: boolean content: description: >- Whether or not to to return content for the site, defaults to true. type: boolean screenshot: description: >- Whether or not to to return a full-page screenshot for the site, defaults to true. type: boolean ttl: description: |- 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). type: number gotoOptions: $ref: '#/definitions/GoToOptions' description: >- An optional goto parameter object for considering when the page is done loading. waitForEvent: description: >- Options for waiting for a specific event to be fired on the page. type: object properties: event: type: string timeout: type: number additionalProperties: false required: - event waitForFunction: description: Options for waiting for a JavaScript function to execute. type: object properties: fn: description: >- The function, or statement, to be evaluated in browser context type: string polling: description: >- An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values: "raf" or "mutation" type: - string - number timeout: description: >- Maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout. type: number additionalProperties: false required: - fn waitForSelector: description: >- Options for waiting for a specific CSS selector to appear on the page. type: object properties: hidden: type: boolean selector: type: string timeout: type: number visible: type: boolean additionalProperties: false required: - selector waitForTimeout: description: >- The amount of time in milliseconds to wait before proceeding. type: number type: object required: - url responses: '200': content: application/json: schema: type: object properties: cookies: description: >- A list of cookies which can be used for new connections or for usage elsewhere. Value is "null" when the request body specifies cookies: false. type: array items: $ref: '#/definitions/Cookie' content: description: >- The HTML content of the page once it is passed bot detection. Value is "null" when the request body specifies cookies: false. type: string browserWSEndpoint: description: >- The browserWSEndpoint of the response when the POST body contains a browserWSEndpoint: true property type: string ttl: description: >- The time the browser will remain alive until it is shutdown. Zero when browserWSEndpoint: false is set in the request payload. The limit is 30000 or 30 seconds, which is the maximum allowed time. type: number screenshot: description: A base64 encoded JPEG of the of the final site page. type: string additionalProperties: false required: - browserWSEndpoint - content - cookies - screenshot - ttl definitions: Cookie: description: Represents a cookie object. type: object properties: path: description: Cookie path. type: string expires: description: >- Cookie expiration date as the number of seconds since the UNIX epoch. Set to `-1` for session cookies type: number size: description: Cookie size. type: number secure: description: True if cookie is secure. type: boolean session: description: True in case of session cookie. type: boolean partitionKeyOpaque: description: >- True if cookie partition key is opaque. Supported only in Chrome. type: boolean name: description: Cookie name. type: string value: description: Cookie value. type: string domain: description: Cookie domain. type: string httpOnly: description: True if cookie is http-only. type: boolean sameSite: $ref: '#/definitions/CookieSameSite' description: Cookie SameSite type. priority: $ref: '#/definitions/CookiePriority' description: Cookie Priority. Supported only in Chrome. sameParty: type: boolean sourceScheme: $ref: '#/definitions/CookieSourceScheme' description: Cookie source scheme type. Supported only in Chrome. partitionKey: description: >- Cookie partition key. In Chrome, it matches the top-level site the partitioned cookie is available in. In Firefox, it matches the source origin in the {@link https://w3c.github.io/webdriver-bidi/#type-storage-PartitionKey PartitionKey}. anyOf: - $ref: '#/definitions/CookiePartitionKey' - type: string additionalProperties: false required: - domain - expires - name - path - secure - session - size - value CookieSameSite: description: |- Represents the cookie's 'SameSite' status: https://tools.ietf.org/html/draft-west-first-party-cookies enum: - Default - Lax - None - Strict type: string CookiePriority: description: |- Represents the cookie's 'Priority' status: https://tools.ietf.org/html/draft-west-cookie-priority-00 enum: - High - Low - Medium type: string CookieSourceScheme: description: >- Represents the source scheme of the origin that originally set the cookie. A value of "Unset" allows protocol clients to emulate legacy cookie scope for the scheme. This is a temporary ability and it will be removed in the future. enum: - NonSecure - Secure - Unset type: string CookiePartitionKey: description: Represents a cookie partition key in Chrome. type: object properties: sourceOrigin: description: >- The site of the top-level URL the browser was visiting at the start of the request to the endpoint that set the cookie. In Chrome, maps to the CDP's `topLevelSite` partition key. type: string hasCrossSiteAncestor: description: >- Indicates if the cookie has any ancestors that are cross-site to the topLevelSite. Supported only in Chrome. type: boolean additionalProperties: false required: - sourceOrigin $schema: http://json-schema.org/draft-07/schema# '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /unblock tags: - Browser REST APIs /proxy/cities: get: definitions: {} description: >- 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. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: country schema: description: >- Optional two-letter country code to filter cities by country (e.g., 'US', 'GB', 'DE'). type: string - in: query name: launch schema: description: |- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - $ref: '#/definitions/BrowserServerOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: {} responses: '200': content: application/json: schema: type: object properties: countries: description: Countries with their available cities type: array items: type: object properties: code: description: Two-letter country code type: string cities: description: List of city names in this country type: array items: type: string additionalProperties: false required: - cities - code totalCountries: description: Total number of countries type: number totalCities: description: Total number of cities across all countries type: number filters: description: Applied filters type: object properties: country: type: string additionalProperties: false additionalProperties: false required: - countries - filters - totalCities - totalCountries $schema: http://json-schema.org/draft-07/schema# '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /proxy/cities tags: - Management REST APIs - Browser REST APIs /map: post: definitions: {} description: |- 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. parameters: - in: query name: timeout schema: description: Request timeout in milliseconds type: number - in: query name: token schema: description: API authentication token type: string requestBody: content: application/json: schema: properties: url: description: The base URL to start mapping from (required) type: string search: description: Search query to order results by relevance type: string limit: description: 'Maximum number of links to return (default: 5000, max: 5000)' type: number timeout: description: Request timeout in milliseconds type: number sitemap: description: >- Controls sitemap behavior: "include" (default), "skip", "only" enum: - include - only - skip type: string includeSubdomains: description: 'Whether to include URLs from subdomains (default: true)' type: boolean ignoreQueryParameters: description: 'Exclude URLs with query parameters (default: true)' type: boolean location: description: Geo-targeting settings type: object properties: country: description: >- ISO 3166-1 alpha-2 country code for proxy routing (e.g., `"us"`, `"gb"`, `"de"`). Defaults to `"us"`. type: string languages: description: >- Preferred language codes for the request (e.g., `["en", "fr"]`). type: array items: type: string additionalProperties: false type: object required: - url responses: '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /map tags: - Browser REST APIs /pdf: post: definitions: {} description: >- A JSON-based API for getting a PDF binary from either a supplied "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 endpoint is also available at: `/chromium/pdf` for backwards compatibility. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: externalProxyServer schema: description: >- 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. type: string - in: query name: launch schema: description: >- Launch options for the browser, either as a JSON object or a JSON string. Includes options like `headless`, `args`, `defaultViewport`, etc. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: proxy schema: description: >- The type of proxy to use, currently just 'residential' is supported type: string const: residential - in: query name: proxyCity schema: description: >- 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 type: string - in: query name: proxyCountry schema: description: >- 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 type: string - in: query name: proxyLocaleMatch schema: description: >- 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). enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: proxyPreset schema: description: >- 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") type: string - in: query name: proxyState schema: description: >- The state or province to use for the proxy, whitespace must be replaced with underscores type: string - in: query name: proxySticky schema: description: >- Whether or not to use the same IP for all requests, defaults to true enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: application/json: schema: properties: blockConsentModals: description: >- Whether to automatically block cookie consent modals and popups. type: boolean options: description: >- PDF generation options based on Puppeteer's PDFOptions interface. Includes properties like `format`, `margin`, `printBackground`, `landscape`, etc. additionalProperties: false type: object properties: scale: description: >- Scales the rendering of the web page. Amount must be between `0.1` and `2`. type: number displayHeaderFooter: description: Whether to show the header and footer. type: boolean headerTemplate: description: >- HTML template for the print header. Should be valid HTML with the following classes used to inject values into them: - `date` formatted print date - `title` document title - `url` document location - `pageNumber` current page number - `totalPages` total pages in the document type: string footerTemplate: description: >- HTML template for the print footer. Has the same constraints and support for special classes as {@link PDFOptions.headerTemplate}. type: string printBackground: description: Set to `true` to print background graphics. type: boolean landscape: description: Whether to print in landscape orientation. type: boolean pageRanges: description: Paper ranges to print, e.g. `1-5, 8, 11-13`. type: string format: $ref: '#/definitions/PaperFormat' width: description: >- Sets the width of paper. You can pass in a number or a string with a unit. type: - string - number height: description: >- Sets the height of paper. You can pass in a number or a string with a unit. type: - string - number preferCSSPageSize: description: >- Give any CSS `@page` size declared in the page priority over what is declared in the `width` or `height` or `format` option. type: boolean margin: $ref: '#/definitions/PDFMargin' description: Set the PDF margins. path: description: The path to save the file to. type: string omitBackground: description: >- Hides default white background and allows generating pdfs with transparency. type: boolean tagged: description: Generate tagged (accessible) PDF. type: boolean outline: description: Generate document outline. type: boolean timeout: description: >- Timeout in milliseconds. Pass `0` to disable timeout. The default value can be changed by using {@link Page.setDefaultTimeout} type: number waitForFonts: description: >- If true, waits for `document.fonts.ready` to resolve. This might require activating the page using {@link Page.bringToFront} if the page is in the background. type: boolean fullPage: type: boolean addScriptTag: description: >- An array of script tags to add to the page before performing actions. Each object can contain either a `url`, or a `content` property. type: array items: $ref: '#/definitions/FrameAddScriptTagOptions' addStyleTag: description: >- An array of style tags to add to the page before performing actions. Each object can contain either a `url`, or a `content` property. type: array items: $ref: '#/definitions/FrameAddStyleTagOptions' authenticate: $ref: '#/definitions/Credentials' description: >- Credentials for HTTP authentication. Contains `username` and `password` properties. bestAttempt: description: >- 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. type: boolean cookies: description: >- An array of cookies to set on the page before navigation. Each cookie object should contain at least `name` and `value` properties. type: array items: $ref: '#/definitions/CookieParam' emulateMediaType: description: >- Changes the CSS media type of the page. Accepts values like "screen" or "print". type: string gotoOptions: $ref: '#/definitions/GoToOptions' description: >- Options to configure the page navigation, such as `timeout` and `waitUntil`. html: description: >- HTML content to set as the page content instead of navigating to a URL. type: string rejectRequestPattern: description: >- An array of patterns to match against request URLs for automatic rejection. Requests matching these patterns will be aborted. type: array items: type: string rejectResourceTypes: description: >- An array of resource types to reject during page load. Common types include "image", "stylesheet", "font", "script", etc. type: array items: enum: - cspviolationreport - document - eventsource - fedcm - fetch - font - image - manifest - media - other - ping - prefetch - preflight - script - signedexchange - stylesheet - texttrack - websocket - xhr type: string requestInterceptors: description: >- 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. type: array items: description: >- An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests. type: object properties: pattern: description: >- An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests. type: string response: additionalProperties: false type: object properties: headers: $ref: '#/definitions/Record%3Cstring%2Cunknown%3E' description: >- Optional response headers. The record values will be converted to string following: Arrays' values will be mapped to String (Used when you need multiple headers with the same name). Non-arrays will be converted to String. status: type: number contentType: type: string body: description: >- A string representation of the body to return. Can be a base64-encoded string but please omit any leading content-type data (eg "data:image/png;base64,"). type: string additionalProperties: false required: - pattern - response setExtraHTTPHeaders: description: >- An object containing additional HTTP headers to send with every request. type: object additionalProperties: type: string setJavaScriptEnabled: description: Whether or not to allow JavaScript to run on the page. type: boolean url: description: The URL to navigate to before performing actions. type: string userAgent: description: The user agent string to use for the page. type: object properties: userAgent: type: string userAgentMetadata: $ref: '#/definitions/Protocol.Emulation.UserAgentMetadata' platform: type: string additionalProperties: false viewport: $ref: '#/definitions/Viewport' description: >- The viewport dimensions and settings for the page. Includes properties like `width`, `height`, `deviceScaleFactor`, etc. waitForEvent: description: >- Options for waiting for a specific event to be fired on the page. type: object properties: event: type: string timeout: type: number additionalProperties: false required: - event waitForFunction: description: Options for waiting for a JavaScript function to execute. type: object properties: fn: description: >- The function, or statement, to be evaluated in browser context type: string polling: description: >- An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values: "raf" or "mutation" type: - string - number timeout: description: >- Maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout. type: number additionalProperties: false required: - fn waitForSelector: description: >- Options for waiting for a specific CSS selector to appear on the page. type: object properties: hidden: type: boolean selector: type: string timeout: type: number visible: type: boolean additionalProperties: false required: - selector waitForTimeout: description: >- The amount of time in milliseconds to wait before proceeding. type: number type: object responses: '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /pdf tags: - Browser REST APIs /screenshot: post: definitions: {} description: >- A JSON-based API for getting a screenshot binary from either a supplied "url" or "html" payload in your request. Many options exist including cookies, user-agents, setting timers and network mocks. **Note:** This endpoint is also available at: `/chromium/screenshot` for backwards compatibility. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: externalProxyServer schema: description: >- 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. type: string - in: query name: launch schema: description: >- Launch options for the browser, either as a JSON object or a JSON string. Includes options like `headless`, `args`, `defaultViewport`, etc. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: proxy schema: description: >- The type of proxy to use, currently just 'residential' is supported type: string const: residential - in: query name: proxyCity schema: description: >- 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 type: string - in: query name: proxyCountry schema: description: >- 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 type: string - in: query name: proxyLocaleMatch schema: description: >- 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). enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: proxyPreset schema: description: >- 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") type: string - in: query name: proxyState schema: description: >- The state or province to use for the proxy, whitespace must be replaced with underscores type: string - in: query name: proxySticky schema: description: >- Whether or not to use the same IP for all requests, defaults to true enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: application/json: schema: properties: blockConsentModals: description: >- Whether to automatically block cookie consent modals and popups. type: boolean options: $ref: '#/definitions/ScreenshotOptions' description: >- Screenshot options based on Puppeteer's ScreenshotOptions interface. Includes properties like `type`, `quality`, `fullPage`, `clip`, etc. addScriptTag: description: >- An array of script tags to add to the page before performing actions. Each object can contain either a `url`, or a `content` property. type: array items: $ref: '#/definitions/FrameAddScriptTagOptions' addStyleTag: description: >- An array of style tags to add to the page before performing actions. Each object can contain either a `url`, or a `content` property. type: array items: $ref: '#/definitions/FrameAddStyleTagOptions' authenticate: $ref: '#/definitions/Credentials' description: >- Credentials for HTTP authentication. Contains `username` and `password` properties. bestAttempt: description: >- 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. type: boolean cookies: description: >- An array of cookies to set on the page before navigation. Each cookie object should contain at least `name` and `value` properties. type: array items: $ref: '#/definitions/CookieParam' emulateMediaType: description: >- Changes the CSS media type of the page. Accepts values like "screen" or "print". type: string gotoOptions: $ref: '#/definitions/GoToOptions' description: >- Options to configure the page navigation, such as `timeout` and `waitUntil`. html: description: >- HTML content to set as the page content instead of navigating to a URL. type: string rejectRequestPattern: description: >- An array of patterns to match against request URLs for automatic rejection. Requests matching these patterns will be aborted. type: array items: type: string rejectResourceTypes: description: >- An array of resource types to reject during page load. Common types include "image", "stylesheet", "font", "script", etc. type: array items: enum: - cspviolationreport - document - eventsource - fedcm - fetch - font - image - manifest - media - other - ping - prefetch - preflight - script - signedexchange - stylesheet - texttrack - websocket - xhr type: string requestInterceptors: description: >- 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. type: array items: description: >- An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests. type: object properties: pattern: description: >- An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests. type: string response: additionalProperties: false type: object properties: headers: $ref: '#/definitions/Record%3Cstring%2Cunknown%3E' description: >- Optional response headers. The record values will be converted to string following: Arrays' values will be mapped to String (Used when you need multiple headers with the same name). Non-arrays will be converted to String. status: type: number contentType: type: string body: description: >- A string representation of the body to return. Can be a base64-encoded string but please omit any leading content-type data (eg "data:image/png;base64,"). type: string additionalProperties: false required: - pattern - response setExtraHTTPHeaders: description: >- An object containing additional HTTP headers to send with every request. type: object additionalProperties: type: string setJavaScriptEnabled: description: Whether or not to allow JavaScript to run on the page. type: boolean url: description: The URL to navigate to before performing actions. type: string userAgent: description: The user agent string to use for the page. type: object properties: userAgent: type: string userAgentMetadata: $ref: '#/definitions/Protocol.Emulation.UserAgentMetadata' platform: type: string additionalProperties: false viewport: $ref: '#/definitions/Viewport' description: >- The viewport dimensions and settings for the page. Includes properties like `width`, `height`, `deviceScaleFactor`, etc. waitForEvent: description: >- Options for waiting for a specific event to be fired on the page. type: object properties: event: type: string timeout: type: number additionalProperties: false required: - event waitForFunction: description: Options for waiting for a JavaScript function to execute. type: object properties: fn: description: >- The function, or statement, to be evaluated in browser context type: string polling: description: >- An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values: "raf" or "mutation" type: - string - number timeout: description: >- Maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout. type: number additionalProperties: false required: - fn waitForSelector: description: >- Options for waiting for a specific CSS selector to appear on the page. type: object properties: hidden: type: boolean selector: type: string timeout: type: number visible: type: boolean additionalProperties: false required: - selector waitForTimeout: description: >- The amount of time in milliseconds to wait before proceeding. type: number scrollPage: description: >- Whether to scroll through the entire page before capturing content. Useful for triggering lazy-loaded content. type: boolean selector: description: >- A CSS selector to target a specific element instead of the full page. type: string type: object responses: '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /screenshot tags: - Browser REST APIs /search: post: definitions: {} description: >- 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). parameters: - in: query name: timeout schema: description: The timeout for the search operation in milliseconds. type: number - in: query name: token schema: description: The API token for authenticating the request. type: string requestBody: content: application/json: schema: properties: query: description: The search query string. type: string limit: description: >- Maximum number of results per source. Defaults to `10`. Capped by plan limits. type: number lang: description: >- Language code for results (e.g., `"en"`, `"es"`, `"de"`). Defaults to `"en"`. type: string location: description: >- City or region to narrow geo-targeting (e.g., `"San Francisco"`). Use with `country`. type: string country: description: >- ISO 3166-1 alpha-2 country code for geo-targeted results (e.g., `"us"`, `"gb"`, `"de"`). type: string tbs: $ref: '#/definitions/TimeBasedOptions' description: >- Time-based filter. Accepts `"day"`, `"week"`, `"month"`, `"year"`, or raw Google TBS syntax (`"qdr:d"`, `"qdr:w"`, `"qdr:m"`, `"qdr:y"`). categories: description: >- Content category filters. Restricts results to `"github"` repos, `"research"` papers, or `"pdf"` documents. type: array items: enum: - github - pdf - research type: string sources: description: >- Sources to search. Defaults to `["web"]`. Also supports `"news"` and `"images"`. type: array items: enum: - images - news - web type: string timeout: description: Request timeout in milliseconds. type: number scrapeOptions: description: >- When provided, fetches and processes each result URL into structured content. type: object properties: formats: type: array items: enum: - html - links - markdown - screenshot type: string stripNonContentTags: type: boolean onlyMainContent: type: boolean removeBase64Images: type: boolean includeTags: type: array items: type: string excludeTags: type: array items: type: string additionalProperties: false required: - formats type: object required: - query responses: '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /search tags: - Browser REST APIs /session: post: definitions: {} description: >- 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. parameters: [] requestBody: content: application/json: schema: properties: ttl: description: >- 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. type: number processKeepAlive: description: >- 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). type: number stealth: description: >- Whether or not to enable advanced stealth mode. Defaults to false. type: boolean blockAds: description: Whether or not to enable ad-blocking. Defaults to false. type: boolean headless: description: |- Whether the browser should be launched in headless mode. Ignored if `stealth` is true, defaults to "true". type: boolean args: description: |- An array of command-line arguments to pass to the browser. Defaults to an empty array. type: array items: type: string browser: description: >- The type of browser to use for the session. 'stealth' uses the Brave browser with advanced anti-detection. Defaults to 'chromium'. enum: - chrome - chromium - stealth type: string url: description: >- 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. type: string proxy: description: >- Proxy Parameters for the session if desired. If not specified, the session will use the default network settings. type: object properties: type: description: >- The type of proxy to use, currently only 'residential' is supported. type: string const: residential sticky: description: >- Whether or not to use the same IP address for all proxied requests. Defaults to true type: boolean country: description: >- The country to proxy through. Defaults to 'us' or United States type: string city: description: The city to proxy through. type: string state: description: The state to proxy through. type: string preset: description: >- Preset code for website-specific proxy configurations (e.g., 'px_gov01' for government sites) type: string additionalProperties: false replay: description: >- Whether to enable session recording for replay. When true, the session will be recorded and can be replayed later. type: boolean extensions: description: >- 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. type: array items: type: string profile: description: >- 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. type: string type: object required: - ttl responses: '200': content: application/json: schema: type: object properties: id: description: The ID of the session type: string connect: description: >- The fully-qualified URL to connect CDP-based libraries to the session type: string ttl: description: The total time of life in milliseconds type: number stop: description: >- The fully qualified URL to stop and remove the session with a DELETE method. type: string browserQL: description: >- The fully-qualified URL to run BrowserQL queries against the session type: string cloudEndpointId: description: >- The encrypted cloud endpoint ID for the session when ran in the browserless cloud. This is a cloud-specific property and is only present when using browserless cloud. type: string additionalProperties: false required: - browserQL - cloudEndpointId - connect - id - stop - ttl $schema: http://json-schema.org/draft-07/schema# '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /session tags: - Management REST APIs - Browser REST APIs /session/*: delete: definitions: {} description: >- 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 parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: force schema: description: >- Whether to force the deletion of the session even if it has active connections. Defaults to false. type: boolean - in: query name: launch schema: description: |- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - $ref: '#/definitions/BrowserServerOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: {} responses: '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /session/* tags: - Management REST APIs - Browser REST APIs /smart-scrape: post: definitions: {} description: >- Intelligently scrapes a URL using cascading strategies (HTTP fetch, proxy, headless browser, etc). parameters: - in: query name: profile schema: description: >- 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. type: string - in: query name: timeout schema: description: The timeout for the scrape operation in milliseconds type: number - in: query name: token schema: description: >- 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. type: string requestBody: content: application/json: schema: properties: url: description: The URL to scrape. Must be an http or https URL. type: string formats: description: >- 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 default: - html type: array items: enum: - html - links - markdown - pdf - screenshot type: string type: object required: - url responses: '200': content: application/json: schema: description: An HTML payload of the scraped page content. type: object properties: ok: description: Whether the scrape was successful or not. type: boolean statusCode: description: >- The HTTP status code of the response, or null if the scrape failed before an HTTP response was received (e.g. due to a network error or captcha). type: number content: description: >- The content of the scraped page. This will be a string for HTML content, or a parsed JSON object if the content type is JSON. Will be null if the scrape was unsuccessful. anyOf: - $ref: '#/definitions/Record%3Cstring%2Cunknown%3E' - type: string contentType: description: >- The content type of the scraped page, or null if the scrape was unsuccessful or the content type was unavailable. If the scrape was successful and the content type is JSON, the `content` field will contain the parsed JSON object rather than a string. type: string headers: $ref: '#/definitions/Record%3Cstring%2Cstring%3E' description: >- The HTTP response headers returned by the site, or an empty object if unavailable. strategy: description: >- The strategy that ultimately succeeded in scraping the page, or the strategy that was being attempted when the scrape failed. type: string attempted: description: >- The strategies that were attempted during the scrape, in order. type: array items: type: string message: description: >- An error message describing why the scrape failed, or null if the scrape was successful. type: string screenshot: description: >- A base64-encoded full-page PNG screenshot, present when `"screenshot"` is in `formats` and the scrape succeeded. type: string pdf: description: >- A base64-encoded PDF of the page, present when `"pdf"` is in `formats` and the scrape succeeded. type: string markdown: description: >- The page content converted to markdown, present when `"markdown"` is in `formats` and the scrape succeeded. type: string links: description: >- A list of links found on the page, present when `"links"` is in `formats` and the scrape succeeded. type: array items: type: string additionalProperties: false required: - attempted - content - contentType - headers - links - markdown - message - ok - pdf - screenshot - statusCode - strategy definitions: Record: type: object additionalProperties: false Record: type: object additionalProperties: false $schema: http://json-schema.org/draft-07/schema# description: An HTML payload of the scraped page content. '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /smart-scrape tags: - Browser REST APIs /stealth/bql?(/*): post: definitions: {} description: >- 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. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: blockConsentModals schema: description: Whether to automatically block cookie consent modals and popups. type: boolean - in: query name: externalProxyServer schema: description: >- 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. type: string - in: query name: humanlike schema: description: >- Whether to enable human-like behavior for interactions. When true, actions like typing and clicking will have randomized delays. type: boolean - in: query name: launch schema: description: >- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: proxy schema: description: >- The type of proxy to use, currently just 'residential' is supported type: string const: residential - in: query name: proxyCity schema: description: >- 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 type: string - in: query name: proxyCountry schema: description: >- 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 type: string - in: query name: proxyLocaleMatch schema: description: >- 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). enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: proxyPreset schema: description: >- 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") type: string - in: query name: proxyState schema: description: >- The state or province to use for the proxy, whitespace must be replaced with underscores type: string - in: query name: proxySticky schema: description: >- Whether or not to use the same IP for all requests, defaults to true enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: replay schema: description: |- Whether to enable session recording for replay. When true, the session will be recorded and can be replayed later. type: boolean - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: application/json: schema: properties: query: description: The BrowserQL query string to execute. type: string operationName: description: >- The name of the operation to execute if the query contains multiple operations. type: string variables: description: Variables to pass to the BrowserQL query. type: object additionalProperties: {} type: object required: - query responses: '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /stealth/bql?(/*) tags: - Browser REST APIs get: definitions: {} description: >- 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 } } } parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: blockConsentModals schema: type: boolean - in: query name: externalProxyServer schema: description: >- 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. type: string - in: query name: humanlike schema: type: boolean - in: query name: launch schema: description: >- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: proxy schema: description: >- The type of proxy to use, currently just 'residential' is supported type: string const: residential - in: query name: proxyCity schema: description: >- 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 type: string - in: query name: proxyCountry schema: description: >- 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 type: string - in: query name: proxyLocaleMatch schema: description: >- 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). enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: proxyPreset schema: description: >- 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") type: string - in: query name: proxyState schema: description: >- The state or province to use for the proxy, whitespace must be replaced with underscores type: string - in: query name: proxySticky schema: description: >- Whether or not to use the same IP for all requests, defaults to true enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: replay schema: type: boolean - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: {} responses: '101': description: Indicates successful WebSocket upgrade. '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /stealth/bql?(/*) tags: - Browser WebSocket APIs /chrome/bql?(/*): post: definitions: {} description: >- 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. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: blockConsentModals schema: description: Whether to automatically block cookie consent modals and popups. type: boolean - in: query name: externalProxyServer schema: description: >- 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. type: string - in: query name: humanlike schema: description: >- Whether to enable human-like behavior for interactions. When true, actions like typing and clicking will have randomized delays. type: boolean - in: query name: launch schema: description: >- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: proxy schema: description: >- The type of proxy to use, currently just 'residential' is supported type: string const: residential - in: query name: proxyCity schema: description: >- 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 type: string - in: query name: proxyCountry schema: description: >- 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 type: string - in: query name: proxyLocaleMatch schema: description: >- 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). enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: proxyPreset schema: description: >- 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") type: string - in: query name: proxyState schema: description: >- The state or province to use for the proxy, whitespace must be replaced with underscores type: string - in: query name: proxySticky schema: description: >- Whether or not to use the same IP for all requests, defaults to true enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: replay schema: description: |- Whether to enable session recording for replay. When true, the session will be recorded and can be replayed later. type: boolean - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: application/json: schema: properties: query: description: The BrowserQL query string to execute. type: string operationName: description: >- The name of the operation to execute if the query contains multiple operations. type: string variables: description: Variables to pass to the BrowserQL query. type: object additionalProperties: {} type: object required: - query responses: '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /chrome/bql?(/*) tags: - Browser REST APIs get: definitions: {} description: >- 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 } } } parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: blockConsentModals schema: type: boolean - in: query name: externalProxyServer schema: description: >- 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. type: string - in: query name: humanlike schema: type: boolean - in: query name: launch schema: description: >- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: proxy schema: description: >- The type of proxy to use, currently just 'residential' is supported type: string const: residential - in: query name: proxyCity schema: description: >- 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 type: string - in: query name: proxyCountry schema: description: >- 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 type: string - in: query name: proxyLocaleMatch schema: description: >- 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). enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: proxyPreset schema: description: >- 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") type: string - in: query name: proxyState schema: description: >- The state or province to use for the proxy, whitespace must be replaced with underscores type: string - in: query name: proxySticky schema: description: >- Whether or not to use the same IP for all requests, defaults to true enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: replay schema: type: boolean - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: {} responses: '101': description: Indicates successful WebSocket upgrade. '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /chrome/bql?(/*) tags: - Browser WebSocket APIs /chromium/bql?(/*): post: definitions: {} description: >- 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. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: blockConsentModals schema: description: Whether to automatically block cookie consent modals and popups. type: boolean - in: query name: externalProxyServer schema: description: >- 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. type: string - in: query name: humanlike schema: description: >- Whether to enable human-like behavior for interactions. When true, actions like typing and clicking will have randomized delays. type: boolean - in: query name: launch schema: description: >- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: proxy schema: description: >- The type of proxy to use, currently just 'residential' is supported type: string const: residential - in: query name: proxyCity schema: description: >- 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 type: string - in: query name: proxyCountry schema: description: >- 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 type: string - in: query name: proxyLocaleMatch schema: description: >- 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). enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: proxyPreset schema: description: >- 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") type: string - in: query name: proxyState schema: description: >- The state or province to use for the proxy, whitespace must be replaced with underscores type: string - in: query name: proxySticky schema: description: >- Whether or not to use the same IP for all requests, defaults to true enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: replay schema: description: |- Whether to enable session recording for replay. When true, the session will be recorded and can be replayed later. type: boolean - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: application/json: schema: properties: query: description: The BrowserQL query string to execute. type: string operationName: description: >- The name of the operation to execute if the query contains multiple operations. type: string variables: description: Variables to pass to the BrowserQL query. type: object additionalProperties: {} type: object required: - query responses: '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /chromium/bql?(/*) tags: - Browser REST APIs get: definitions: {} description: >- 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 } } } parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: blockConsentModals schema: type: boolean - in: query name: externalProxyServer schema: description: >- 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. type: string - in: query name: humanlike schema: type: boolean - in: query name: launch schema: description: >- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: proxy schema: description: >- The type of proxy to use, currently just 'residential' is supported type: string const: residential - in: query name: proxyCity schema: description: >- 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 type: string - in: query name: proxyCountry schema: description: >- 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 type: string - in: query name: proxyLocaleMatch schema: description: >- 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). enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: proxyPreset schema: description: >- 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") type: string - in: query name: proxyState schema: description: >- The state or province to use for the proxy, whitespace must be replaced with underscores type: string - in: query name: proxySticky schema: description: >- Whether or not to use the same IP for all requests, defaults to true enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: replay schema: type: boolean - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: {} responses: '101': description: Indicates successful WebSocket upgrade. '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /chromium/bql?(/*) tags: - Browser WebSocket APIs /session/bql/*: post: definitions: {} description: >- > 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. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: launch schema: description: >- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: replay schema: type: boolean - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: application/json: schema: properties: query: description: >- 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 } }` type: string variables: description: >- Variables to pass to the GraphQL query. Useful for dynamic values. Example: `{ "url": "https://example.com", "selector": "h1", "text": "Hello World" }` type: object additionalProperties: {} operationName: description: >- The name of the operation to execute if the query contains multiple operations. Optional - only needed when query has multiple named operations. type: string type: object required: - query responses: '200': content: application/json: schema: type: object properties: data: $ref: '#/definitions/Record%3Cstring%2Cany%3E' description: >- The GraphQL response data. Contains the result of the executed query. Structure depends on the specific query executed. Example responses: - Navigation + Title + Element: `{ "goto": { "status": 200 }, "title": { "title": "Example Domain" }, "querySelector": { "innerHTML": "Example Domain" } }` - Multiple elements: `{ "querySelectorAll": [{ "innerHTML": "Item 1" }, { "innerHTML": "Item 2" }] }` - Screenshot: `{ "screenshot": { "data": "base64encodedimage", "type": "png" } }` - PDF: `{ "pdf": { "data": "base64encodedpdf" } }` - System info: `{ "version": "1.0.0", "browser": "Chrome/120.0.0.0" }` - Form interaction: `{ "type": { "success": true }, "click": { "success": true } }` errors: description: >- Array of GraphQL errors, if any occurred during query execution. Only present when errors exist. type: array items: type: object properties: message: description: Error message describing what went wrong type: string locations: description: Locations in the query where the error occurred type: array items: type: object properties: line: type: number column: type: number additionalProperties: false required: - column - line path: description: Path to the field that caused the error type: array items: type: - string - number additionalProperties: false required: - message additionalProperties: false definitions: Record: type: object additionalProperties: false $schema: http://json-schema.org/draft-07/schema# '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /session/bql/* tags: - Management REST APIs - Browser REST APIs /crawl/*: delete: definitions: {} description: >- 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. parameters: - in: query name: token schema: description: The API token for authenticating the request. type: string requestBody: content: {} responses: '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /crawl/* tags: - Browser REST APIs get: definitions: {} description: >- 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. parameters: - in: query name: skip schema: description: The number of pages to skip for pagination. type: number - in: query name: token schema: description: The API token for authenticating the request. type: string requestBody: content: {} responses: '200': content: application/json: schema: type: object properties: status: $ref: '#/definitions/CrawlStatus' total: type: number completed: type: number failed: type: number expiresAt: type: string next: type: string data: type: array items: $ref: '#/definitions/CrawlPageResponse' additionalProperties: false required: - completed - data - expiresAt - failed - next - status - total definitions: CrawlStatus: enum: - cancelled - completed - failed - in-progress type: string CrawlPageResponse: type: object properties: status: $ref: '#/definitions/PageStatus' contentUrl: type: string metadata: type: object properties: title: type: string description: type: string language: type: string scrapedAt: type: string sourceURL: type: string statusCode: type: number error: type: string additionalProperties: false required: - description - error - language - scrapedAt - sourceURL - statusCode - title additionalProperties: false required: - contentUrl - metadata - status PageStatus: enum: - cancelled - completed - failed - in-progress - queued type: string $schema: http://json-schema.org/draft-07/schema# '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /crawl/* tags: - Browser REST APIs /crawl: get: definitions: {} description: >- 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. parameters: - in: query name: cursor schema: description: Cursor for fetching the next page of results. type: string - in: query name: limit schema: description: Maximum number of crawls to return per page (1–100, default 20). type: number - in: query name: status schema: description: >- Filter crawls by status: in-progress, completed, failed, or cancelled. type: string - in: query name: token schema: description: The API token for authenticating the request. type: string requestBody: content: {} responses: '200': content: application/json: schema: type: object properties: crawls: type: array items: $ref: '#/definitions/CrawlListItem' nextCursor: type: string additionalProperties: false required: - crawls - nextCursor definitions: CrawlListItem: type: object properties: id: type: string url: type: string status: $ref: '#/definitions/CrawlStatus' total: type: number completed: type: number createdAt: type: string completedAt: type: string additionalProperties: false required: - completed - completedAt - createdAt - id - status - total - url CrawlStatus: enum: - cancelled - completed - failed - in-progress type: string $schema: http://json-schema.org/draft-07/schema# '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /crawl tags: - Browser REST APIs post: definitions: {} description: >- 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. parameters: - in: query name: profile schema: description: >- 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. type: string - in: query name: token schema: description: The API token for authenticating the request. type: string requestBody: content: application/json: schema: properties: url: description: The URL to crawl. Must be a valid http or https URL. type: string limit: description: >- Maximum number of pages to crawl. Clamped to your plan's limit. default: 100 minimum: 1 type: number maxDepth: description: Maximum link-follow depth from the root URL. default: 5 minimum: 0 type: number maxRetries: description: Number of retry attempts per failed page. default: 1 minimum: 0 type: number allowExternalLinks: description: Whether to follow links to external domains. default: false type: boolean allowSubdomains: description: Whether to follow links to subdomains of the root URL. default: false type: boolean sitemap: description: Sitemap handling strategy. default: auto enum: - auto - force - skip type: string includePaths: description: Regex patterns for URL paths to include. default: [] type: array items: type: string excludePaths: description: Regex patterns for URL paths to exclude. default: [] type: array items: type: string delay: description: Delay between requests in milliseconds. default: 200 minimum: 0 type: number scrapeOptions: description: Options controlling how each page is scraped. type: object properties: formats: description: Output formats for scraped content. default: - markdown type: array items: enum: - html - markdown - rawText type: string onlyMainContent: description: Whether to extract only the main content of the page. default: true type: boolean includeTags: description: HTML tag selectors to include. default: [] type: array items: type: string excludeTags: description: HTML tag selectors to exclude. default: [] type: array items: type: string waitFor: description: Time in ms to wait after page load before scraping. default: 0 minimum: 0 type: number headers: description: Custom HTTP headers to send with each request. type: object additionalProperties: type: string timeout: description: Navigation timeout in milliseconds. default: 150000 minimum: 1000 maximum: 180000 type: number additionalProperties: false webhook: description: Webhook configuration for crawl event notifications. type: object properties: url: description: The HTTPS URL to send webhook events to. type: string events: description: Which events to send. default: - completed type: array items: enum: - completed - failed - page type: string additionalProperties: false required: - url type: object required: - url responses: '200': content: application/json: schema: type: object properties: success: type: boolean id: type: string url: type: string additionalProperties: false required: - id - success - url $schema: http://json-schema.org/draft-07/schema# '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /crawl tags: - Browser REST APIs /profile: post: definitions: {} description: >- 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. parameters: [] requestBody: content: application/json: schema: properties: name: description: |- A user-visible name for the profile. Must be unique per token. type: string stealth: description: >- Whether or not to enable advanced stealth mode. Defaults to false. type: boolean browser: description: The type of browser to use. Defaults to 'stealth'. enum: - chrome - chromium - stealth type: string args: description: An array of command-line arguments to pass to the browser. type: array items: type: string proxy: description: Proxy parameters for the profile creation session. type: object properties: type: description: >- The type of proxy to use, currently only 'residential' is supported. type: string const: residential sticky: description: >- Whether or not to use the same IP address for all proxied requests. Defaults to true. type: boolean country: description: >- The country to proxy through. Defaults to 'us' or United States. type: string city: description: The city to proxy through. type: string state: description: The state to proxy through. type: string preset: description: >- Preset code for website-specific proxy configurations (e.g., 'px_gov01' for government sites). type: string additionalProperties: false type: object required: - name responses: '200': content: application/json: schema: type: object properties: id: description: Temporary session ID used for the profile creation browser type: string name: description: The profile name that will be used when saving type: string connect: description: WebSocket URL to connect to the browser type: string stop: description: URL to stop/delete the temporary session type: string additionalProperties: false required: - connect - id - name - stop $schema: http://json-schema.org/draft-07/schema# '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /profile tags: - Management REST APIs /profile/*: delete: definitions: {} description: |- 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. parameters: [] requestBody: content: {} responses: '200': content: application/json: schema: type: object properties: success: description: Always true on success. type: boolean message: description: Human-readable confirmation message. type: string name: description: Name of the profile that was deleted. type: string additionalProperties: false required: - message - name - success $schema: http://json-schema.org/draft-07/schema# '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /profile/* tags: - Management REST APIs get: definitions: {} description: |- 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. parameters: [] requestBody: content: {} responses: '200': content: application/json: schema: type: object properties: id: description: Unique profile identifier. type: string name: description: User-supplied profile name. Unique per token. type: string cookieCount: description: Number of cookies captured in the profile. type: number originCount: description: >- Number of distinct origins with stored localStorage or IndexedDB. type: number lastUsedAt: description: >- ISO timestamp of the last time this profile was applied to a session, or null if never used. type: string createdAt: description: ISO timestamp of when the profile was created. type: string updatedAt: description: ISO timestamp of the last metadata change (e.g., rename). type: string additionalProperties: false required: - cookieCount - createdAt - id - lastUsedAt - name - originCount - updatedAt $schema: http://json-schema.org/draft-07/schema# '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /profile/* tags: - Management REST APIs put: definitions: {} description: >- 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. parameters: [] requestBody: content: application/json: schema: properties: name: description: The new name for the profile. type: string type: object required: - name responses: '200': content: application/json: schema: type: object properties: id: description: Unique profile identifier. type: string name: description: User-supplied profile name. Unique per token. type: string cookieCount: description: Number of cookies captured in the profile. type: number originCount: description: >- Number of distinct origins with stored localStorage or IndexedDB. type: number lastUsedAt: description: >- ISO timestamp of the last time this profile was applied to a session, or null if never used. type: string createdAt: description: ISO timestamp of when the profile was created. type: string updatedAt: description: ISO timestamp of the last metadata change (e.g., rename). type: string additionalProperties: false required: - cookieCount - createdAt - id - lastUsedAt - name - originCount - updatedAt $schema: http://json-schema.org/draft-07/schema# '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /profile/* tags: - Management REST APIs /profiles: get: definitions: {} description: >- 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. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: launch schema: description: |- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - $ref: '#/definitions/BrowserServerOptions' - type: string - in: query name: limit schema: description: Maximum number of profiles to return (1–1000). Defaults to 100. type: number - in: query name: offset schema: description: Number of profiles to skip for pagination. Defaults to 0. type: number - in: query name: profile schema: description: >- 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. type: string - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: {} responses: '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /profiles tags: - Management REST APIs /profile/refresh: post: definitions: {} description: |- 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". parameters: [] requestBody: content: application/json: schema: properties: name: description: >- Name of the existing profile to refresh. Must already exist for the requesting token. type: string state: description: >- Pre-captured authentication state. Same shape as `POST /profile/upload`. type: object required: - name - state responses: '200': content: application/json: schema: type: object properties: diagnostics: $ref: '#/definitions/RefreshResponseDiagnostics' description: >- Per-entry counts of cookies, origins, and IndexedDB items the server dropped or truncated before persisting. All zero on a clean refresh. id: description: Unique profile identifier. type: string name: description: User-supplied profile name. Unique per token. type: string cookieCount: description: Number of cookies captured in the profile. type: number originCount: description: >- Number of distinct origins with stored localStorage or IndexedDB. type: number lastUsedAt: description: >- ISO timestamp of the last time this profile was applied to a session, or null if never used. type: string createdAt: description: ISO timestamp of when the profile was created. type: string updatedAt: description: ISO timestamp of the last metadata change (e.g., rename). type: string additionalProperties: false required: - cookieCount - createdAt - diagnostics - id - lastUsedAt - name - originCount - updatedAt definitions: RefreshResponseDiagnostics: description: >- Per-entry counts of cookies, origins, and IndexedDB items the server dropped or truncated before persisting. All zero on a clean refresh. type: object properties: skippedMalformedCookies: description: >- Cookies dropped because required fields were missing or wrong type. type: number skippedPrivateCookies: description: >- Cookies dropped because their domain pointed at a private/internal host. type: number skippedMalformedOrigins: description: >- Origins dropped because they were malformed or non-http(s). type: number skippedPrivateOrigins: description: >- Origins dropped because they targeted a private/internal network. type: number truncatedOrigins: description: >- Origins dropped because the per-profile cap was exceeded. type: number skippedMalformedIdbDatabases: description: >- IndexedDB databases dropped because required fields were missing. type: number truncatedIdbDatabases: description: >- IndexedDB databases dropped because the per-origin cap was exceeded. type: number skippedMalformedIdbStores: description: >- IndexedDB object-stores dropped because required fields were missing. type: number truncatedIdbEntries: description: >- IndexedDB entries dropped because the per-store cap was exceeded. type: number additionalProperties: false required: - skippedMalformedCookies - skippedMalformedIdbDatabases - skippedMalformedIdbStores - skippedMalformedOrigins - skippedPrivateCookies - skippedPrivateOrigins - truncatedIdbDatabases - truncatedIdbEntries - truncatedOrigins $schema: http://json-schema.org/draft-07/schema# '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /profile/refresh tags: - Management REST APIs /profile/upload: post: definitions: {} description: |- 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". parameters: [] requestBody: content: application/json: schema: properties: name: description: >- A user-visible name for the profile. Must be unique per token. type: string state: description: >- Pre-captured authentication state. An object with two arrays — `cookies` (browser cookies) and `origins` (per-origin localStorage and IndexedDB). type: object required: - name - state responses: '200': content: application/json: schema: type: object properties: diagnostics: $ref: '#/definitions/UploadResponseDiagnostics' description: >- Per-entry counts of cookies, origins, and IndexedDB items the server dropped or truncated before persisting. All zero on a clean upload. id: description: Unique profile identifier. type: string name: description: User-supplied profile name. Unique per token. type: string cookieCount: description: Number of cookies captured in the profile. type: number originCount: description: >- Number of distinct origins with stored localStorage or IndexedDB. type: number lastUsedAt: description: >- ISO timestamp of the last time this profile was applied to a session, or null if never used. type: string createdAt: description: ISO timestamp of when the profile was created. type: string updatedAt: description: ISO timestamp of the last metadata change (e.g., rename). type: string additionalProperties: false required: - cookieCount - createdAt - diagnostics - id - lastUsedAt - name - originCount - updatedAt definitions: UploadResponseDiagnostics: description: >- Per-entry counts of cookies, origins, and IndexedDB items the server dropped or truncated before persisting. All zero on a clean upload. type: object properties: skippedMalformedCookies: description: >- Cookies dropped because required fields were missing or wrong type. type: number skippedPrivateCookies: description: >- Cookies dropped because their domain pointed at a private/internal host. type: number skippedMalformedOrigins: description: >- Origins dropped because they were malformed or non-http(s). type: number skippedPrivateOrigins: description: >- Origins dropped because they targeted a private/internal network. type: number truncatedOrigins: description: >- Origins dropped because the per-profile cap was exceeded. type: number skippedMalformedIdbDatabases: description: >- IndexedDB databases dropped because required fields were missing. type: number truncatedIdbDatabases: description: >- IndexedDB databases dropped because the per-origin cap was exceeded. type: number skippedMalformedIdbStores: description: >- IndexedDB object-stores dropped because required fields were missing. type: number truncatedIdbEntries: description: >- IndexedDB entries dropped because the per-store cap was exceeded. type: number additionalProperties: false required: - skippedMalformedCookies - skippedMalformedIdbDatabases - skippedMalformedIdbStores - skippedMalformedOrigins - skippedPrivateCookies - skippedPrivateOrigins - truncatedIdbDatabases - truncatedIdbEntries - truncatedOrigins $schema: http://json-schema.org/draft-07/schema# '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /profile/upload tags: - Management REST APIs /stealth: get: definitions: {} description: >- 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. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: externalProxyServer schema: description: >- 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. type: string - in: query name: integrations schema: type: string - in: query name: launch schema: description: |- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: proxy schema: description: >- The type of proxy to use, currently just 'residential' is supported type: string const: residential - in: query name: proxyCity schema: description: >- 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 type: string - in: query name: proxyCountry schema: description: >- 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 type: string - in: query name: proxyLocaleMatch schema: description: >- 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). enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: proxyPreset schema: description: >- 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") type: string - in: query name: proxyState schema: description: >- The state or province to use for the proxy, whitespace must be replaced with underscores type: string - in: query name: proxySticky schema: description: >- Whether or not to use the same IP for all requests, defaults to true enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: record schema: type: boolean - in: query name: replay schema: type: boolean - in: query name: solveCaptchas schema: type: boolean - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: {} responses: '101': description: Indicates successful WebSocket upgrade. '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /stealth tags: - Browser WebSocket APIs /chrome/live/*: get: definitions: {} description: >- > This API is only available on paid plans. [Sign-up here](https://www.browserless.io/pricing/). Websocket back-end that powers the live session experience. parameters: [] requestBody: content: {} responses: '101': description: Indicates successful WebSocket upgrade. '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /chrome/live/* tags: - Browser WebSocket APIs /chrome/stealth: get: definitions: {} description: >- 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. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: externalProxyServer schema: description: >- 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. type: string - in: query name: integrations schema: type: string - in: query name: launch schema: description: |- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: proxy schema: description: >- The type of proxy to use, currently just 'residential' is supported type: string const: residential - in: query name: proxyCity schema: description: >- 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 type: string - in: query name: proxyCountry schema: description: >- 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 type: string - in: query name: proxyLocaleMatch schema: description: >- 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). enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: proxyPreset schema: description: >- 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") type: string - in: query name: proxyState schema: description: >- The state or province to use for the proxy, whitespace must be replaced with underscores type: string - in: query name: proxySticky schema: description: >- Whether or not to use the same IP for all requests, defaults to true enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: record schema: type: boolean - in: query name: replay schema: type: boolean - in: query name: solveCaptchas schema: type: boolean - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: {} responses: '101': description: Indicates successful WebSocket upgrade. '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /chrome/stealth tags: - Browser WebSocket APIs /live/*: get: definitions: {} description: >- > This API is only available on paid plans. [Sign-up here](https://www.browserless.io/pricing/). Websocket back-end that powers the live session experience. **Note:** This endpoint is also available at: `/chromium/live/*` for backwards compatibility. parameters: [] requestBody: content: {} responses: '101': description: Indicates successful WebSocket upgrade. '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /live/* tags: - Browser WebSocket APIs /chromium/stealth: get: definitions: {} description: >- 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. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: externalProxyServer schema: description: >- 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. type: string - in: query name: integrations schema: type: string - in: query name: launch schema: description: |- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: proxy schema: description: >- The type of proxy to use, currently just 'residential' is supported type: string const: residential - in: query name: proxyCity schema: description: >- 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 type: string - in: query name: proxyCountry schema: description: >- 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 type: string - in: query name: proxyLocaleMatch schema: description: >- 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). enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: proxyPreset schema: description: >- 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") type: string - in: query name: proxyState schema: description: >- The state or province to use for the proxy, whitespace must be replaced with underscores type: string - in: query name: proxySticky schema: description: >- Whether or not to use the same IP for all requests, defaults to true enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: record schema: type: boolean - in: query name: replay schema: type: boolean - in: query name: solveCaptchas schema: type: boolean - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: {} responses: '101': description: Indicates successful WebSocket upgrade. '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /chromium/stealth tags: - Browser WebSocket APIs /reconnect/*: get: definitions: {} description: >- Reconnect to an existing Chromium or Chrome session with a library like puppeteer or others that work over chrome-devtools-protocol. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: integrations schema: type: string - in: query name: launch schema: description: |- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - $ref: '#/definitions/BrowserServerOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: replay schema: type: boolean - in: query name: solveCaptchas schema: type: boolean - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: {} responses: '101': description: Indicates successful WebSocket upgrade. '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /reconnect/* tags: - Browser WebSocket APIs /session/connect/*: get: definitions: {} description: >- 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. parameters: - in: query name: launch schema: anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: replay schema: type: boolean - in: query name: timeout schema: type: number - in: query name: token schema: type: string requestBody: content: {} responses: '101': description: Indicates successful WebSocket upgrade. '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /session/connect/* tags: - Browser WebSocket APIs /chromium/agent: get: definitions: {} description: >- WebSocket endpoint for agentic browser interaction. Connect to establish a persistent browser session, then send JSON-RPC messages to control the browser. Uses a simple JSON protocol instead of GraphQL: Send: { "id": 1, "method": "goto", "params": { "url": "https://example.com" } } Receive: { "id": 1, "result": { "status": 200, "url": "https://example.com" } } All BQL mutations are available as methods (goto, click, type, screenshot, etc.). Additionally supports a "snapshot" method that returns interactive page elements with CSS selectors, plus tab-management methods (getTabs, switchTab, createTab, closeTab) for multi-tab workflows. parameters: - in: query name: blockAds schema: description: |- Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly. type: boolean - in: query name: blockConsentModals schema: description: Whether to automatically block cookie consent modals and popups. type: boolean - in: query name: externalProxyServer schema: description: >- 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. type: string - in: query name: humanlike schema: description: >- Whether to enable human-like behavior for interactions. When true, actions like typing and clicking will have randomized delays. type: boolean - in: query name: launch schema: description: >- 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. anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: >- 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. type: string - in: query name: proxy schema: description: >- The type of proxy to use, currently just 'residential' is supported type: string const: residential - in: query name: proxyCity schema: description: >- 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 type: string - in: query name: proxyCountry schema: description: >- 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 type: string - in: query name: proxyLocaleMatch schema: description: >- 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). enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: proxyPreset schema: description: >- 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") type: string - in: query name: proxyState schema: description: >- The state or province to use for the proxy, whitespace must be replaced with underscores type: string - in: query name: proxySticky schema: description: >- Whether or not to use the same IP for all requests, defaults to true enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: replay schema: description: |- Whether to enable session recording for replay. When true, the session will be recorded and can be replayed later. type: boolean - in: query name: timeout schema: description: |- Override the system-level timeout for this request. Accepts a value in milliseconds. type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: {} responses: '101': description: Indicates successful WebSocket upgrade. '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /chromium/agent tags: - Browser WebSocket APIs servers: [] components: {}