Test runs REST API
List all runs of a load test
GET /cloud/v6/load_tests/{id}/test_runs
List all runs of a load test.
Request parameters
Name | Description | In | Required | Type |
---|---|---|---|---|
stackId | Numeric ID of the Grafana stack representing the request scope.
| header | true | integer |
$count | Include collection length in the response object as @count . | query | false | boolean |
$skip | The initial index from which to return the results. | query | false | integer |
$top | Number of results to return per page. Default: 1000 Maximum: 1000 | query | false | integer |
id | ID of the load test. | path | true | integer |
200
response
OK.
Content type:
application/json
TestRunListResponse
properties:
Name | Description | Required | Type |
---|---|---|---|
@count | Object count in the collection. | false | integer |
@nextLink | A reference to the next page of results. The property is included until there are no more pages of results to retrieve. | false | string
, format: uri |
value | List of the resulting values. | true | Array[TestRunApiModel] |
The API model for a test run.
TestRunApiModel
properties:
Name | Description | Required | Type |
---|---|---|---|
cost | Test run cost details. The cost is available only after test run validation.
| true | TestCostApiModel
|
null |
created | Date and time when the test run was started. | true | string
, format: date-time |
distribution | List of the load zones configured for the test and the corresponding distribution percentages. | true | array
|
null |
ended | Date and time when the test run ended. Unset if the test is still running. | true | string
|
null
, format: date-time |
id | ID of the test run. | true | integer |
note | User-defined note for the test run. | true | string |
options | The original options object if available. | true | object
|
null |
project_id | ID of the parent project. | true | integer |
result | Test run result. passed if there were no issues, failed if thresholds were breached, error if the execution was not completed. | true | string
|
null |
result_details | Additional information about the test run result. | true | object
|
null |
retention_expiry | Timestamp after which the test run results are deleted or null if the test run is saved. | true | string
|
null
, format: date-time |
started_by | Email of the user who started the test if started with a user token. | true | string
|
null
, format: email |
status | Current test run status. | true | string |
status_details | Details of the current test run status. | true | StatusApiModel |
status_history | List of test run status objects sorted by the enter time representing the status history. | true | Array[StatusApiModel] |
test_id | ID of the parent test. | true | integer |
Details of the test run status.
StatusApiModel
properties:
Name | Description | Required | Type |
---|---|---|---|
entered | Date and time when the test run entered the status. | true | string
, format: date-time |
extra | Extra information about the indicated status. | false | StatusExtraApiModel
|
null |
type | Type of simple test run status: created , queued , initializing , running , processing_metrics , completed or aborted . | true | string |
StatusExtraApiModel
properties:
Name | Description | Required | Type |
---|---|---|---|
by_user | Email of the user that set the status if applicable. | true | string
|
null
, format: email |
code | Service-defined error code if applicable. | true | integer
|
null |
message | Human-readable string describing the error if applicable. | true | string
|
null |
TestCostApiModel
properties:
Name | Description | Required | Type |
---|---|---|---|
breakdown | true | TestCostBreakdownApiModel | |
total_vuh | Total number of VUH charged for the test run. | true |
Breakdown details of the test cost.
TestCostBreakdownApiModel
properties:
Name | Description | Required | Type |
---|---|---|---|
browser_vuh | Number of VUH charged for the browser part of the test run. | true | |
protocol_vuh | Number of VUH charged for the protocol part of the test run. | true |
OK example
{
"@count": 123,
"@nextLink": "https://api.k6.io/cloud/v6/load_tests/123/test_runs?$skip=50\u0026$top=20",
"value": [
{
"cost": {
"breakdown": {
"browser_vuh": 0,
"protocol_vuh": 10
},
"total_vuh": 10
},
"created": "2024-06-01T19:00:00Z",
"distribution": [
{
"load_zone": "amazon:us:ashburn",
"percent": 100
}
],
"ended": null,
"id": 1234,
"note": "User-defined note for the test run.",
"options": {
"cloud": {
"distribution": {
"amazon:us:ashburn": {
"loadZone": "amazon:us:ashburn",
"percent": 100
}
},
"projectID": 12
},
"stages": [
{
"duration": "10m",
"target": 10
},
{
"duration": "20m",
"target": 10
}
]
},
"project_id": 12,
"result": null,
"result_details": {},
"retention_expiry": "2024-07-01T19:30:30Z",
"started_by": "user@example.com",
"status": "running",
"status_details": {
"entered": "2024-06-01T19:00:20Z",
"type": "running"
},
"status_history": [
{
"entered": "2024-06-01T19:00:00Z",
"type": "created"
},
{
"entered": "2024-06-01T19:00:10Z",
"type": "initializing"
},
{
"entered": "2024-06-01T19:00:20Z",
"type": "running"
}
],
"test_id": 123
}
]
}
400
response
401
response
403
response
404
response
500
response
List all test runs
GET /cloud/v6/test_runs
List all available test runs.
Request parameters
Name | Description | In | Required | Type |
---|---|---|---|---|
stackId | Numeric ID of the Grafana stack representing the request scope.
| header | true | integer |
$count | Include collection length in the response object as @count . | query | false | boolean |
$skip | The initial index from which to return the results. | query | false | integer |
$top | Number of results to return per page. Default: 1000 Maximum: 1000 | query | false | integer |
200
response
OK.
Content type:
application/json
TestRunListResponse
properties:
Name | Description | Required | Type |
---|---|---|---|
@count | Object count in the collection. | false | integer |
@nextLink | A reference to the next page of results. The property is included until there are no more pages of results to retrieve. | false | string
, format: uri |
value | List of the resulting values. | true | Array[TestRunApiModel] |
The API model for a test run.
TestRunApiModel
properties:
Name | Description | Required | Type |
---|---|---|---|
cost | Test run cost details. The cost is available only after test run validation.
| true | TestCostApiModel
|
null |
created | Date and time when the test run was started. | true | string
, format: date-time |
distribution | List of the load zones configured for the test and the corresponding distribution percentages. | true | array
|
null |
ended | Date and time when the test run ended. Unset if the test is still running. | true | string
|
null
, format: date-time |
id | ID of the test run. | true | integer |
note | User-defined note for the test run. | true | string |
options | The original options object if available. | true | object
|
null |
project_id | ID of the parent project. | true | integer |
result | Test run result. passed if there were no issues, failed if thresholds were breached, error if the execution was not completed. | true | string
|
null |
result_details | Additional information about the test run result. | true | object
|
null |
retention_expiry | Timestamp after which the test run results are deleted or null if the test run is saved. | true | string
|
null
, format: date-time |
started_by | Email of the user who started the test if started with a user token. | true | string
|
null
, format: email |
status | Current test run status. | true | string |
status_details | Details of the current test run status. | true | StatusApiModel |
status_history | List of test run status objects sorted by the enter time representing the status history. | true | Array[StatusApiModel] |
test_id | ID of the parent test. | true | integer |
Details of the test run status.
StatusApiModel
properties:
Name | Description | Required | Type |
---|---|---|---|
entered | Date and time when the test run entered the status. | true | string
, format: date-time |
extra | Extra information about the indicated status. | false | StatusExtraApiModel
|
null |
type | Type of simple test run status: created , queued , initializing , running , processing_metrics , completed or aborted . | true | string |
StatusExtraApiModel
properties:
Name | Description | Required | Type |
---|---|---|---|
by_user | Email of the user that set the status if applicable. | true | string
|
null
, format: email |
code | Service-defined error code if applicable. | true | integer
|
null |
message | Human-readable string describing the error if applicable. | true | string
|
null |
TestCostApiModel
properties:
Name | Description | Required | Type |
---|---|---|---|
breakdown | true | TestCostBreakdownApiModel | |
total_vuh | Total number of VUH charged for the test run. | true |
Breakdown details of the test cost.
TestCostBreakdownApiModel
properties:
Name | Description | Required | Type |
---|---|---|---|
browser_vuh | Number of VUH charged for the browser part of the test run. | true | |
protocol_vuh | Number of VUH charged for the protocol part of the test run. | true |
OK example
{
"@count": 123,
"@nextLink": "https://api.k6.io/cloud/v6/test_runs?$skip=50\u0026$top=20",
"value": [
{
"cost": {
"breakdown": {
"browser_vuh": 0,
"protocol_vuh": 10
},
"total_vuh": 10
},
"created": "2024-06-01T19:00:00Z",
"distribution": [
{
"load_zone": "amazon:us:ashburn",
"percent": 100
}
],
"ended": null,
"id": 1234,
"note": "User-defined note for the test run.",
"options": {
"cloud": {
"distribution": {
"amazon:us:ashburn": {
"loadZone": "amazon:us:ashburn",
"percent": 100
}
},
"projectID": 12
},
"stages": [
{
"duration": "10m",
"target": 10
},
{
"duration": "20m",
"target": 10
}
]
},
"project_id": 12,
"result": null,
"result_details": {},
"retention_expiry": "2024-07-01T19:30:30Z",
"started_by": "user@example.com",
"status": "running",
"status_details": {
"entered": "2024-06-01T19:00:20Z",
"type": "running"
},
"status_history": [
{
"entered": "2024-06-01T19:00:00Z",
"type": "created"
},
{
"entered": "2024-06-01T19:00:10Z",
"type": "initializing"
},
{
"entered": "2024-06-01T19:00:20Z",
"type": "running"
}
],
"test_id": 123
}
]
}
400
response
401
response
403
response
500
response
Delete a test run
DELETE /cloud/v6/test_runs/{id}
Delete a test run.
Request parameters
Name | Description | In | Required | Type |
---|---|---|---|---|
stackId | Numeric ID of the Grafana stack representing the request scope.
| header | true | integer |
id | ID of the load test run. | path | true | integer |
204
response
OK.
401
response
403
response
404
response
409
response
Cannot delete test while it’s running.
Content type:
application/json
ErrorResponseApiModel
properties:
Name | Description | Required | Type |
---|---|---|---|
error | true | ErrorApiModel |
Details of the error.
ErrorApiModel
properties:
Name | Description | Required | Type |
---|---|---|---|
code | Service-defined error code. | true | string |
details | Array of objects with more specific error information when applicable. | false | array
|
null |
message | Human-readable string describing the error. | true | string |
target | A string indicating the target of the error. For example, the name of the property in error. | false | string
|
null |
500
response
Get a test run by ID
GET /cloud/v6/test_runs/{id}
Fetch a single test run.
Request parameters
Name | Description | In | Required | Type |
---|---|---|---|---|
stackId | Numeric ID of the Grafana stack representing the request scope.
| header | true | integer |
id | ID of the load test run. | path | true | integer |
200
response
OK.
Content type:
application/json
The API model for a test run.
TestRunApiModel
properties:
Name | Description | Required | Type |
---|---|---|---|
cost | Test run cost details. The cost is available only after test run validation.
| true | TestCostApiModel
|
null |
created | Date and time when the test run was started. | true | string
, format: date-time |
distribution | List of the load zones configured for the test and the corresponding distribution percentages. | true | array
|
null |
ended | Date and time when the test run ended. Unset if the test is still running. | true | string
|
null
, format: date-time |
id | ID of the test run. | true | integer |
note | User-defined note for the test run. | true | string |
options | The original options object if available. | true | object
|
null |
project_id | ID of the parent project. | true | integer |
result | Test run result. passed if there were no issues, failed if thresholds were breached, error if the execution was not completed. | true | string
|
null |
result_details | Additional information about the test run result. | true | object
|
null |
retention_expiry | Timestamp after which the test run results are deleted or null if the test run is saved. | true | string
|
null
, format: date-time |
started_by | Email of the user who started the test if started with a user token. | true | string
|
null
, format: email |
status | Current test run status. | true | string |
status_details | Details of the current test run status. | true | StatusApiModel |
status_history | List of test run status objects sorted by the enter time representing the status history. | true | Array[StatusApiModel] |
test_id | ID of the parent test. | true | integer |
Details of the test run status.
StatusApiModel
properties:
Name | Description | Required | Type |
---|---|---|---|
entered | Date and time when the test run entered the status. | true | string
, format: date-time |
extra | Extra information about the indicated status. | false | StatusExtraApiModel
|
null |
type | Type of simple test run status: created , queued , initializing , running , processing_metrics , completed or aborted . | true | string |
StatusExtraApiModel
properties:
Name | Description | Required | Type |
---|---|---|---|
by_user | Email of the user that set the status if applicable. | true | string
|
null
, format: email |
code | Service-defined error code if applicable. | true | integer
|
null |
message | Human-readable string describing the error if applicable. | true | string
|
null |
TestCostApiModel
properties:
Name | Description | Required | Type |
---|---|---|---|
breakdown | true | TestCostBreakdownApiModel | |
total_vuh | Total number of VUH charged for the test run. | true |
Breakdown details of the test cost.
TestCostBreakdownApiModel
properties:
Name | Description | Required | Type |
---|---|---|---|
browser_vuh | Number of VUH charged for the browser part of the test run. | true | |
protocol_vuh | Number of VUH charged for the protocol part of the test run. | true |
Completed example
{
"cost": {
"breakdown": {
"browser_vuh": 0,
"protocol_vuh": 10
},
"total_vuh": 10
},
"created": "2024-06-01T19:00:00Z",
"distribution": [
{
"load_zone": "amazon:us:ashburn",
"percent": 100
}
],
"ended": "2024-06-01T19:30:30Z",
"id": 1234,
"note": "User-defined note for the test run.",
"options": {
"cloud": {
"distribution": {
"amazon:us:ashburn": {
"loadZone": "amazon:us:ashburn",
"percent": 100
}
},
"projectID": 12
},
"stages": [
{
"duration": "10m",
"target": 10
},
{
"duration": "20m",
"target": 10
}
]
},
"project_id": 12,
"result": "success",
"result_details": {},
"retention_expiry": "2024-07-01T19:30:30Z",
"started_by": "user@example.com",
"status": "completed",
"status_details": {
"entered": "2024-06-01T19:30:30Z",
"type": "completed"
},
"status_history": [
{
"entered": "2024-06-01T19:00:00Z",
"type": "created"
},
{
"entered": "2024-06-01T19:00:10Z",
"type": "initializing"
},
{
"entered": "2024-06-01T19:00:20Z",
"type": "running"
},
{
"entered": "2024-06-01T19:30:20Z",
"type": "processing_metrics"
},
{
"entered": "2024-06-01T19:30:30Z",
"type": "completed"
}
],
"test_id": 123
}
Running example
{
"cost": {
"breakdown": {
"browser_vuh": 0,
"protocol_vuh": 10
},
"total_vuh": 10
},
"created": "2024-06-01T19:00:00Z",
"distribution": [
{
"load_zone": "amazon:us:ashburn",
"percent": 100
}
],
"ended": null,
"id": 1234,
"note": "User-defined note for the test run.",
"options": {
"cloud": {
"distribution": {
"amazon:us:ashburn": {
"loadZone": "amazon:us:ashburn",
"percent": 100
}
},
"projectID": 12
},
"stages": [
{
"duration": "10m",
"target": 10
},
{
"duration": "20m",
"target": 10
}
]
},
"project_id": 12,
"result": null,
"result_details": {},
"retention_expiry": "2024-07-01T19:30:30Z",
"started_by": "user@example.com",
"status": "running",
"status_details": {
"entered": "2024-06-01T19:00:20Z",
"type": "running"
},
"status_history": [
{
"entered": "2024-06-01T19:00:00Z",
"type": "created"
},
{
"entered": "2024-06-01T19:00:10Z",
"type": "initializing"
},
{
"entered": "2024-06-01T19:00:20Z",
"type": "running"
}
],
"test_id": 123
}
ValidationError example
{
"cost": null,
"created": "2024-06-01T19:00:00Z",
"distribution": null,
"ended": "2024-06-01T19:00:10Z",
"id": 1234,
"note": "",
"options": null,
"project_id": 12,
"result": "error",
"result_details": {},
"retention_expiry": "2024-07-01T19:00:10Z",
"started_by": "user@example.com",
"status": "aborted",
"status_details": {
"entered": "2024-06-24T19:44:36.46Z",
"extra": {
"by_user": null,
"code": 123,
"message": "Validation error"
},
"type": "aborted"
},
"status_history": [
{
"entered": "2024-06-01T19:00:00Z",
"type": "created"
},
{
"entered": "2024-06-01T19:00:10Z",
"extra": {
"by_user": null,
"code": 123,
"message": "Validation error"
},
"type": "aborted"
}
],
"test_id": 123
}
401
response
403
response
404
response
500
response
Update a test run
PATCH /cloud/v6/test_runs/{id}
Update a test run.
Request parameters
Name | Description | In | Required | Type |
---|---|---|---|---|
stackId | Numeric ID of the Grafana stack representing the request scope.
| header | true | integer |
id | ID of the load test run. | path | true | integer |
Request body
Content type:
application/json
PatchTestRunApiModel
properties:
Name | Description | Required | Type |
---|---|---|---|
note | User-defined note for the test run. | true | string |
Update example
{
"note": "New note for the test run"
}
204
response
OK.
400
response
401
response
403
response
404
response
500
response
Abort a running test
POST /cloud/v6/test_runs/{id}/abort
Abort a running test.
Request parameters
Name | Description | In | Required | Type |
---|---|---|---|---|
stackId | Numeric ID of the Grafana stack representing the request scope.
| header | true | integer |
id | ID of the load test run. | path | true | integer |
204
response
OK.
401
response
403
response
404
response
409
response
Cannot abort a non-running test.
Content type:
application/json
ErrorResponseApiModel
properties:
Name | Description | Required | Type |
---|---|---|---|
error | true | ErrorApiModel |
Details of the error.
ErrorApiModel
properties:
Name | Description | Required | Type |
---|---|---|---|
code | Service-defined error code. | true | string |
details | Array of objects with more specific error information when applicable. | false | array
|
null |
message | Human-readable string describing the error. | true | string |
target | A string indicating the target of the error. For example, the name of the property in error. | false | string
|
null |
500
response
Save test run results
POST /cloud/v6/test_runs/{id}/save
Persist test run results to keep them past the data-retention period.
Request parameters
Name | Description | In | Required | Type |
---|---|---|---|---|
stackId | Numeric ID of the Grafana stack representing the request scope.
| header | true | integer |
id | ID of the load test run. | path | true | integer |
204
response
OK.
401
response
403
response
404
response
409
response
The test run results have been deleted, or the maximum number of saved test runs has been reached.
Content type:
application/json
ErrorResponseApiModel
properties:
Name | Description | Required | Type |
---|---|---|---|
error | true | ErrorApiModel |
Details of the error.
ErrorApiModel
properties:
Name | Description | Required | Type |
---|---|---|---|
code | Service-defined error code. | true | string |
details | Array of objects with more specific error information when applicable. | false | array
|
null |
message | Human-readable string describing the error. | true | string |
target | A string indicating the target of the error. For example, the name of the property in error. | false | string
|
null |
Deleted example
{
"error": {
"code": "conflict",
"message": "Test run has been deleted"
}
}
LimitReached example
{
"error": {
"code": "conflict",
"message": "The maximum number of saved test runs has been reached"
}
}
500
response
Download the test run script
GET /cloud/v6/test_runs/{id}/script
Download the test run script.
Request parameters
Name | Description | In | Required | Type |
---|---|---|---|---|
stackId | Numeric ID of the Grafana stack representing the request scope.
| header | true | integer |
id | ID of the load test run. | path | true | integer |
200
response
OK.
Content type:
application/x-tar
K6ArchiveScript example
(.tar data)
Content type:
text/javascript
TextScript example
import http from 'k6/http';
import { sleep } from 'k6';
export const options = {
vus: 10,
duration: '30s',
cloud: {
// Project: Default project
projectID: 3684621,
// Test runs with the same name groups test runs together.
name: 'Test (04/12/2024-20:28:06)'
}
};
export default function() {
http.get('https://test.k6.io');
sleep(1);
}
401
response
403
response
404
response
500
response
Unsave test run results
POST /cloud/v6/test_runs/{id}/unsave
Disable persistence of the test run results past the data-retention period.
The data will be automatically deleted at the end of the retention period.
Request parameters
Name | Description | In | Required | Type |
---|---|---|---|---|
stackId | Numeric ID of the Grafana stack representing the request scope.
| header | true | integer |
id | ID of the load test run. | path | true | integer |
204
response
OK.