> For the complete documentation index, see [llms.txt](/llms.txt)
# 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: `token` query parameter (`?token=`)
- Content-Type: `application/json`
- Response: `application/json`
See the [OpenAPI reference](/open-api/chrome-performance) for complete details.
- A Browserless API token from your [account dashboard](https://browserless.io/account/)
## Quickstart
**cURL:**
```sh
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/"
}'
```
**Javascript:**
```js
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();
```
**Python:**
```python
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**
```text
// ...
"audits": {
"is-on-https": {
"title": "Uses HTTPS",
"score": 1
// ...
},
"viewport": {
"title": "Has a `` 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.
> **Warning**
> 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](https://github.com/GoogleChrome/lighthouse/blob/master/readme.md#cli-options), available categories are `accessibility`, `best practices`, `performance`, `pwa`, and `seo`
```sh
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:
```json
{
"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 ``",
"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](https://github.com/GoogleChrome/lighthouse/tree/master/core/audits)
```sh
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**
```json
{
"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](https://browserless.io/account/).
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.
## Next steps
REST API overview
introduction to all available endpoints
API playground
test endpoints interactively