POST /v3/on_page/lighthouse/task_post – DataForSEO API documentation

OnPage

Changed on Jul 22, 2026

‌The OnPage Lighthouse API is based on Google’s open-source Lighthouse project for measuring the quality of web pages and web apps.

post/v3/on_page/lighthouse/task_post

Request

Base URL: https://api.dataforseo.com
URL: https://api.dataforseo.com/v3/on_page/lighthouse/task_post
Auth: HTTP basic

Request body

urlstring

target URL required field target page should be specified with its absolute URL (including http:// or https://) example: <code>https://dataforseo.com/</code>

for_mobileboolean nullable

applies mobile emulation optional field if set to <code>true</code>, Lighthouse will use mobile device and screen emulation to test the page against mobile environment if set to <code>false</code>, the results will be provided for desktop default value: <code>false</code>

categoriesstring[] nullable

categories of Lighthouse audits optional field each category is a collection of audits and audit groups that applies weighting and scoring to the section (<a href="https://github.com/GoogleChrome/lighthouse/blob/master/docs/architecture.md#auditreport-terminology" target="_blank" rel="noopener noreferrer">see official definition</a>)if you ignore this field, we will return data for all categories unless you specify <code>audits</code> use this field to get data for specific categories you indicate herepossible values: <code>seo</code>, <code>performance</code>, <code>best_practices</code>, <code>accessibility</code>

auditsstring[] nullable

Lighthouse audits optional field audits are individual tests Lighthouse runs for each specific feature/optimization/metric to produce a numeric score (<a href="https://github.com/GoogleChrome/lighthouse/blob/master/docs/architecture.md#components--terminology" target="_blank" rel="noopener noreferrer">see official definition</a>)if you ignore this field, we will return data for all audits use this field to get data for specific audits you indicate herenote that some audits do not belong to a specific category and are stand-alone page quality measurementsin general, there can be several use cases:1. if you ignore <code>categories</code>, you can use this field to get data for the specified audits only for example, if you ignore <code>"categories"</code> and specify <code>"audits": ["metrics/cumulative-layout-shift","metrics/largest-contentful-paint","metrics/total-blocking-time"]</code>, you will get data only for these audits2. if you specify a category, you can use this field to additionally receive audits that do not belong to the category(-ies) you specified for example, if you specify <code>"categories": ["seo"]</code> and <code>"audits": ["metrics/cumulative-layout-shift","metrics/largest-contentful-paint","metrics/total-blocking-time"]</code>, you will get only these audits under "performance" and all audits under "seo"you can get <a href="/v3/on_page/lighthouse/audits/">the full list of possible audits here</a>

versionstring nullable

lighthouse version optional field you can obtain the results specific to a certain Lighthouse version by specifying its number the list of available versions is available through the <a href="/v3/on_page/lighthouse/versions/" target="_blank" rel="noopener noreferrer">Lighthouse Versions endpoint</a>

language_namestring nullable

lighthouse language name optional field you can receive the list of available languages of the search engine with their <code>language_name</code> by making a separate request to <code>https://api.dataforseo.com/v3/on_page/lighthouse/languages</code> default value: <code class="long-string">English</code>

language_codestring nullable

lighthouse language code optional field you can receive the list of available languages of the search engine with their <code>language_code</code> by making a separate request to <code>https://api.dataforseo.com/v3/on_page/lighthouse/languages</code> default value: <code class="long-string">en</code>

custom_user_agentstring nullable

custom user agent optional field specify the custom user agent used by the browser when running the Lighthouse audit; can be specified with up to 254 characters;

browser_screen_widthinteger nullable

browser screen width optional field set the screen width of the browser used for the Lighthouse audit to emulate a specific device; can be specified within the following range: <code>240–9999</code>;

browser_screen_heightinteger nullable

browser screen height optional field set the screen height of the browser used for the Lighthouse audit to emulate a specific device; can be specified within the following range: <code>240–9999</code>;

browser_screen_scale_factornumber nullable

browser screen scale factor optional field set the device pixel ratio of the browser used for the Lighthouse audit; can be specified within the following range: <code>0.5–3</code>;

browser_network_throttling_methodstring nullable

browser network throttling method optional field defines the method used to apply throttling during the Lighthouse audit; possible vaules: <code>simulate</code> - calculates estimated performance metrics without applying explicit throttling; <code>devtools</code> - applies the throttling settings specified in <code>browser_network_throttling</code> and <code>browser_cpu_throttling_multiplier</code>; <code>provided</code> - uses the network conditions of the crawling environment;

browser_cpu_throttling_multipliernumber nullable

browser CPU throttling multiplier required if <code>browser_network_throttling_method</code> is set to <code>devtools</code>; set the CPU throttling multiplier to simulate device performance conditions during the Lighthouse audit; can be specified within the following range: <code>1–4</code>; Note: this parameter is applied only when <code>browser_network_throttling_method</code> is set to <code>devtools</code>;

browser_network_throttlingstring nullable

browser network throttling required if <code>browser_network_throttling_method</code> is set to <code>devtools</code>; set the network throttling profile to simulate connection speed conditions during the Lighthouse audit; possible values: <code>no_throttling</code>, <code>fast_4g</code>, <code>slow_4g</code>, <code>regular_3g</code>, <code>pc</code>; Note: this parameter is applied only when <code>browser_network_throttling_method</code> is set to <code>devtools</code>;

tagstring nullable

user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified <code>tag</code> value in the <code>data</code> object of the response

pingback_urlstring nullable

notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a <code>$id</code> variable and ‘$tag’ as urlencoded <code>$tag</code> variable. We will set the necessary values before sending the request. example: <code>http://your-server.com/pingscript?id=$id</code> <code>http://your-server.com/pingscript?id=$id&tag=$tag</code> Note: special characters in <code>pingback_url</code> will be urlencoded; i.a., the <code>#</code> character will be encoded into <code>%23</code>learn more on our <a href="https://dataforseo.com/help-center/pingbacks-postbacks-with-dataforseo-api" target="_blank" rel="noopener noreferrer">Help Center</a>

Example request

[
  {
    "url": "https://dataforseo.com",
    "for_mobile": true,
    "tag": "some_string_123",
    "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
  }
]

Response

Successful operation

versionstring nullable

the current version of the API

status_codeinteger nullable

general status code you can find the full list of the response codes here

status_messagestring nullable

general informational message you can find the full list of general informational messages here

timestring nullable

total execution time, seconds

costnumber double nullable

total tasks cost, USD

tasks_countinteger nullable

the number of tasks in the tasks array

tasks_errorinteger nullable

the number of tasks in the tasks array returned with an error

Changes

Jul 22, 20265ca55b1d9811 Revision changes
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new optional request property /////
Mar 30, 20266061f0e837b7 Revision changes
- warning
  removed the request property /////

Operation history (4 revisions)