What is the Lighthouse API for and how to use it?

What is the Lighthouse API for and how to use it?

The Lighthouse API runs Google’s open-source Lighthouse tool against a URL you specify and returns the full report as JSON. This API is part of our OnPage API, but it works differently from the rest of its endpoints. A regular OnPage crawl analyzes a website and checks on-page parameters across numerous pages. Lighthouse opens one page in a headless Chrome browser, records what happens during the load, and scores that page against a set of audits.

What the API is for

Lighthouse tells you how the page behaves once a browser renders it, and whether it follows the performance, accessibility, SEO, and security recommendations that you cannot check in raw HTML.

In particular, the Lighthouse API can be used to:

• reproduce PageSpeed Insights style reports inside the product without maintaining Chrome instances;
• track Core Web Vitals for client pages over time;
• run accessibility or SEO checks that need a rendered DOM;
• compare how one URL performs under mobile and desktop emulation;
• audit a page under a specific viewport, user agent, or connection profile.

The result array contains the Lighthouse report itself, with the same field names and structure that the Lighthouse CLI produces. You can paste it into the Lighthouse Report Viewer or parse it directly.

How a single audit runs

Every request to the Lighthouse API loads the target URL once in a clean headless Chrome session, with storage cleared and no warm cache. Lighthouse records a trace of that load and then runs the individual audits against it.

An audit is a single test that returns a score, a numeric value, or an informative verdict without a score. A category is a weighted group of audits, and its score is the weighted average of the audits inside it. Scores use a 0 to 1 scale, so 0.62 in the response is 62 in the Lighthouse interface.

Categories and individual audits

Two optional parameters control the API’s output.

The categories parameter accepts available categories: seo, performance, best_practices and accessibility. The audits parameter accepts individual audit identifiers, and you can retrieve the full list for free using the Lighthouse Audits endpoint:

GET https://api.dataforseo.com/v3/on_page/lighthouse/audits

The list includes over 150 identifiers. Many feature a group prefix like metrics/largest-contentful-paint, seo/canonical, accessibility/color-contrast, or insights/lcp-breakdown-insight. In your request, only include the prefix part. Responses are organized with the audits object keyed by the segment after the slash, so metrics/largest-contentful-paint appears as largest-contentful-paint.

If you specify neither parameter, you will receive results for every category and every audit. If you specify only the audits parameter, you get results just for the specified audits. In case you specify both parameters, you get all the audits in the categories you listed plus the extra audits you specified separately.

Some audits are not assigned to any category and appear as standalone measurements. If you request only a few audits, the category block still shows, but its score reflects only the audits that were executed, so it may differ from a full-category run.

Throttling and device emulation

The most surprising numbers come from this setting. Lighthouse does not measure the page under your own connection conditions. By default, it models a mid-tier mobile device on a throttled 4G connection, and every response includes the applied configuration in the configSettings object:

"configSettings": {
  "formFactor": "mobile",
  "throttling": {
    "rttMs": 150,
    "throughputKbps": 1638.4,
    "requestLatencyMs": 562.5,
    "downloadThroughputKbps": 1474.56,
    "uploadThroughputKbps": 675,
    "cpuSlowdownMultiplier": 4
  },
  "throttlingMethod": "simulate",
  "screenEmulation": {
    "mobile": true,
    "width": 412,
    "height": 823,
    "deviceScaleFactor": 1.75
  }
}

However, you can apply custom throttling conditions by using the optional browser_network_throttling_method parameter.

This parameter allows for selecting between three throttling methods:

• simulate is the default method. The page loads without artificial limits, and Lighthouse then recalculates the metrics on a model of the target device and network.
• devtools applies real throttling through the DevTools protocol. It requires setting the browser_network_throttling parameter (possible values: no_throttling, fast_4g, slow_4g, regular_3g, pc) and the browser_cpu_throttling_multiplier to a value between 1 and 4.
• provided applies no throttling and reports the raw conditions of the crawling environment.

The device emulation works separately. The for_mobile parameter allows you to switch between the mobile and desktop profiles, while the browser_screen_width, browser_screen_height, browser_screen_scale_factor, and custom_user_agent parameters let you emulate a specific device.

Due to default throttling, results often appear slower than what you see in your browser, and they may not match real user field data. Lighthouse performs a lab test with a deliberately harsher environment than an average visitor’s connection.

Running an audit

In Standard mode, you assign a task, wait for its completion, and then collect it:

POST https://api.dataforseo.com/v3/on_page/lighthouse/task_post

You can check the IDs of completed tasks using the Tasks Ready endpoint. The results are collected through the Task GET endpoint. If you specify pingback_url or postback_url, we notify you or deliver the results as soon as the task is done.

Request example:

[
  {
    "url": "https://dataforseo.com/",
    "for_mobile": true,
    "categories": ["performance", "seo"],
    "tag": "homepage_weekly"
  }
]

In Live mode, you get the report in the same API response:

POST https://api.dataforseo.com/v3/on_page/lighthouse/live/json

A single Task POST call can carry up to 100 tasks, while a Live call carries one. Both modes allow up to 2000 API calls per minute and 30 simultaneous requests. Live requests time out after 120 seconds if Lighthouse cannot finish the page. Unlike our other APIs, Lighthouse charges the same price for Standard Queue and Live Mode.

Why the same page returns different numbers

It’s common for repeat measurements of the same URL not to match exactly. For example, two Live requests sent to the same page roughly a minute apart, using the same settings, produced the following results:

Request example:

[
  {
    "url": "https://dataforseo.com/",
    "for_mobile": true,
    "audits": [
      "metrics/largest-contentful-paint",
      "metrics/cumulative-layout-shift",
      "metrics/total-blocking-time"
    ]
  }
]

Selected metrics, compared:

 
Four things can cause that difference:

• Each request measures a single page load rather than an average across many. Timing metrics such as LCP, Speed Index, and Total Blocking Time depend on when individual resources arrive and how busy the main thread is at that moment. Layout and structural audits are much steadier, as the CLS column above shows.
• The machine running Chrome is shared. CPU contention shifts the baseline used by the simulated throttling model for calibration. Lighthouse reports this baseline as benchmarkIndex in the environment object.
• The page changes with each request due to differences in third-party scripts, ad slots, A/B tests, CDN cache status, and origin load.
• Lighthouse revises scoring weights, metric definitions, and the audit list between releases. A score that drops right after a version bump often means the scoring changed, and the page did not.

For comparable numbers, keep the request parameters the same across runs and specify the identical Lighthouse version. Run the audit several times and use the median rather than trusting a single result. Weekly trends will tell you more than any single measurement.

Versions and languages

You can get available Lighthouse versions and languages using the respective endpoints:

➤ The Lighthouse Versions endpoint returns the supported Lighthouse versions, with one flagged as default. While making a request to the Lighthouse API, you can pass a specific version number using the version parameter when you need a stable basis for comparison over time.

➤ The Lighthouse Languages endpoint returns available language settings. The language_code and language_name parameters allow you to localize audit titles and descriptions in the report. The language parameters don’t affect the measurements.

You can find the full parameter reference in the OnPage Lighthouse API documentation. In addition, you can also test the Lighthouse endpoints in our Sandbox before spending credits.