SpeedVitals API

Run a lighthouse batch test

POST /v1/lighthouse-batch-tests

Api key

Runs a new lighthouse batch test.

Body

This is the lighthouse batch test body object

urls array[string]

For multiple-urls batch type, provide an array of urls to test. For other batch types, provide a single url in array and if multiple urls are provided, only first in the list will be used for the test. All invalid urls in the array will be ignored.

Maximum length of each is 5000.
devices array[string]

For multiple-devices batch type, provide an array of device ids to test or leave it empty for testing on all preset devices. For other batch types, provide a single device id in array and if multiple device ids are provided, only first in the list will be used for the test. All invalid device ids in the array will be ignored.

Values are mobile, desktop, macbookAirM1, highEndLaptop, ipad102, galaxyTabS7, iphone13ProMax, iphone11, galaxyS10Plus, redmiNote8Pro, iphone7, galaxyA50, galaxyJ8, motoG5, or redmi5A.
locations array[string]

For multiple-locations batch type, provide an array of location ids to test or leave it empty for testing on all preset locations. For other batch types, provide just a single location id in array and if multiple location ids are provided, only first in the list will be used for the test. All invalid location ids in the array will be ignored.

Values are us, ca, br, de, uk, nl, pl, ch, jp, in, sg, au, id, kr, or tw.
batch_type string

The type of batch test to run

Values are multiple-urls, multiple-devices, or multiple-locations.
config object
- connection string | null
  
  Connection Type
  
  Maximum length is 5000. Values are fiber, cable, dsl, 5g, wifi_fast, wifi, 4g_fast, 4g, 3g_fast, 3g, 3g_slow, 2g_edge, or 2g.
- throttling_method string | null
  
  Choose between simulated throttling and applied throttling
  
  Maximum length is 5000. Default value is simulated.
- http_version string | null
  
  Force HTTP/1.1 or HTTP/2(default)
  
  Maximum length is 5000. Default value is 2.
- video boolean | null
  
  Enable page load video
  
  Maximum length is 5000. Default value is false.
- adblock boolean | null
  
  Enable Adblock
  
  Default value is false.
- user_agent string | null
  
  Run test with custom user agent
  
  Maximum length is 5000.
- auth_username string | null
  
  Username for authentication
  
  Maximum length is 5000.
- auth_password string | null
  
  Password for authentication
  
  Maximum length is 5000.
- cookies array[string] | null
  
  List of session cookies
- whitelist array[string] | null
  
  List of whitelisted urls(Max 5)
- blacklist array[string] | null
  
  List of blacklisted urls(Max 10)

Responses

• 201 object

A lighthouse batch report to be returned
- id string
- urls array[string] Required
- devices array[string] Required
  
  Values are mobile, desktop, macbookAirM1, highEndLaptop, ipad102, galaxyTabS7, iphone13ProMax, iphone11, galaxyS10Plus, redmiNote8Pro, iphone7, galaxyA50, galaxyJ8, motoG5, or redmi5A.
- locations array[string] Required
  
  Values are us, ca, br, de, uk, nl, pl, ch, jp, in, sg, au, id, kr, or tw.
- batch_type string Required
  
  Values are multiple_urls, multiple_devices, or multiple-locations.
- config object
  connection string | null
  
  Connection Type
  
  Maximum length is 5000. Values are fiber, cable, dsl, 5g, wifi_fast, wifi, 4g_fast, 4g, 3g_fast, 3g, 3g_slow, 2g_edge, or 2g.
  
  throttling_method string | null
  
  Choose between simulated throttling and applied throttling
  
  Maximum length is 5000. Default value is simulated.
  
  http_version string | null
  
  Force HTTP/1.1 or HTTP/2(default)
  
  Maximum length is 5000. Default value is 2.
  
  video boolean | null
  
  Enable page load video
  
  Maximum length is 5000. Default value is false.
  
  adblock boolean | null
  
  Enable Adblock
  
  Default value is false.
  
  user_agent string | null
  
  Run test with custom user agent
  
  Maximum length is 5000.
  
  auth_username string | null
  
  Username for authentication
  
  Maximum length is 5000.
  
  auth_password string | null
  
  Password for authentication
  
  Maximum length is 5000.
  
  cookies array[string] | null
  
  List of session cookies
  
  whitelist array[string] | null
  
  List of whitelisted urls(Max 5)
  
  blacklist array[string] | null
  
  List of blacklisted urls(Max 10)
- status string
  
  Values are idle, active, or completed.
- lighthouse_version string
  
  The version of the lighthouse used to run the tests
- report_url string
- created_at number
  
  Time at which the batch test was created. Measured in seconds since the Unix epoch.
- expires_at number
  
  Time at which the batch report will expire. Measured in seconds since the Unix epoch.
- reports array[object]
  id string
  
  url string
  
  device string
  
  Values are mobile, desktop, macbookAirM1, highEndLaptop, ipad102, galaxyTabS7, iphone13ProMax, iphone11, galaxyS10Plus, redmiNote8Pro, iphone7, galaxyA50, galaxyJ8, motoG5, or redmi5A.
  
  location string
  
  Values are us, ca, br, de, uk, nl, pl, ch, jp, in, sg, au, id, kr, or tw.
  
  status string
  
  Values are idle, active, success, or failed.
  
  metrics object | null
  
  cumulative_layout_shift number
  
  Cumulative Layout Shift
  
  first_contentful_paint number
  
  First Contentful Paint time (in milliseconds)
  
  first_meaningful_paint number
  
  First Meaningful Paint time (in milliseconds)
  
  time_to_interactive number
  
  Time to Interactive (in milliseconds)
  
  largest_contentful_paint number
  
  Largest Contentful Paint time (in milliseconds)
  
  server_response_time number
  
  TTFB (in milliseconds)
  
  speed_index number
  
  Speed Index (in milliseconds)
  
  total_blocking_time number
  
  Total Blocking time (in milliseconds)
  
  performance_score number
  
  Performance Score (in percentage)
  
  report_url string | null
  
  The URL at which SpeedVitals report is accessible (Present when status is success)
  
  error object | null
  
  Contains error code and description(present only if status is failed)
  
  code string
  
  Error code specific to lighthouse error
  
  message string
  
  Error message describing the summary of lighthouse error
• 400 object

Invalid Request body or missing required parameters
- code string
  
  An error code specific to the error.
- message string
  
  A human-readable message providing more details about the error.
• 402 object

Insufficient Credits
- code string
  
  An error code specific to the error.
- message string
  
  A human-readable message providing more details about the error.

POST /v1/lighthouse-batch-tests

curl \
 -X POST https://api.speedvitals.com/v1/lighthouse-batch-tests \
 -H "X-API-KEY: $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"value":{"urls":["https://speedvitals.com","https://blog.speedvitals.com"],"devices":["macbookAirM1"],"locations":["us"],"batch_type":"multiple-urls"}}'

Request example

{
  "value": {
    "urls": [
      "https://speedvitals.com",
      "https://blog.speedvitals.com"
    ],
    "devices": [
      "macbookAirM1"
    ],
    "locations": [
      "us"
    ],
    "batch_type": "multiple-urls"
  }
}

Response example (201)

{
  "value": {
    "id": "lbt_IU8rN0XQmIWEqGkP",
    "urls": [
      "https://speedvitals.com",
      "https://blog.speedvitals.com"
    ],
    "devices": [
      "macbookAirM1"
    ],
    "locations": [
      "us"
    ],
    "config": null,
    "batch_type": "multiple-urls",
    "status": "idle",
    "lighthouse_version": "9.6.2",
    "report_url": "https://speedvitals.com/result/afd98w0l/",
    "created_at": 1657539924734,
    "expires_at": 1660131924733,
    "reports": null
  }
}

Response example (400)

{
  "code": "string",
  "message": "string"
}

Response example (402)

{
  "code": "string",
  "message": "string"
}