Numeric ID of the Grafana stack representing the request scope.
If the API is called with a Personal API token, the user must be a member of the specified stack.
If the API is called with a Grafana Stack API token, the value must be the ID of the corresponding stack.
header
true
integer
$count
Include collection length in the response object as @count.
query
false
boolean
$orderby
Comma-separated list of fields to use when ordering the results. Available fields:
id
project_id
name
created
updated
The default ascending order can be reversed by appending the desc specifier.
query
false
string
$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
LoadTestListResponse 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[LoadTestApiModel]
LoadTestApiModel properties:
Name
Description
Required
Type
baseline_test_run_id
ID of a baseline test run used for results comparison.
true
integer|null
created
The date when the test was created.
true
string
, format: date-time
id
ID of the load test.
true
integer
name
Unique name of the test within the project.
true
string
project_id
ID of the parent project.
true
integer
updated
The date when the test was last updated.
true
string
, format: date-time
OK example
{"@count":123,"@nextLink":"https://api.k6.io/cloud/v6/load_tests?$skip=50\u0026$top=20","value":[{"baseline_test_run_id":null,"created":"2024-12-03T09:53:00.553","id":1234,"name":"Orders API Soak Test","project_id":312,"updated":"2024-12-03T09:53:00.553"}]}
400
response
401
response
403
response
500
response
Delete a load test
DELETE /cloud/v6/load_tests/{id}
Delete a load test.
Request parameters
Name
Description
In
Required
Type
stackId
Numeric ID of the Grafana stack representing the request scope.
If the API is called with a Personal API token, the user must be a member of the specified stack.
If the API is called with a Grafana Stack API token, the value must be the ID of the corresponding stack.
header
true
integer
id
ID of the load test.
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 load test by ID
GET /cloud/v6/load_tests/{id}
Fetch a single load test.
Request parameters
Name
Description
In
Required
Type
stackId
Numeric ID of the Grafana stack representing the request scope.
If the API is called with a Personal API token, the user must be a member of the specified stack.
If the API is called with a Grafana Stack API token, the value must be the ID of the corresponding stack.
header
true
integer
id
ID of the load test.
path
true
integer
200
response
OK.
Content type:
application/json
LoadTestApiModel properties:
Name
Description
Required
Type
baseline_test_run_id
ID of a baseline test run used for results comparison.
true
integer|null
created
The date when the test was created.
true
string
, format: date-time
id
ID of the load test.
true
integer
name
Unique name of the test within the project.
true
string
project_id
ID of the parent project.
true
integer
updated
The date when the test was last updated.
true
string
, format: date-time
OK example
{"baseline_test_run_id":null,"created":"2024-12-03T09:53:00.553","id":1234,"name":"Orders API Soak Test","project_id":312,"updated":"2024-12-03T09:53:00.553"}
401
response
403
response
404
response
500
response
Update a load test
PATCH /cloud/v6/load_tests/{id}
Update a load test.
Request parameters
Name
Description
In
Required
Type
stackId
Numeric ID of the Grafana stack representing the request scope.
If the API is called with a Personal API token, the user must be a member of the specified stack.
If the API is called with a Grafana Stack API token, the value must be the ID of the corresponding stack.
header
true
integer
id
ID of the load test.
path
true
integer
Request body
Content type:
application/json
PatchLoadTestApiModel properties:
Name
Description
Required
Type
baseline_test_run_id
ID of a baseline test run used for results comparison.
false
integer|null
name
Unique name of the test within the project.
false
string
Update example
{"baseline_test_run_id":123,"name":"New Test Name"}
204
response
OK.
400
response
401
response
403
response
404
response
409
response
The name is already taken.
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
Download the test script
GET /cloud/v6/load_tests/{id}/script
Download the test script.
The script can be either in the form of a single JavaScript file or a k6 .tar archive -
the type is identified by the request content type.
Request parameters
Name
Description
In
Required
Type
stackId
Numeric ID of the Grafana stack representing the request scope.
If the API is called with a Personal API token, the user must be a member of the specified stack.
If the API is called with a Grafana Stack API token, the value must be the ID of the corresponding stack.
header
true
integer
id
ID of the load test.
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';exportconst options ={vus:10,duration:'30s',cloud:{// Project: Default projectprojectID:3684621,// Test runs with the same name groups test runs together.name:'Test (04/12/2024-20:28:06)'}};exportdefaultfunction(){
http.get('https://test.k6.io');sleep(1);}
401
response
403
response
404
response
500
response
Upload the script for a test
PUT /cloud/v6/load_tests/{id}/script
Upload the script for a test.
The script can be either in the form of a single JavaScript text file or a k6 .tar archive -
the type is auto-detected by the API. Any received payload that is not a .tar archive
is assumed to be a JavaScript file.
Request parameters
Name
Description
In
Required
Type
stackId
Numeric ID of the Grafana stack representing the request scope.
If the API is called with a Personal API token, the user must be a member of the specified stack.
If the API is called with a Grafana Stack API token, the value must be the ID of the corresponding stack.
header
true
integer
id
ID of the load test.
path
true
integer
Request body
Content type:
application/octet-stream
K6ArchiveScript example
(.tar data)
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);
}
204
response
OK.
400
response
401
response
403
response
404
response
500
response
Start a test in Grafana Cloud
POST /cloud/v6/load_tests/{id}/start
Start a test in Grafana Cloud.
Request parameters
Name
Description
In
Required
Type
stackId
Numeric ID of the Grafana stack representing the request scope.
If the API is called with a Personal API token, the user must be a member of the specified stack.
If the API is called with a Grafana Stack API token, the value must be the ID of the corresponding stack.
header
true
integer
id
ID of the load test.
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.
For test runs still in progress, the value is an estimate of the full cost that will be charged upon successful completion.
For finished test runs, the value is the real cost charged for the test run.
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.
Numeric ID of the Grafana stack representing the request scope.
If the API is called with a Personal API token, the user must be a member of the specified stack.
If the API is called with a Grafana Stack API token, the value must be the ID of the corresponding stack.
header
true
integer
$count
Include collection length in the response object as @count.
query
false
boolean
$orderby
Comma-separated list of fields to use when ordering the results. Available fields:
id
project_id
name
created
updated
The default ascending order can be reversed by appending the desc specifier.
query
false
string
$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 project.
path
true
integer
200
response
OK.
Content type:
application/json
LoadTestListResponse 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[LoadTestApiModel]
LoadTestApiModel properties:
Name
Description
Required
Type
baseline_test_run_id
ID of a baseline test run used for results comparison.
true
integer|null
created
The date when the test was created.
true
string
, format: date-time
id
ID of the load test.
true
integer
name
Unique name of the test within the project.
true
string
project_id
ID of the parent project.
true
integer
updated
The date when the test was last updated.
true
string
, format: date-time
OK example
{"@count":123,"@nextLink":"https://api.k6.io/cloud/v6/projects/312/load_tests?$skip=50\u0026$top=20","value":[{"baseline_test_run_id":null,"created":"2024-12-03T09:53:00.553","id":1234,"name":"Orders API Soak Test","project_id":312,"updated":"2024-12-03T09:53:00.553"}]}
400
response
401
response
403
response
404
response
500
response
Create a new test
POST /cloud/v6/projects/{id}/load_tests
Create a new test in the project.
The script can be either in the form of a single JavaScript text file or a k6 .tar archive -
the type is auto-detected by the API. Any received payload that is not a .tar archive
is assumed to be a JavaScript file.
Request parameters
Name
Description
In
Required
Type
stackId
Numeric ID of the Grafana stack representing the request scope.
If the API is called with a Personal API token, the user must be a member of the specified stack.
If the API is called with a Grafana Stack API token, the value must be the ID of the corresponding stack.
header
true
integer
id
ID of the project.
path
true
integer
Request body
Content type:
multipart/form-data
CreateLoadTestApiModel properties:
Name
Description
Required
Type
name
Unique name of the test within the project.
true
string
script
Test script in the form of a UTF-8 encoded text or a k6 .tar archive.
true
string
, format: binary
201
response
OK.
Content type:
application/json
LoadTestApiModel properties:
Name
Description
Required
Type
baseline_test_run_id
ID of a baseline test run used for results comparison.
true
integer|null
created
The date when the test was created.
true
string
, format: date-time
id
ID of the load test.
true
integer
name
Unique name of the test within the project.
true
string
project_id
ID of the parent project.
true
integer
updated
The date when the test was last updated.
true
string
, format: date-time
OK example
{"baseline_test_run_id":null,"created":"2024-12-03T09:53:00.553","id":1234,"name":"Orders API Soak Test","project_id":312,"updated":"2024-12-03T09:53:00.553"}
400
response
401
response
403
response
404
response
409
response
The name is already taken.
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
Validate k6 script options
POST /cloud/v6/validate_options
Verify a test can be run in Grafana Cloud with the provided k6 script options.
Project ID can be specified in the root object as well as under options.cloud.
Request parameters
Name
Description
In
Required
Type
stackId
Numeric ID of the Grafana stack representing the request scope.
If the API is called with a Personal API token, the user must be a member of the specified stack.
If the API is called with a Grafana Stack API token, the value must be the ID of the corresponding stack.