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 your API tokens under the Tokens tab in the dashboard if your plan supports API access.

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 Check

POST/v1/lighthouse/checks

Create Lighthouse Check to test a URL from multiple regions

Request Body

urlstring
required
Description:

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

Example:
https://example.com
regionsarray
required
Description:

The regions to test from

Example:
[ "us-east4", "us-west1" ]
Possible Values:
  • 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
  • australia-southeast1
versionstring
optional
Description:

The version of Lighthouse to use. Defaults to the most recent version (recommended)

Possible Values:
  • 12.1.0
  • 12.0.0
  • 11.7.1
  • 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
  • 10.0.2
devicestring
optional
Description:

The device type Lighthouse should emulate

Example:
mobile
Possible Values:
  • desktop
  • mobile
headersobject
optional
Description:

Custom headers to send with the request

Example:
{ "Authorization": "eyJhbGciOiJIUzI1NiIsInR5cI..." }
Request Example
Request Body
{
  "url": "https://example.com",
  "regions": [
    "us-east4",
    "us-west1"
  ]
}
Response Example
201Created Lighthouse Check
Response Body
{
  "id": "0be76dba-2bbe-4a8b-9134-7451a265adee",
  "version": "12.1.0",
  "device": "mobile",
  "url": "https://example.com",
  "regions": [
    "us-east4",
    "us-west1"
  ],
  "runs": [
    {
      "id": "41f1089d-454a-4a84-890d-db5986d7e911",
      "region": "us-east4",
      "createdAt": 1707649200000
    }
  ],
  "createdAt": 1707649200000
}

Get Lighthouse Check

GET/v1/lighthouse/checks/:checkId

Get a dedicated Lighthouse Check by ID

Path Parameters
checkIdstring
required
Description:

The ID of the Lighthouse Check

Response Example
200Lighthouse Check
Response Body
{
  "id": "0be76dba-2bbe-4a8b-9134-7451a265adee",
  "version": "12.1.0",
  "url": "https://example.com",
  "device": "mobile",
  "regions": [
    "us-east4",
    "us-west1"
  ],
  "headers": {
    "Authorization": "eyJhbGciOiJIUzI1NiIsInR5cI..."
  },
  "runs": [
    {
      "id": "41f1089d-454a-4a84-890d-db5986d7e911",
      "version": "12.1.0",
      "url": "https://example.com",
      "region": "us-east4",
      "state": "succeeded",
      "performance": 90,
      "accessibility": 90,
      "bestPractices": 90,
      "seo": 90,
      "fcp": 1000,
      "si": 788,
      "lcp": 788,
      "tti": 788,
      "tbt": 0,
      "cls": 0.1,
      "createdAt": 1707649200000
    }
  ],
  "createdAt": 1707649200000
}

Lighthouse Monitors

Monitors allow you to continuously test a URL in a specific region over time.

List Lighthouse Monitors

GET/v1/lighthouse/monitors

Get a list of Lighthouse Monitors

Query Parameters
pagestring
optional
Description:

Page number

Example:
1
limitstring
optional
Description:

Number of entries per page

Example:
25
Response Example
200List of Lighthouse Monitors
Response Body
{
  "data": [
    {
      "id": "2834eaf0-8a8e-4212-9837-240af24d1d97",
      "name": "Example Monitor",
      "url": "https://example.com",
      "version": "12.1.0",
      "region": "us-east4",
      "device": "mobile",
      "updatedAt": 1707649200000,
      "createdAt": 1707649200000
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "links": {
      "prev": null,
      "next": "https://api.lighthouse-metrics.com/v1/lighthouse/checks?page=2"
    }
  }
}

Get Lighthouse Monitor

GET/v1/lighthouse/monitors/:monitorId

Get a dedicated Lighthouse Monitor by ID

Path Parameters
monitorIdstring
required
Description:

Example:
2834eaf0-8a8e-4212-9837-240af24d1d97
Response Example
200Lighthouse Monitor
Response Body
{
  "id": "2834eaf0-8a8e-4212-9837-240af24d1d97",
  "name": "Example Monitor",
  "url": "https://example.com",
  "version": "12.1.0",
  "region": "us-east4",
  "device": "mobile",
  "updatedAt": 1707649200000,
  "createdAt": 1707649200000
}

List Lighthouse Runs for Monitor

GET/v1/lighthouse/monitors/:monitorId/runs

Get Lighthouse Runs for a specific Lighthouse Monitor

Path Parameters
monitorIdstring
required
Description:

Example:
2834eaf0-8a8e-4212-9837-240af24d1d97
Query Parameters
pagestring
optional
Description:

Page number

Example:
1
limitstring
optional
Description:

Number of entries per page

Example:
25
Response Example
200List of Lighthouse Runs
Response Body
{
  "data": [
    {
      "id": "41f1089d-454a-4a84-890d-db5986d7e911",
      "region": "us-east4",
      "state": "succeeded",
      "createdAt": 1707649200000
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "links": {
      "prev": null,
      "next": "https://api.lighthouse-metrics.com/v1/lighthouse/monitors/2834eaf0-8a8e-4212-9837-240af24d1d97/runs?page=2"
    }
  }
}

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/v1/lighthouse/runs/:runId

Get Lighthouse Runs

Path Parameters
runIdstring
required
Description:

The ID of the Lighthouse Run

Response Example
200Lighthouse Run
Response Body
{
  "id": "41f1089d-454a-4a84-890d-db5986d7e911",
  "version": "12.1.0",
  "url": "https://example.com",
  "device": "mobile",
  "region": "us-east4",
  "state": "succeeded",
  "performance": 90,
  "accessibility": 90,
  "bestPractices": 90,
  "seo": 90,
  "fcp": 1000,
  "si": 788,
  "lcp": 788,
  "tti": 788,
  "tbt": 0,
  "cls": 0.1,
  "createdAt": 1707649200000
}

Get Lighthouse Report

GET/v1/lighthouse/runs/:runId/report

Get Lighthouse Report

Path Parameters
runIdstring
required
Description:

The ID of the Lighthouse Run

Response Example
200Generated Lighthouse Report
Response Body
{
  "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.