Browserless GraphQL API

The Browserless GraphQL API exposes queries for monitoring fleet health, session activity, and unit consumption on your dedicated fleet.

note

This GraphQL API is specifically for monitoring and managing private Browserless deployments (checking session pressure, metrics, etc). If you are looking for browser automation capabilities, you should use BrowserQL instead, which is our dedicated browser automation API.

Pressure

The pressure query shows how much load your instance(s) are under, and whether they can accept more traffic or not. This is real-time, so if you need to check if your instance can take more traffic you can do a request to check prior to running your puppeteer.connect call.

warning

The pressure queries are still in BETA and may experience breaking schema changes.

GraphQL Example:

{
  pressure(apiToken: "YOUR_API_TOKEN_HERE") {
    running
    recentlyRejected
    queued
    isAvailable
    date
  }
}

cURL Example:

curl --location 'https://api.browserless.io/graphql' \
--header 'Content-Type: application/json' \
--data '{"query":"{\n  pressure(apiToken: \"YOUR_API_TOKEN_HERE\") {\n    running\n    recentlyRejected\n    queued\n    isAvailable\n    date\n  }\n}","variables":{}}'

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

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

Use the isAvailable boolean to check if the instance can handle more connections before running your puppeteer.connect call. This is useful for pre-session checks to keep workers healthy and prevent rejections or queuing.

Metrics

The metrics query returns performance data for your workers, including successful, rejected, and timed-out session counts.

warning

The metrics queries are still in BETA and may experience breaking schema changes.

GraphQL Example:

{
  metrics(apiToken: "YOUR_API_TOKEN_HERE") {
    successful
    rejected
    timedout
    queued
    cpu
    memory
    date
  }
}

cURL Example:

curl --location 'https://api.browserless.io/graphql' \
--header 'Content-Type: application/json' \
--data '{"query":"{\n  metrics(apiToken: \"YOUR_API_TOKEN_HERE\") {\n    successful\n    rejected\n    timedout\n    queued\n    cpu\n    memory\n    date\n  }\n}","variables":{}}'

This request returns an array of objects with metrics for your instances. When multiple instances exist, stats are aggregated in 5-minute intervals. CPU and memory are averaged across instances.

{
  "data": {
    "metrics": [
      {
        "successful": 0,
        "rejected": 0,
        "timedout": 0,
        "queued": 0,
        "cpu": 0.002734375,
        "memory": 0.9055320561641963,
        "date": 1524227700000
      },
      //...
    ]
  }
}

Sessions

Not for Session Management

This GraphQL sessions query is for monitoring currently running browser sessions. It should not be confused with the REST sessions endpoint, which is used to create and manage persistent browser session endpoints.

The sessions query returns currently running browser instances. This query requires a dedicated fleet for security.

GraphQL Example:

{
  sessions(apiToken: "YOUR_API_TOKEN_HERE") {
    description
    devtoolsFrontendUrl
    live
    kill
    title
    type
    url
    trackingId
    browserId
    browserWSEndpoint
    browserWSEndpointClient
  }
}

cURL Example:

curl --location 'https://api.browserless.io/graphql' \
--header 'Content-Type: application/json' \
--data '{
  "query": "{ sessions(apiToken: \"YOUR_API_TOKEN_HERE\") { description devtoolsFrontendUrl live kill title type url trackingId browserId browserWSEndpoint browserWSEndpointClient } }",
  "variables": {}
}'

warning

For security purposes, we limit the number of failed GraphQL request attempts. If you encounter rate limiting errors, you'll need to wait until the top of the hour before making additional requests.

Export Metrics

Use the exportMetrics query to retrieve unit consumption data. This is more accurate than the REST /metrics/total endpoint because it queries aggregated billing data rather than per-worker stats. Stats from /metrics/total reset after a Relaunch; exportMetrics does not.

Authentication

The exportMetrics query requires an auth token obtained via the login mutation:

mutation Login($email: String!, $password: String!) {
  login(email: $email, password: $password) {
    authToken
    needsSecondFactor
  }
}

If needsSecondFactor is true, complete authentication with loginSecondFactor. Pass the authToken from the login response and the OTP code from your authenticator app:

mutation LoginSecondFactor($authToken: String!, $otp: String!) {
  loginSecondFactor(authToken: $authToken, otp: $otp) {
    authToken
  }
}

Use the authToken returned by loginSecondFactor (or by login if 2FA is not enabled) in the query below.

Query

query ExportMetrics($apiToken: String!, $timeslot: timeslot, $authToken: String) {
  exportMetrics(apiToken: $apiToken, timeslot: $timeslot, authToken: $authToken) {
    date
    totalUnitsUsed
    timeUnits
    proxyUnits
    captchaUnits
  }
}

The timeslot parameter accepts "year", "month", or "week".