Skip to main content
Version: v2

/performance API

info

Currently, Browserless V2 is available in production via two domains: production-sfo.browserless.io and production-lon.browserless.io

The performance API reveals key metrics about a site's accessibility, best practices, performance, PWA information, and SEO, from a performance standpoint. It includes useful metrics like latency, time-to-interaction, design contrast other recommendations. This API is powered by Google's Lighthouse project, and it's compatible with its CLI options.

In order to gather this data, send a POST request to https://production-sfo.browserless.io/performance if on a hosted plan, with a simple JSON payload containing a valid URL.

warning

Due to the number of checks gathered it can take anywhere from several seconds to minutes depending on the site and size of the worker.

You can check the full Open API schema here.

Examples​

  1. Basic Usage
  2. Gathering metrics for a category
  3. Gathering metrics from a single audit

Basic Usage​

JSON

{
  "url": "https://example.com/"
}

cURL request

curl -X POST \
  https://production-sfo.browserless.io/performance?token=MY_API_TOKEN \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '
{
  "url": "https://example.com/"
}'

By default, the /performance API will gather all the metrics. This will not only result in a really big JSON response (350kb to 800kb on average) and it will take some seconds (to minutes) to complete.

Each test has a score that indicates how well it performed, where 1 is the maximum and 0 is the lowest, generating a response like this:

  // ...
  "audits": {
    "is-on-https": {
      "title": "Uses HTTPS",
      "score": 1
      // ...
    },
    "viewport": {
      "title": "Has a `<meta name=\"viewport\">` tag with `width` or `initial-scale`",
      "score": 1
      // ...
    },
    "first-contentful-paint": {
      "score": 1,
      "displayValue": "0.8 s"
      // ...
    }
    // ...
  }

Gathering metrics for a category​

You can get metrics from specific categories, using the config property. Just like Lighthouse, available categories are accessibility, best practices, performance, pwa, and seo

JSON

{
  "url": "https://example.com",
  "config": {
    "extends": "lighthouse:default",
    "settings": {
      "onlyCategories": ["accessibility"]
    }
  }
}

cURL request

curl --request POST \
  --url 'https://production-sfo.browserless.io/performance?token=MY_API_TOKEN' \
  --header 'Cache-Control: no-cache' \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://browserless.io",
  "config": {
    "extends": "lighthouse:default",
    "settings": {
      "onlyCategories": ["accessibility"]
    }
  }
}'

This will gather the predefined metrics defined by Lighthouse for that category:

  // ...
  "audits": {
    "aria-command-name": {
      "title": "`button`, `link`, and `menuitem` elements have accessible names",
      "score": 1
      // ...
    },
    "aria-hidden-body": {
      "title": "`[aria-hidden=\"true\"]` is not present on the document `<body>`",
      "score": 1
      // ...
    },
    "aria-hidden-focus": {
      "title": "`[aria-hidden=\"true\"]` elements do not contain focusable descendents",
      "score": 1
      // ...
    },
    // ...
  }

Gathering metrics from a single audit​

You can get any specific metrics valid in Lighthouse

{
  "url": "https://browserless.io",
  "config": {
    "extends": "lighthouse:default",
    "settings": {
      "onlyAudits": ["unminified-css"]
    }
  }
}

cURL request

curl --request POST \
  --url 'https://production-sfo.browserless.io/performance?token=MY_API_TOKEN' \
  --header 'Cache-Control: no-cache' \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://browserless.io",
  "config": {
    "extends": "lighthouse:default",
    "settings": {
      "onlyCategories": ["accessibility"]
    }
  }
}'

Response example

  // ...
  "audits": {
    "unminified-css": {
      "title": "Minify CSS",
      "score": 1
      // ...
    },
    // ...
  }