Skip to main content
Version: v2

Connection URLs and Endpoints

Our BaaS offering allows you to control Puppeteer, Playwright, and similar libraries through a WSS (WebSocket Secure), allowing real-time browser. It provides persistent, bidirectional communication for browser automation and interactive sessions.

A sample Connection URL using Chrome from our San Francisco load-balancer would look like this:
wss://production-sfo.browserless.io/chrome?token=094632bb-e326-4c63-b953-82b55700b14c

note

Looking for REST API connections? Quickly generate screenshots, PDFs, or extract HTML with our REST APIs, with no need to install libraries.

Building Your Connection URL​

Connection URL Pattern​

Connection URLs are strings that follow this pattern:

wss://production-region.browserless.io/browser/optional?token=YOUR_API_TOKEN_HERE

Connection URL Tool​

Below you can quickly select your preferred configuration to build your required connection URL:

BaaS Connection URL Builder

Connection URL:

wss://production-sfo.browserless.io/?token=YOUR_TOKEN

Code Snippet:

const browser = await puppeteer.connect({
  browserWSEndpoint: 'wss://production-sfo.browserless.io/?token=YOUR_TOKEN',
});

Endpoint components​

Authentication​

You can authenticate by appending your API token to the URL query string as wss://production-sfo.browserless.io/?token=YOUR_TOKEN.
Invalid tokens result in HTTP 401 errors.

Region​

Selecting a closer endpoint reduces latency by minimizing the round-trip time between your application and the browser instance, which is especially important for WebSocket connections that require real-time communication. Lower latency means faster page loads, quicker DOM interactions, and more responsive automation scripts.
See Load Balancers to use the closest available regional endpoint for your application.

Browser Binaries, Protocol and Library​

Each library version comes bundled up with a browser binary version. It's important to define the browser/library and protocol, in the case of Playwright for a successful connection.

If no browser binary is defined in the connection string, Browserless will default to /chromium. It's important to note that multimedia-rich sites may display a message such as "Browser not supported", which can many times be fixed by using the /chrome path, which contains the necessary codecs.

Puppeteer supports /chromium and /chrome.

  • Chromium: wss://production-sfo.browserless.io/?token=YOUR_TOKEN
  • Chrome: wss://production-sfo.browserless.io/chrome?token=YOUR_TOKEN

Playwright supports /chrome, /chromium, /firefox, /webkit, and /edge.

Using Playwright's CDP Mode:

  • Chrome: wss://production-sfo.browserless.io/chrome?token=YOUR_TOKEN
  • Chromium: wss://production-sfo.browserless.io/chromium?token=YOUR_TOKEN

Using Playwright's Server Mode:

The playwright path is only required when using Playwright with their server mode.

  • Chrome: wss://production-sfo.browserless.io/chrome/playwright?token=YOUR_TOKEN
  • Chromium: wss://production-sfo.browserless.io/chromium/playwright?token=YOUR_TOKEN
  • Firefox: wss://production-sfo.browserless.io/firefox/playwright?token=YOUR_TOKEN
  • WebKit: wss://production-sfo.browserless.io/webkit/playwright?token=YOUR_TOKEN
  • Edge: wss://production-sfo.browserless.io/edge/playwright?token=YOUR_TOKEN

Stealth Mode​

This path is optional, but if used, it will implement stealthy behavior developed by the Browserless team.
wss://production-sfo.browserless.io/chromium/stealth?token=YOUR_TOKEN

See Also

Load Balancers — learn how requests are distributed across Browserless servers and regions.