SpeedVitals API
0.1.0

The SpeedVitals REST API. Please see https://docs.speedvitals.com/api for more details.

This is the documentation for version 0.1.0 of the API. Last update on Jul 22, 2022.

Base URL 
https://api.speedvitals.com

Authentication

Api key (http_api_key)

Send an authentication token in the X-API-KEY header to authenticate with the API.

Rate Limits

SpeedVitals API has a rate limit to protect our service from attacks and ensure its stability. For normal use case, the limits are quite high and wouldn't cause any issue.

There are primarily two rate limits:

  • Global rate limit: The global rate limit is the maximum number of requests that can be made in a given time period across all API endpoints. The global rate limit is 120 requests in a minute. When this exceeds, the 429 Status Code will show up along with the rate limit headers, as described in the table.
  • Concurrency limit: This rate limit applies on the number of tests running in parallel. The concurrency limit is 2 for single lighthouse test and 1 for batch lighthouse test. When this exceeds, the 429 Status Code will be returned and new test won't start until current tests finishes.

If you are facing any issues regarding rate limits, please Contact Us.

List of response headers when global rate limit exceeds:

Header Description
Retry-After The minimum time to wait in seconds before making next request
X-RateLimit-Limit The maximum number of requests available in the current time window.
X-RateLimit-Remaining The number of remaining requests in the current time window
X-RateLimit-Reset The time at which the current rate limit window resets in UTC epoch seconds

Errors

SpeedVitals uses conventional HTTP response codes to indicate the success or failure of an API request.

In general, Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that
failed given the information provided (e.g., a required parameter was omitted, lighthouse test failed,
etc.). Codes in the 5xx range indicate an error with SpeedVitals servers (these are rare).

List of common errors codes:

HTTP Status Description
401 Unauthorized
429 Rate Limit Exceeded
500 Internal Server Error
502 Server Under Maintenance

Ping

Check API status

GET /ping

Responds a pong if the API is up and running.

Responses

  • • 200 string

    Success

    Responds with a pong

GET /ping 
curl \
 -X GET https://api.speedvitals.com/ping
Response example (200) 
"pong"

Devices

List all devices

GET /v1/devices

Returns a list of SpeedVitals supported devices

Responses

  • • 200 object

    Successful response.

    • data array[object]

      An array of device objects

      • id string

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

      • name string
      • category string

        Values are mobile, desktop, or tablet.

GET /v1/devices 
curl \
 -X GET https://api.speedvitals.com/v1/devices
Response example (200) 
{
  "data": [
    {
      "id": "macbookAirM1",
      "name": "MacBook Air (2020)",
      "category": "desktop"
    },
    {
      "id": "iphone13ProMax",
      "name": "iPhone 13 Pro Max",
      "category": "mobile"
    },
    "{...}",
    "{...}"
  ]
}

Get a device

GET /v1/devices/{id}

Retrieves a device info

Path parameters

  • id string Required

    Device id

Responses

  • • 200 object

    Successful response.

    • id string

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

    • name string
    • category string

      Values are mobile, desktop, or tablet.

  • • 404

    Resource Not Found

GET /v1/devices/{id} 
curl \
 -X GET https://api.speedvitals.com/v1/devices/{id}
Response example (200) 
{
  "id": "macbookAirM1",
  "name": "MacBook Air (2020)",
  "category": "desktop"
}

Locations

List all locations

GET /v1/locations

Returns a list of SpeedVitals supported locations

Responses

  • • 200 object

    Successful response.

    • data array[object]

      An array of location objects

      • id string

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

      • name string
      • full_name string
      • region string

        Values are America, Europe, or Asia Pacific.

GET /v1/locations 
curl \
 -X GET https://api.speedvitals.com/v1/locations
Response example (200) 
{
  "data": [
    {
      "id": "us",
      "name": "United States",
      "full_name": "South Carolina, US",
      "region": "America"
    },
    {
      "id": "de",
      "name": "Germany",
      "full_name": "Frankfurt, Germany",
      "region": "Europe"
    },
    "{...}",
    "{...}"
  ]
}

Get a location

GET /v1/locations/{id}

Retrieves a location info

Path parameters

  • id string Required

    Location id

Responses

  • • 200 object

    Successful response.

    • id string

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

    • name string
    • full_name string
    • region string

      Values are America, Europe, or Asia Pacific.

  • • 404

    Resource Not Found

GET /v1/locations/{id} 
curl \
 -X GET https://api.speedvitals.com/v1/locations/{id}
Response example (200) 
{
  "id": "us",
  "name": "United States",
  "full_name": "South Carolina, US",
  "region": "America"
}

Lighthouse Tests

List all lighthouse reports

GET /v1/lighthouse-tests
Api key

Returns a list of your lighthouse tests. The tests are returned sorted by creation date, with the most recently created test appearing first.

Query parameters

  • page_number integer

    The page number to return. The default page number is 1.

  • page_size integer

    A size of the number of objects to be returned. Page size can range between 1 and 100, and the default is 10.

  • created_at[gt] integer

    Filter tests where the created_at field is greater than this value

  • created_at[gte] integer

    Filter tests where the created_at field is greater than this value.

  • created_at[lt] integer

    Filter tests where the created_at field is less than this value.

  • created_at[lte] integer

    Filter tests where the created_at field is less than or equal to this value.

Responses

  • • 200 object

    Successful response.

    • data array[object] Required
      • 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
      • 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.

GET /v1/lighthouse-tests 
curl \
 -X GET https://api.speedvitals.com/v1/lighthouse-tests \
 -H "X-API-KEY: $API_KEY"
Response example (200) 
{
  "data": [
    {
      "id": "lt_LthsZedDcOUfYFHxN",
      "url": "https://speedvitals.com",
      "device": "macbookAirM1",
      "location": "us",
      "config": {
        "http_version": 2,
        "video": true,
        "adblock": true
      },
      "status": "idle",
      "lighthouse_version": "9.6.2",
      "metrics": {
        "cumulative_layout_shift": 0.0,
        "first_contentful_paint": 515,
        "first_meaningful_paint": 566,
        "time_to_interactive": 725,
        "largest_contentful_paint": 515,
        "server_response_time": 21,
        "speed_index": 1123,
        "total_blocking_time": 69,
        "performance_score": 99
      },
      "report_url": "https://speedvitals.com/report/speedvitals.com/Q6qWx6/",
      "created_at": 1657537268453,
      "expires_at": 1660129268453,
      "error": null
    },
    "{...}",
    "{...}"
  ]
}
Response example (400) 
{
  "code": "string",
  "message": "string"
}

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
    • 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 '{"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
  }
}
Response example (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 example (400) 
{
  "code": "string",
  "message": "string"
}
Response example (402) 
{
  "code": "string",
  "message": "string"
}

Retrieve a lighthouse report

GET /v1/lighthouse-tests/{id}
Api key

Retrieves the report of lighthouse test. Supply the unique test ID from either a lighthouse test creation request or the lighthouse tests list, and SpeedVitals will return the corresponding test information.

Path parameters

  • id string Required

Responses

  • • 200 object

    Successful response.

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

  • • 404

    Resource Not Found

GET /v1/lighthouse-tests/{id} 
curl \
 -X GET https://api.speedvitals.com/v1/lighthouse-tests/lt_LthsZedDcOUfYFHxN \
 -H "X-API-KEY: $API_KEY"
Response example (200) 
{
  "id": "lt_LthsZedDcOUfYFHxN",
  "url": "https://speedvitals.com",
  "device": "macbookAirM1",
  "location": "us",
  "config": {
    "http_version": 2,
    "video": true,
    "adblock": true
  },
  "status": "idle",
  "lighthouse_version": "9.6.2",
  "metrics": {
    "cumulative_layout_shift": 0.0,
    "first_contentful_paint": 515,
    "first_meaningful_paint": 566,
    "time_to_interactive": 725,
    "largest_contentful_paint": 515,
    "server_response_time": 21,
    "speed_index": 1123,
    "total_blocking_time": 69,
    "performance_score": 99
  },
  "report_url": "https://speedvitals.com/report/speedvitals.com/Q6qWx6/",
  "created_at": 1657537268453,
  "expires_at": 1660129268453,
  "error": null
}

Get a report resource

GET /v1/lighthouse-tests/{id}/resources/{resource_name}
Api key

Retrieves the resource of lighthouse report. Supply the unique test ID from either a lighthouse test creation request or the lighthouse tests list along with resource name to get that resource.

Path parameters

Responses

  • • 200 object

    Successful response.

  • • 404

    Resource Not Found

GET /v1/lighthouse-tests/{id}/resources/{resource_name} 
curl \
 -X GET https://api.speedvitals.com/v1/lighthouse-tests/{id}/resources/{resource_name} \
 -H "X-API-KEY: $API_KEY"
Response example (200) 
{}

Lighthouse Batch Tests

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]
  • • 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 '{"urls":["https://speedvitals.com","https://blog.speedvitals.com"],"devices":["macbookAirM1"],"locations":["us"],"batch_type":"multiple-urls"}'
Request example 
{
  "urls": [
    "https://speedvitals.com",
    "https://blog.speedvitals.com"
  ],
  "devices": [
    "macbookAirM1"
  ],
  "locations": [
    "us"
  ],
  "batch_type": "multiple-urls"
}
Response example (201) 
{
  "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"
}

Retrieve a lighthouse batch report

GET /v1/lighthouse-batch-tests/{id}
Api key

Retrieves the report of lighthouse test. Supply the unique test ID from either a lighthouse test creation request or the lighthouse tests list, and SpeedVitals will return the corresponding test information.

Path parameters

  • id string Required

Responses

  • • 200 object

    Successful response.

    • 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]
  • • 404

    Resource Not Found

GET /v1/lighthouse-batch-tests/{id} 
curl \
 -X GET https://api.speedvitals.com/v1/lighthouse-batch-tests/{id} \
 -H "X-API-KEY: $API_KEY"
Response example (200) 
{
  "id": "lbt_IU8rN0XQmIWEqGkP",
  "urls": [
    "https://speedvitals.com",
    "https://blog.speedvitals.com"
  ],
  "devices": [
    "macbookAirM1"
  ],
  "locations": [
    "us"
  ],
  "batch_type": "multiple-urls",
  "config": null,
  "status": "active",
  "lighthouse_version": "9.6.2",
  "report_url": "https://speedvitals.com/result/afd98w0l/",
  "created_at": 1657539924734,
  "expires_at": 1660131924733,
  "reports": [
    {
      "id": "lt_dObdG5EW4d231hto",
      "url": "https://speedvitals.com",
      "device": "macbookAirM1",
      "location": "us",
      "status": "success",
      "metrics": {
        "cumulative_layout_shift": 0.0,
        "first_contentful_paint": 292,
        "first_meaningful_paint": 297,
        "time_to_interactive": 297,
        "largest_contentful_paint": 434,
        "server_response_time": 32,
        "speed_index": 900,
        "total_blocking_time": 0,
        "performance_score": 100
      },
      "report_url": "https://speedvitals.com/report/speedvitals.com/IvWenx/",
      "error": null
    },
    {
      "id": "lt_dmpbeQ2xk1XPh4UP",
      "url": "https://blog.speedvitals.com",
      "device": "macbookAirM1",
      "location": "us",
      "status": "idle",
      "metrics": {
        "cumulative_layout_shift": 0.0,
        "first_contentful_paint": 322,
        "first_meaningful_paint": 365,
        "time_to_interactive": 368,
        "largest_contentful_paint": 488,
        "server_response_time": 68,
        "speed_index": 1406,
        "total_blocking_time": 0,
        "performance_score": 99
      },
      "report_url": "https://speedvitals.com/report/blog.speedvitals.com/3t4lm7",
      "error": null
    }
  ]
}

TTFB Regions

List all TTFB regions

GET /v1/ttfb-regions

Returns a list of SpeedVitals supported regions for TTFB test

Responses

GET /v1/ttfb-regions 
curl \
 -X GET https://api.speedvitals.com/v1/ttfb-regions
Response example (200) 
{
  "data": [
    {
      "id": "asia",
      "name": "Asia Pacific and Africa",
      "locations": [
        {
          "id": "del",
          "name": "Delhi"
        },
        {
          "id": "sgp",
          "name": "Singapore"
        },
        "{...}",
        "{...}"
      ]
    },
    "{...}",
    "{...}"
  ]
}

Get a TTFB region

GET /v1/ttfb-regions/{id}

Retrieves a TTFB region info

Path parameters

  • id string Required

    Region id

Responses

GET /v1/ttfb-regions/{id} 
curl \
 -X GET https://api.speedvitals.com/v1/ttfb-regions/{id}
Response example (200) 
{
  "id": "asia",
  "name": "Asia Pacific and Africa",
  "locations": [
    {
      "id": "del",
      "name": "Delhi"
    },
    {
      "id": "sgp",
      "name": "Singapore"
    },
    "{...}",
    "{...}"
  ]
}

TTFB Tests

Run a TTFB test

POST /v1/ttfb-tests
Api key

Runs a new TTFB test for a region.

Body

This is the TTFB test body object

  • url string

    The url of the webpage

  • region string

    Values are asia, america, or europe.

Responses

POST /v1/ttfb-tests 
curl \
 -X POST https://api.speedvitals.com/v1/ttfb-tests \
 -H "X-API-KEY: $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"url":"https://speedvitals.com","region":"asia"}'
Request example 
{
  "url": "https://speedvitals.com",
  "region": "asia"
}
Response example (201) 
{
  "url": "https://speedvitals.com",
  "region": "america",
  "result": [
    {
      "location_id": "del",
      "location_name": "Delhi",
      "status": "success",
      "data": {
        "timings": {
          "dns_lookup": 2,
          "server_processing": 18,
          "tcp_connection": 10,
          "tls_handshake": 25,
          "total": 56,
          "ttfb": 55
        },
        "http_version": 2,
        "http_status": 200,
        "response_headers": {
          "accept-ranges": "bytes",
          "age": 520141,
          "cache-control": "max-age=604800",
          "vary": "Accept-Encoding",
          "x-cache": "HIT"
        }
      },
      "error": null
    },
    "{...}",
    "{...}"
  ]
}
Response example (400) 
{
  "code": "string",
  "message": "string"
}
Response example (402) 
{
  "code": "string",
  "message": "string"
}

Account

Check credits

GET /v1/account/credits
Api key

Fetch lighthouse and ttfb credits available in account

GET /v1/account/credits 
curl \
 -X GET https://api.speedvitals.com/v1/account/credits \
 -H "X-API-KEY: $API_KEY"
Response example (200) 
{
  "lighthouse": {
    "available_credits": 100,
    "available_paid_credits": 0
  },
  "ttfb": {
    "available_credits": 32,
    "available_paid_credits": 0
  },
  "credits_refill_date": 1657535713
}