Api key (http_api_key)
Send an authentication token in the
X-API-KEY
header
to authenticate with the API.
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.
https://api.speedvitals.com
Send an authentication token in the
X-API-KEY
header
to authenticate with the API.
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:
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 |
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 |
curl \
-X GET https://api.speedvitals.com/ping
"pong"
curl \
-X GET https://api.speedvitals.com/v1/devices
{
"data": [
{
"id": "macbookAirM1",
"name": "MacBook Air (2020)",
"category": "desktop"
},
{
"id": "iphone13ProMax",
"name": "iPhone 13 Pro Max",
"category": "mobile"
},
"{...}",
"{...}"
]
}
Device id
curl \
-X GET https://api.speedvitals.com/v1/devices/{id}
{
"id": "macbookAirM1",
"name": "MacBook Air (2020)",
"category": "desktop"
}
curl \
-X GET https://api.speedvitals.com/v1/locations
{
"data": [
{
"id": "us",
"name": "United States",
"full_name": "South Carolina, US",
"region": "America"
},
{
"id": "de",
"name": "Germany",
"full_name": "Frankfurt, Germany",
"region": "Europe"
},
"{...}",
"{...}"
]
}
Location id
curl \
-X GET https://api.speedvitals.com/v1/locations/{id}
{
"id": "us",
"name": "United States",
"full_name": "South Carolina, US",
"region": "America"
}
Returns a list of your lighthouse tests. The tests are returned sorted by creation date, with the most recently created test appearing first.
The page number to return. The default page number is 1.
A size of the number of objects to be returned. Page size can range between 1 and 100, and the default is 10.
Filter tests where the created_at field is greater than this value
Filter tests where the created_at field is greater than this value.
Filter tests where the created_at field is less than this value.
Filter tests where the created_at field is less than or equal to this value.
curl \
-X GET https://api.speedvitals.com/v1/lighthouse-tests \
-H "X-API-KEY: $API_KEY"
{
"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
},
"{...}",
"{...}"
]
}
{
"code": "string",
"message": "string"
}
This is the lighthouse test body object
The url of webpage
Values are mobile
, desktop
, macbookAirM1
, highEndLaptop
, ipad102
, galaxyTabS7
, iphone13ProMax
, iphone11
, galaxyS10Plus
, redmiNote8Pro
, iphone7
, galaxyA50
, galaxyJ8
, motoG5
, or redmi5A
.
Values are us
, ca
, br
, de
, uk
, nl
, pl
, ch
, jp
, in
, sg
, au
, id
, kr
, or tw
.
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}}'
{
"url": "https://speedvitals.com",
"device": "macbookAirM1",
"location": "us",
"config": {
"connection": "fiber",
"video": true,
"adblock": true
}
}
{
"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
}
{
"code": "string",
"message": "string"
}
{
"code": "string",
"message": "string"
}
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.
curl \
-X GET https://api.speedvitals.com/v1/lighthouse-tests/lt_LthsZedDcOUfYFHxN \
-H "X-API-KEY: $API_KEY"
{
"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
}
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.
Values are pdf
, har
, or video
.
curl \
-X GET https://api.speedvitals.com/v1/lighthouse-tests/{id}/resources/{resource_name} \
-H "X-API-KEY: $API_KEY"
{}
This is the lighthouse batch test body object
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
.
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
.
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
.
The type of batch test to run
Values are multiple-urls
, multiple-devices
, or multiple-locations
.
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"}'
{
"urls": [
"https://speedvitals.com",
"https://blog.speedvitals.com"
],
"devices": [
"macbookAirM1"
],
"locations": [
"us"
],
"batch_type": "multiple-urls"
}
{
"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
}
{
"code": "string",
"message": "string"
}
{
"code": "string",
"message": "string"
}
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.
curl \
-X GET https://api.speedvitals.com/v1/lighthouse-batch-tests/{id} \
-H "X-API-KEY: $API_KEY"
{
"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
}
]
}
Returns a list of SpeedVitals supported regions for TTFB test
curl \
-X GET https://api.speedvitals.com/v1/ttfb-regions
{
"data": [
{
"id": "asia",
"name": "Asia Pacific and Africa",
"locations": [
{
"id": "del",
"name": "Delhi"
},
{
"id": "sgp",
"name": "Singapore"
},
"{...}",
"{...}"
]
},
"{...}",
"{...}"
]
}
Region id
curl \
-X GET https://api.speedvitals.com/v1/ttfb-regions/{id}
{
"id": "asia",
"name": "Asia Pacific and Africa",
"locations": [
{
"id": "del",
"name": "Delhi"
},
{
"id": "sgp",
"name": "Singapore"
},
"{...}",
"{...}"
]
}
This is the TTFB test body object
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"}'
{
"url": "https://speedvitals.com",
"region": "asia"
}
{
"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
},
"{...}",
"{...}"
]
}
{
"code": "string",
"message": "string"
}
{
"code": "string",
"message": "string"
}
curl \
-X GET https://api.speedvitals.com/v1/account/credits \
-H "X-API-KEY: $API_KEY"
{
"lighthouse": {
"available_credits": 100,
"available_paid_credits": 0
},
"ttfb": {
"available_credits": 32,
"available_paid_credits": 0
},
"credits_refill_date": 1657535713
}