API

The Lighthouse Metrics API gives you access to a scalable way of creating Lighthouse reports and getting reliable performance metrics.

Authentication

To properly interact with the API, you must use the Bearer authentication scheme. Each request should have the Authorization header with your API token.

You can find and manage API tokens under the Tokens tab.

Rate Limits

Per default each endpoint has a specific rate limit. If you exceed it, you will receive a HTTP status code 429.

Endpoints

The API exposes a variety of endpoints under the URL https://api.lighthouse-metrics.com and generally follows the REST architecture.

Lighthouse Checks

Checks allow you to test a specific URL in one or many regions. For each specified region you'll get a unique run that contains the result for the corresponding region.

Create Lighthouse Checks

Creates a check that runs tests in multiple regions at once

Body Parameter
url
required

The url to test, starting with http:// or https://

version

The Lighthouse version that should be used. Defaults to the most recent version.

Available versions:

11.6.0, 11.5.0, 11.4.0, 11.3.0, 11.2.0, 11.1.0, 11.0.0, 10.4.0, 10.3.0, 10.2.0, 10.1.1 and 10.0.2
device

Specifies the device type that should be used. Defaults to mobile.

Available options:
mobile and desktop

regions
required

Regions where the check should run. At least one region is required.

Available regions:

northamerica-northeast2, us-east4, us-central1, us-west1, southamerica-east1, europe-north1, europe-west2, europe-west3, europe-west6, europe-southwest1, europe-west9, me-west1, asia-south1, asia-southeast1, asia-northeast1 and australia-southeast1
POST
/v1/lighthouse/checks
Body
{
  "url": "https://www.example.com",
  "regions": [
    "us-west1"
  ]
}
Response
{
  "id": "0be76dba-2bbe-4a8b-9134-7451a265adee",
  "version": "9.6.2",
  "url": "https://www.example.com",
  "device": "mobile",
  "regions": [
    "us-west1"
  ],
  "runs": [
    {
      "id": "41f1089d-454a-4a84-890d-db5986d7e911",
      "region": "us-west1",
      "state": "created"
    }
  ]
}

Get Lighthouse Check

Gets a check with its runs

Query Parameters
id
required

The id of the check

GET
/v1/lighthouse/checks/:id
Response
{
  "id": "0be76dba-2bbe-4a8b-9134-7451a265adee",
  "version": "9.6.2",
  "url": "https://www.example.com",
  "device": "mobile",
  "regions": [
    "us-west1"
  ],
  "runs": [
    {
      "id": "41f1089d-454a-4a84-890d-db5986d7e911",
      "version": "9.6.2",
      "url": "https://www.example.com",
      "region": "us-west1",
      "state": "succeeded",
      "performance": 100,
      "accessibility": 92,
      "bestPractices": 100,
      "pwa": 30,
      "seo": 91,
      "fcp": 788,
      "si": 788,
      "lcp": 788,
      "tti": 788,
      "tbt": 0,
      "cls": 0
    }
  ]
}

Lighthouse Runs

Runs are automatically created for each specified region during the a check creation. Each run contains common metrics from the full Lighthouse report.

Get Lighthouse Run

Get a specific run

Query Parameters
id
required

The id of the run

GET
/v1/lighthouse/runs/:id
Response
{
  "id": "41f1089d-454a-4a84-890d-db5986d7e911",
  "version": "9.6.2",
  "url": "https://www.example.com",
  "device": "mobile",
  "region": "us-west1",
  "state": "succeeded",
  "performance": 100,
  "accessibility": 92,
  "bestPractices": 100,
  "pwa": 30,
  "seo": 91,
  "fcp": 788,
  "si": 788,
  "lcp": 788,
  "tti": 788,
  "tbt": 0,
  "cls": 0
}

Get Lighthouse Report

Gets the full Lighthouse report for a specific run

Query Parameters
id
required

The id of the run

GET
/v1/lighthouse/runs/:id/report
Response
{
  "gatherMode": "...",
  "userAgent": "...",
  "environment": "...",
  "lighthouseVersion": "...",
  "fetchTime": "...",
  "...": "..."
}

Issues

Please reach out if you encounter any issues or have questions. You can either use the support option on the dashboard or write an email to support@lighthouse-metrics.com.