Testing and synthetics

Performance testing

Reference pages

Cloud REST API

Deprecated REST API

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 Parameter	Type	Description
id	integer	A unique integer value identifying this test.

{
  "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:

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

Value	Description
0	NOT_STARTED - data processing has not started yet.
1	PROCESSING - data processing is in progress.
2	FINISHED - data processing is finished and all metrics are available.
3	ERROR - 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:

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

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

Path Parameter	Type	Description
id	integer	ID of the test run.

Query Parameter	Type	Description	Example
$select	string	Specify a subset of fields to return.	`/loadtests/v2/runs/1?$select=id,test_id,run_status,created`

{
  "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

Parameter	Description
`$select`	Optional: Specifies a comma-separated list of properties to include in the response.

Example Request:

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

Example Response:

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 Parameter	Type	Description	Example
test_id	integer	ID of the test.	`/loadtests/v2/runs?$test_id=1`
$select	string	Specify a subset of fields to return.	`/loadtests/v2/runs?$test_id=1&select=id,test_id,run_status,created`
ids[]	integer	Specify a subset test runs to return.	`/loadtests/v2/runs?$test_id=1&ids[]=1&ids[]=3`
public_id	string	Get a test run by public_id.	`/loadtests/v2/runs?public_id={public_id}`

{
  "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.

Parameter	Description
`$select`	Specifies a comma-separated list of properties to include in the response.
`$orderby`	Specifies the sorting order for the returned results. It accepts one or more comma-separated properties with an optional `asc` (ascending) or `desc` (descending) keyword.
`$top`	Limits the number of items to return in the response.
`$skip`	Specifies 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.
`$count`	Includes a count of the total number of items in the result set in the response.
`$filter`	Filters the result set based on specified conditions.

Example request:

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

Was this page helpful?

Email docs@grafana.com

Help and support

Community

Test Runs Legacy API

Start load test run

Read load test run

Read load test run Cloud v5

Parameters

List load test runs

List load test runs Cloud v5

Parameters

Stop load test run

Was this page helpful?

Related documentation

Related resources from Grafana Labs