Test Runs
Documentationbreadcrumb arrow Grafana Cloudbreadcrumb arrow Testing and syntheticsbreadcrumb arrow Performance testingbreadcrumb arrow Reference pagesbreadcrumb arrow Cloud REST APIbreadcrumb arrow Deprecated REST APIbreadcrumb arrow Test Runs
Grafana Cloud

Test Runs Legacy API

Warning

The Grafana Cloud k6 endpoints under this section are deprecated and planned for removal in the near future. Migrate to the latest Test Runs API endpoints to avoid disruptions.

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

Read load test run Cloud v5

Returns details of a test run with the specified ID.

GET /cloud/v5/test_runs/:id

Parameters

ParameterDescription
$selectOptional: Specifies a comma-separated list of properties to include in the response.

Example Request:

http 
GET https://api.k6.io/cloud/v5/test_runs/152779
Accept: application/json
Authorization: Token 56c166885f9a7fc1e588a1b3cb66f6dd

Example Response:

http 
HTTP/1.1 200
Content-Type: application/json

{
  "config": {
    "agent_access_token": "eba569496f1d64f42333333320e4abaec0c74c6baf06d22f603f3aac7eb39c",
    "archive": "4744e429260e47f8a504443d0f9f1bf1.tar",
    // cut for brevity
  },
  "created": "2023-05-18T08:46:01.157645Z",
  "delete_status": 0,
  "deleted": false,
  "duration": 2550,
  "ended": "2023-05-18T08:55:25.000000Z",
  "error_code": null,
  "error_detail": null,
  "id": 152779,
  "is_baseline": false,
  "note": "",
  "organization_id": 499,
  "processing_status": 2,
  "project_id": 5276,
  "public_id": null,
  "result_status": 0,
  "run_process": "UI-Script to Cloud",
  "run_status": 5,
  "script": "import { sleep, check } from 'k6 ...", // cut for brevity
  "started": "2023-05-18T08:48:31.000000Z",
  "stopped_by_id": 703,
  "test_id": 3535,
  "user_id": 703,
  "vus": 3000
}

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

List load test runs Cloud v5

Returns all test runs for a particular load test.

GET /cloud/v5/load_tests/:loadTestId/test_runs

Example URL with optional parameters:

GET /cloud/v5/load_tests/:loadTestId/test_runs?$top=10&$skip=20&$count=true&$select=id,name,created&$orderby=created desc&$filter=run_status eq 5 and

Parameters

All parameters are optional.

ParameterDescription
$selectSpecifies a comma-separated list of properties to include in the response.
$orderbySpecifies the sorting order for the returned results. It accepts one or more comma-separated properties with an optional asc (ascending) or desc (descending) keyword.
$topLimits the number of items to return in the response.
$skipSpecifies the number of items to skip in the result set before returning the remaining items. It is used for paging through a large result set.
$countIncludes a count of the total number of items in the result set in the response.
$filterFilters the result set based on specified conditions.

Example request:

http 
GET https://api.k6.io/cloud/v5/load_tests/3535/test_runs?$top=10&$count=true&$orderby=created desc
Accept: application/json
Authorization: Token 56c166885f9a7fc1e588a1b3cb66f6dd

Example response

http 
HTTP/1.1 200
Content-Type: application/json

{
  "@count": "144",
  "value": [
    {
      "config": {
        "agent_access_token": "eba569496f1d64f42333333320e4abaec0c74c6baf06d22f603f3aac7eb39c",
        "archive": "4744e429260e47f8a504443d0f9f1bf1.tar",
        // cut for brevity
      },
      "created": "2023-05-18T08:46:01.157645Z",
      "delete_status": 0,
      "deleted": false,
      "duration": 2550,
      "ended": "2023-05-18T08:55:25.000000Z",
      "error_code": null,
      "error_detail": null,
      "id": 152779,
      "is_baseline": false,
      "note": "",
      "organization_id": 499,
      "processing_status": 2,
      "project_id": 5276,
      "public_id": null,
      "result_status": 0,
      "run_process": "UI-Script to Cloud",
      "run_status": 5,
      "script": "import { sleep, check } from 'k6 ...", // cut for brevity
      "started": "2023-05-18T08:48:31.000000Z",
      "stopped_by_id": 703,
      "test_id": 3535,
      "user_id": 703,
      "vus": 3000
    },
    // cut for brevity
  ]
}

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