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 for complete details.

Quickstart

{
  "url": "https://example.com/"
}

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)

import java.io.*;
import java.net.URI;
import java.net.http.*;

public class FetchPerformanceMetrics {
    public static void main(String[] args) {
        String TOKEN = "YOUR_API_TOKEN_HERE";
        String url = "https://production-sfo.browserless.io/performance?token=" + TOKEN;

        String jsonData = """
        {
            "url": "https://example.com/"
        }
        """;

        HttpClient client = HttpClient.newHttpClient();

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Cache-Control", "no-cache")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(jsonData))
            .build();

        try {
            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
            System.out.println("Response: " + response.body());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

class Program {
    static async Task Main(string[] args) {
        string TOKEN = "YOUR_API_TOKEN_HERE";
        string url = $"https://production-sfo.browserless.io/performance?token={TOKEN}";

        string jsonData = @"
        {
            ""url"": ""https://example.com/""
        }";

        using var client = new HttpClient();
        var content = new StringContent(jsonData, Encoding.UTF8, "application/json");

        try {
            var response = await client.PostAsync(url, content);
            response.EnsureSuccessStatusCode();

            var result = await response.Content.ReadAsStringAsync();
            Console.WriteLine("Response: " + result);
        } catch (Exception ex) {
            Console.WriteLine($"Error: {ex.Message}");
        }
    }
}

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.

Examples

warning

Due to the number of checks gathered, requests can take anywhere from several seconds to minutes depending on the site and worker size.

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

{
  "url": "https://example.com",
  "config": {
    "extends": "lighthouse:default",
    "settings": {
      "onlyCategories": ["accessibility"]
    }
  }
}

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://browserless.io",
  "config": {
    "extends": "lighthouse:default",
    "settings": {
      "onlyCategories": ["accessibility"]
    }
  }
}'

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://browserless.io",
  config: {
    extends: "lighthouse:default",
    settings: {
      onlyCategories: ["accessibility"]
    }
  }
};

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://browserless.io",
    "config": {
        "extends": "lighthouse:default",
        "settings": {
            "onlyCategories": ["accessibility"]
        }
    }
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

print(result)

import java.io.*;
import java.net.URI;
import java.net.http.*;

public class FetchPerformanceWithConfig {
    public static void main(String[] args) {
        String TOKEN = "YOUR_API_TOKEN_HERE";
        String url = "https://production-sfo.browserless.io/performance?token=" + TOKEN;

        String jsonData = """
        {
            "url": "https://browserless.io",
            "config": {
                "extends": "lighthouse:default",
                "settings": {
                    "onlyCategories": ["accessibility"]
                }
            }
        }
        """;

        HttpClient client = HttpClient.newHttpClient();

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Cache-Control", "no-cache")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(jsonData))
            .build();

        try {
            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
            System.out.println("Response: " + response.body());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

class Program {
    static async Task Main(string[] args) {
        string TOKEN = "YOUR_API_TOKEN_HERE";
        string url = $"https://production-sfo.browserless.io/performance?token={TOKEN}";

        string jsonData = @"
        {
            ""url"": ""https://browserless.io"",
            ""config"": {
                ""extends"": ""lighthouse:default"",
                ""settings"": {
                    ""onlyCategories"": [""accessibility""]
                }
            }
        }";

        using var client = new HttpClient();
        var content = new StringContent(jsonData, Encoding.UTF8, "application/json");

        try {
            var response = await client.PostAsync(url, content);
            response.EnsureSuccessStatusCode();

            var result = await response.Content.ReadAsStringAsync();
            Console.WriteLine("Response: " + result);
        } catch (Exception ex) {
            Console.WriteLine($"Error: {ex.Message}");
        }
    }
}

This will gather the predefined metrics defined by Lighthouse for that category:

  // ...
  "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

{
  "url": "https://browserless.io",
  "config": {
    "extends": "lighthouse:default",
    "settings": {
      "onlyAudits": ["unminified-css"]
    }
  }
}

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://browserless.io",
  "config": {
    "extends": "lighthouse:default",
    "settings": {
      "onlyCategories": ["accessibility"]
    }
  }
}'

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://browserless.io",
  config: {
    extends: "lighthouse:default",
    settings: {
      onlyCategories: ["accessibility"]
    }
  }
};

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://browserless.io",
    "config": {
        "extends": "lighthouse:default",
        "settings": {
            "onlyCategories": ["accessibility"]
        }
    }
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

print(result)

import java.io.*;
import java.net.URI;
import java.net.http.*;

public class FetchPerformanceWithConfig {
    public static void main(String[] args) {
        String TOKEN = "YOUR_API_TOKEN_HERE";
        String url = "https://production-sfo.browserless.io/performance?token=" + TOKEN;

        String jsonData = """
        {
            "url": "https://browserless.io",
            "config": {
                "extends": "lighthouse:default",
                "settings": {
                    "onlyCategories": ["accessibility"]
                }
            }
        }
        """;

        HttpClient client = HttpClient.newHttpClient();

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Cache-Control", "no-cache")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(jsonData))
            .build();

        try {
            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
            System.out.println("Response: " + response.body());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

class Program {
    static async Task Main(string[] args) {
        string TOKEN = "YOUR_API_TOKEN_HERE";
        string url = $"https://production-sfo.browserless.io/performance?token={TOKEN}";

        string jsonData = @"
        {
            ""url"": ""https://browserless.io"",
            ""config"": {
                ""extends"": ""lighthouse:default"",
                ""settings"": {
                    ""onlyCategories"": [""accessibility""]
                }
            }
        }";

        using var client = new HttpClient();
        var content = new StringContent(jsonData, Encoding.UTF8, "application/json");

        try {
            var response = await client.PostAsync(url, content);
            response.EnsureSuccessStatusCode();

            var result = await response.Content.ReadAsStringAsync();
            Console.WriteLine("Response: " + result);
        } catch (Exception ex) {
            Console.WriteLine($"Error: {ex.Message}");
        }
    }
}

Response example

  // ...
  "audits": {
    "unminified-css": {
      "title": "Minify CSS",
      "score": 1
      // ...
    },
    // ...
  }

Quickstart​

Examples​

Gathering Metrics for a Category​

Gathering metrics from a single audit​

Quickstart

Examples

Gathering Metrics for a Category

Gathering metrics from a single audit