SpeedVitals API

Run a lighthouse test

POST /v1/lighthouse-tests

Api key

Runs a new lighthouse test.

Body

This is the lighthouse test body object

url string

The url of webpage
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.
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 report to be returned
- id string
- url string Required
- device string Required
  
  Values are mobile, desktop, macbookAirM1, highEndLaptop, ipad102, galaxyTabS7, iphone13ProMax, iphone11, galaxyS10Plus, redmiNote8Pro, iphone7, galaxyA50, galaxyJ8, motoG5, or redmi5A.
- location string Required
  
  Values are us, ca, br, de, uk, nl, pl, ch, jp, in, sg, au, id, kr, or tw.
- 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 Required
  
  Values are idle, active, success, or failed.
- lighthouse_version string Required
  
  The version of the lighthouse used to generate the report
- 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)
- created_at number
  
  Time at which the test was created. Measured in seconds since the Unix epoch.
- expires_at number
  
  Time at which the report will expire. Measured in seconds since the Unix epoch.
- 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-tests

curl \
 -X POST https://api.speedvitals.com/v1/lighthouse-tests \
 -H "X-API-KEY: $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"value":{"url":"https://speedvitals.com","device":"macbookAirM1","location":"us","config":{"connection":"fiber","video":true,"adblock":true}}}'

Request example

{
  "value": {
    "url": "https://speedvitals.com",
    "device": "macbookAirM1",
    "location": "us",
    "config": {
      "connection": "fiber",
      "video": true,
      "adblock": true
    }
  }
}

Response example (201)

{
  "value": {
    "url": "https://speedvitals.com",
    "device": "macbookAirM1",
    "location": "us",
    "config": {
      "connection": "fiber",
      "video": true,
      "adblock": true
    },
    "status": "success",
    "lighthouse_version": "9.6.2",
    "metrics": null,
    "report_url": null,
    "created_at": 1657537268453,
    "expires_at": 1660129268453,
    "error": null
  }
}

Response example (400)

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

Response example (402)

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