Performance API
Run Lighthouse audits and return metrics for accessibility, best practices, performance, PWA, and SEO. Includes latency, time-to-interaction, design contrast, and other recommendations.
Endpoint
- Method:
POST - Path:
/performance - Auth:
tokenquery parameter (?token=) - Content-Type:
application/json - Response:
application/json
See the OpenAPI reference for complete details.
- A Browserless API token from your account dashboard
Quickstart
- cURL
- Javascript
- Python
curl -X POST \
"https://production-sfo.browserless.io/performance?token=YOUR_API_TOKEN_HERE" \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
"url": "https://example.com/"
}'
const TOKEN = "YOUR_API_TOKEN_HERE";
const url = `https://production-sfo.browserless.io/performance?token=${TOKEN}`;
const headers = {
"Cache-Control": "no-cache",
"Content-Type": "application/json"
};
const data = {
url: "https://example.com/"
};
const fetchPerformanceMetrics = async () => {
const response = await fetch(url, {
method: 'POST',
headers: headers,
body: JSON.stringify(data)
});
const result = await response.json();
console.log(result);
};
fetchPerformanceMetrics();
import requests
TOKEN = "YOUR_API_TOKEN_HERE"
url = f"https://production-sfo.browserless.io/performance?token={TOKEN}"
headers = {
"Cache-Control": "no-cache",
"Content-Type": "application/json"
}
data = {
"url": "https://example.com/"
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result)
Response
// ...
"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"
// ...
}
// ...
}
Each test has a score that indicates how well it performed, where 1 is the maximum and 0 is the lowest.
Due to the number of checks gathered, requests can take anywhere from several seconds to minutes depending on the site and worker size.
Examples
By default, the /performance API will gather all the metrics. This will result in a really big JSON response (350kb to 800kb on average) and it will take some seconds (to minutes) to complete.
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
curl --request POST \
--url 'https://production-sfo.browserless.io/performance?token=YOUR_API_TOKEN_HERE' \
--header 'Cache-Control: no-cache' \
--header 'Content-Type: application/json' \
--data '{
"url": "https://www.browserless.io",
"config": {
"extends": "lighthouse:default",
"settings": {
"onlyCategories": ["accessibility"]
}
}
}'
This will gather the predefined metrics defined by Lighthouse for that category:
{
"data": {
"lighthouseVersion": "13.0.3",
"requestedUrl": "https://www.browserless.io/",
// ...
"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
curl --request POST \
--url 'https://production-sfo.browserless.io/performance?token=YOUR_API_TOKEN_HERE' \
--header 'Cache-Control: no-cache' \
--header 'Content-Type: application/json' \
--data '{
"url": "https://www.browserless.io",
"config": {
"extends": "lighthouse:default",
"settings": {
"onlyAudits": ["unminified-css"]
}
}
}'
Response example
{
"data": {
"lighthouseVersion": "13.0.3",
"requestedUrl": "https://www.browserless.io/",
// ...
"audits": {
"unminified-css": {
"title": "Minify CSS",
"score": 1
// ...
},
// ...
}
}
}
FAQ & Troubleshooting
Why am I getting a 401 Unauthorized error?
Your API token is missing or invalid. Include it as a ?token= query parameter or in the Authorization header. Verify the token in your account dashboard.
My request returns an empty response
The page may not have finished loading. Increase waitForTimeout or use waitForSelector to wait for specific content before extracting data.