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 your API tokens under the Tokens tab in the dashboard if your plan supports API access.
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.
Create Lighthouse Check to test a URL from multiple regions
The URL to test, starting with http:// or https://
The regions to test from
The version of Lighthouse to use. Defaults to the most recent version (recommended)
The device type Lighthouse should emulate
Custom headers to send with the request
{
"url": "https://example.com",
"regions": [
"us-east4",
"us-west1"
]
}{
"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 a dedicated Lighthouse Check by ID
The ID of the Lighthouse Check
{
"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
}Monitors allow you to continuously test a URL in a specific region over time.
Get a list of Lighthouse Monitors
Page number
Number of entries per page
{
"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 a dedicated Lighthouse Monitor by ID
{
"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
}Get Lighthouse Runs for a specific Lighthouse Monitor
Page number
Number of entries per page
{
"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"
}
}
}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 Runs
The ID of the Lighthouse Run
{
"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
The ID of the Lighthouse 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.