Menu
DocumentationGrafana CloudTest applications and servicesPerformance TestingReference pagesCloud REST APILegacy REST APITest Runs
Grafana Cloud

Test Runs Legacy API

Warning

The Legacy REST API is no longer under active development. It should not be used except when it provides capabilities not yet offered by the Grafana Cloud k6 REST API.

A load test run is an individual execution of a load test. Every test run has an ID, held in an array of test_run_ids in the k6-test object.

Start load test run

Starts a test run in the cloud for the specified Load Test ID.

Note

Note that this endpoint uses the /v2/tests/ base URL rather than /v2/runs. It also needs to be provided with a Load Test {id}. This is because this endpoint makes use of the data from the provided Load Test to create and return a new Load Test Run.

The test run is managed by the cloud from beginning to end. You can monitor the test progress in the cloud application. From there, you can also export and analyze the result.

POST https://api.k6.io/loadtests/v2/tests/{id}/start-testrun

Path ParameterTypeDescription
idintegerA unique integer value identifying this test.
json 
{
  "k6-run": {
    "config": {},
    "created": "2020-08-13T18:28:45Z",
    "duration": 0,
    "ended": "2020-08-13T18:28:45Z",
    "error_code": 0,
    "error_detail": "string",
    "id": 0,
    "k6_archive": "string",
    "load_time": 0,
    "note": "string",
    "organization_id": 0,
    "processing_status": 0,
    "project_id": 0,
    "public_id": 0,
    "result_status": 0,
    "run_process": "string",
    "run_status": 0,
    "script": "string",
    "started": "2020-08-13T18:28:45Z",
    "stopped_by_id": 0,
    "test_id": 0,
    "user_id": 0,
    "version": "string",
    "vus": 0
  }
}

Read load test run

Returns details of a test run with the specified ID. The response contains several fields about test-run status.

The run_status field describes how far the test run is in the execution pipeline. Possible values are the following:

ValueDescription
-2CREATED - test run is created in our system.
-1VALIDATED - test run passed script and subscription validation.
0QUEUED - test run is waiting for an empty slot in execution queue.
1INITIALIZING - load generator instances are being allocated for the test run.
2RUNNING - test run is currently executing.
3FINISHED - test run has finished executing.
4TIMED_OUT - test run has timed out (usually because data took too long to arrive/process).
5ABORTED_BY_USER - test run was aborted by user.
6ABORTED_BY_SYSTEM - test run was aborted by our system (usually because of some error).
7ABORTED_BY_SCRIPT_ERROR - test run was aborted due to an error in the script.
8ABORTED_BY_THRESHOLD - test run was aborted because a threshold defined in k6 script was reached.
9ABORTED_BY_LIMIT - test run was aborted because of a limit in script definition or execution (e.g. subscription limitations).

processing_status - Describes if system is (still) processing metric data for the test run. Possible values are:

ValueDescription
0NOT_STARTED - data processing has not started yet.
1PROCESSING - data processing is in progress.
2FINISHED - data processing is finished and all metrics are available.
3ERROR - there was an error in data processing and some or all metrics are not available.

result_status - Describes if the test has passed or failed. Possible values are:

ValueDescription
0PASSED - all criteria defined in k6 script have passed.
1FAILED - on or more criteria in k6 script has failed.

GET https://api.k6.io/loadtests/v2/runs/{id}

Path ParameterTypeDescription
idintegerID of the test run.
Query ParameterTypeDescriptionExample
$selectstringSpecify a subset of fields to return./loadtests/v2/runs/1?$select=id,test_id,run_status,created
json 
{
  "k6-run": {
    "config": {},
    "created": "2020-08-18T13:33:41",
    "duration": 120,
    "ended": "2020-08-18T13:36:02",
    "error_code": null,
    "error_detail": null,
    "export": null,
    "id": 0,
    "is_baseline": false,
    "k6_archive": "string",
    "load_time": 75.0,
    "note": "",
    "organization_id": 0,
    "processing_status": 2,
    "project_id": 0,
    "public_id": null,
    "request_builder_config": null,
    "result_status": 1,
    "run_process": "k6 to Cloud",
    "run_status": 3,
    "script": "",
    "started": "2020-08-18T13:34:04",
    "stopped_by_id": 0,
    "test_id": 0,
    "user_id": 0,
    "version": 2,
    "vus": 200,
    "vus_per_instance": 0
  }
}

List load test runs

Returns all test runs for a particular load test.

GET https://api.k6.io/loadtests/v2/runs?test_id={test_id}

Query ParameterTypeDescriptionExample
test_idintegerID of the test./loadtests/v2/runs?$test_id=1
$selectstringSpecify a subset of fields to return./loadtests/v2/runs?$test_id=1&select=id,test_id,run_status,created
ids[]integerSpecify a subset test runs to return./loadtests/v2/runs?$test_id=1&ids[]=1&ids[]=3
public_idstringGet a test run by public_id./loadtests/v2/runs?public_id={public_id}
json 
{
  "k6-runs": [
    {
      "config": {},
      "created": "2020-08-18T13:33:41",
      "duration": 120,
      "ended": "2020-08-18T13:36:02",
      "error_code": null,
      "error_detail": null,
      "id": 0,
      "is_baseline": false,
      "k6_archive": "string",
      "load_time": 75.0,
      "note": "",
      "organization_id": 0,
      "processing_status": 2,
      "project_id": 0,
      "public_id": null,
      "request_builder_config": null,
      "result_status": 1,
      "run_process": "k6 to Cloud",
      "run_status": 3,
      "script": "",
      "started": "2020-08-18T13:34:04",
      "stopped_by_id": 0,
      "test_id": 0,
      "user_id": 0,
      "version": 2,
      "vus": 200,
      "vus_per_instance": 0
    }
  ],
  "meta": {
    "count": 1
  }
}

Stop load test run

Manually stops a load test run. If you follow along in the app, the test-run will be marked as Aborted (by User). Note that can take a few moments before the test actually stops as the processor shuts down.

POST /loadtests/v2/runs/{id}/stop