Run a lighthouse test

POST /v1/lighthouse-tests

Runs a new lighthouse test.

application/json

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
    Hide config attributes Show config attributes
    • 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

    A lighthouse report to be returned

    Hide response attributes Show response attributes object
    • 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
      Hide config attributes Show config attributes
      • 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
      Hide metrics attributes Show metrics attributes
    • report_url string | null

      The URL at which SpeedVitals report is accessible (Present when status is success)

    • Time at which the test was created. Measured in seconds since the Unix epoch.

    • 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)

      Hide error attributes Show error attributes
      • code string

        Error code specific to lighthouse error

      • message string

        Error message describing the summary of lighthouse error

  • 400

    Invalid Request body or missing required parameters

    Hide response attributes Show response attributes object
    • code string

      An error code specific to the error.

    • message string

      A human-readable message providing more details about the error.

  • 402

    Insufficient Credits

    Hide response attributes Show response attributes object
    • 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 '{"url":"https://speedvitals.com","device":"macbookAirM1","location":"us","config":{"connection":"fiber","video":true,"adblock":true}}'
Request example
{
  "url": "https://speedvitals.com",
  "device": "macbookAirM1",
  "location": "us",
  "config": {
    "connection": "fiber",
    "video": true,
    "adblock": true
  }
}
Request examples
{
  "url": "string",
  "device": "macbookAirM1",
  "location": "us",
  "config": {
    "connection": "fiber",
    "throttling_method": "simulated",
    "http_version": "2",
    "video": false,
    "adblock": false,
    "user_agent": "string",
    "auth_username": "string",
    "auth_password": "string",
    "cookies": [
      "string"
    ],
    "whitelist": [
      "string"
    ],
    "blacklist": [
      "string"
    ]
  }
}
Response examples (201)
{
  "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 examples (201)
{
  "id": "lt_LthsZedDcOUfYFHxN",
  "url": "https://speedvitals.com",
  "error": null,
  "config": {
    "video": true,
    "adblock": true,
    "http_version": 2
  },
  "device": "macbookAirM1",
  "status": "idle",
  "metrics": {
    "speed_index": 1123,
    "performance_score": 99,
    "time_to_interactive": 725,
    "total_blocking_time": 69,
    "server_response_time": 21,
    "first_contentful_paint": 515,
    "first_meaningful_paint": 566,
    "cumulative_layout_shift": 0.0,
    "largest_contentful_paint": 515
  },
  "location": "us",
  "created_at": 1657537268453,
  "expires_at": 1660129268453,
  "report_url": "https://speedvitals.com/report/speedvitals.com/Q6qWx6/",
  "lighthouse_version": "9.6.2"
}
Response examples (400)
{
  "code": "string",
  "message": "string"
}
Response examples (400)
{
  "code": "string",
  "message": "string"
}
Response examples (402)
{
  "code": "string",
  "message": "string"
}
Response examples (402)
{
  "code": "string",
  "message": "string"
}