Skip to main content

Terminology

On the main browserless.io site, and inside this documentation site, you'll notice we use a few terms like "worker" or "session". Below is a list of commonly-used terms and what they mean.

WebSocket Endpoint​

The WebSocket endpoint (wsEndpoint()) is the internal browser's native WebSocket URL that the browser process exposes when launched. This is a local address (e.g., ws://127.0.0.1:9222/devtools/browser/...) that points directly to the browser's debugging port.

For CDP browsers, this endpoint is obtained after launching the browser and represents the raw connection point to Chrome DevTools Protocol. For Playwright browsers, it's similarly obtained from the browser server's wsEndpoint() method.

Connection URL​

The connection URL (publicWSEndpoint()) is the externally-accessible URL that clients use to connect to the browser through Browserless. This URL is constructed by taking the internal WebSocket endpoint's path and combining it with the configured external address. For ex. wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN

Worker​

A worker is a Browserless container instance running on a virtual machine. Cloud-Unit plans use a distributed fleet of workers to serve multiple users simultaneously, while Enterprise customers can work with us to provision appropriately sized workers and scale them to meet their specific traffic requirements.

Session​

A session is anytime Chrome is actively running and connected to. Browserless automatically queues up to twice your concurrency limit, allowing traffic bursts without code changes—simply continue using puppeteer.connect() and requests will queue when capacity is reached.

To handle higher session volumes, you can scale up your worker size or deploy additional worker instances.

Concurrency​

Concurrency refers to the maximum number of browser sessions that can run simultaneously on a browserless instance. This is a core limit that controls how many parallel browser automations your account can execute at once.

For self-hosted instances, concurrency can be configured via the CONCURRENT or MAX_CONCURRENT_SESSIONS environment variables, with a default of 10 concurrent sessions. For details of concurrency limits in different plans, see our pricing plans for concurrency limits.

There's also a queue system configured via QUEUED or QUEUE_LENGTH environment variables (default 10) that allows requests to wait when concurrency is at capacity.

You can check current concurrency usage via the /pressure API endpoint, which returns:

  • running: Current number of active sessions
  • queued: Current number of queued sessions
  • maxConcurrent: Maximum allowed concurrent sessions
  • maxQueued: Maximum allowed queued sessions

Pressure​

Pressure indicates how much traffic is going on in your workers at any given time. Using the GraphQL API, you can fetch important details like isAvailable to see if your workers can handle another connection. Doing so will ensure your accout doesn't get overloaded and become unresponsive.

# https://api.browserless.io/graphql
{
  pressure(apiToken: "YOUR_API_KEY") {
    running
    recentlyRejected
    queued
    isAvailable
    date
  }
}

This request will return a JSON object with the following payload:

// JSON returned
{
  "data": {
    "pressure": {
      "running": 0,
      "recentlyRejected": 0,
      "queued": 0,
      "isAvailable": true,
      "date": 1524762532204
    }
  }
}