The Lighthouse Metrics API gives you access to a scalable way of creating Lighthouse reports and getting reliable performance metrics.
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.
Per default each endpoint has a specific rate limit. If you exceed it, you will receive a HTTP status code 429.
The API exposes a variety of endpoints under the URL https://api.lighthouse-metrics.com
and generally follows the REST architecture.
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.
Creates a check that runs tests in multiple regions at once
The url to test, starting with http://
or https://
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
Specifies the device type that should be used. Defaults to mobile
.
Available options:
mobile
and desktop
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
{ "url": "https://www.example.com", "regions": [ "us-west1" ] }
{ "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" } ] }
Gets a check with its runs
The id of the check
{ "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 } ] }
Runs are automatically created for each specified region during the a check creation. Each run contains common metrics from the full Lighthouse report.
Get a specific run
The id of the run
{ "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 }
Gets the full Lighthouse report for a specific run
The id of the run
{ "gatherMode": "...", "userAgent": "...", "environment": "...", "lighthouseVersion": "...", "fetchTime": "...", "...": "..." }
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.