Testing and synthetics

Performance testing

Reference pages

Cloud REST API

Load tests

Grafana Cloud

Tests REST API

List all tests

GET /cloud/v6/load_tests

List all available tests.

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`
`$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';

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

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.	`true`

Started example

{
  "cost": null,
  "created": "2024-06-01T19:00:00Z",
  "distribution": null,
  "ended": null,
  "id": 1234,
  "note": "",
  "options": null,
  "project_id": 12,
  "result": null,
  "result_details": null,
  "retention_expiry": "2024-06-07T19:00:00Z",
  "started_by": "user@example.com",
  "status": "created",
  "status_details": {
    "entered": "2024-06-01T19:00:00Z",
    "type": "created"
  },
  "status_history": [
    {
      "entered": "2024-06-01T19:00:00Z",
      "type": "created"
    }
  ],
  "test_id": 123
}

`401` response

`403` response

`404` response

`500` response

List load tests in a project

GET /cloud/v6/projects/{id}/load_tests

List load tests in a project.

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`
`$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.

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.

header

true

integer

Request body

Content type: `application/json`

ValidateOptionsRequest properties:

Name	Description	Required	Type
`options`	k6 script options object to validate.	`true`	`object`
`project_id`	ID of a project where the test belongs.	`false`	`integer` \| `null`

ProjectIdInOptions example

{
  "options": {
    "cloud": {
      "distribution": {
        "amazon:us:ashburn": {
          "loadZone": "amazon:us:ashburn",
          "percent": 100
        }
      },
      "projectID": 123456
    },
    "stages": [
      {
        "duration": "1m",
        "target": 20
      },
      {
        "duration": "3m",
        "target": 20
      },
      {
        "duration": "30s",
        "target": 0
      }
    ]
  }
}

`200` response

OK.

Content type: `application/json`

ValidateOptionsResponse properties:

Name	Description	Required	Type
`vuh_usage`	How many VUH will be charged for the test.	`true`	`number`

OK example

{
  "vuh_usage": 1.5
}

`400` response

`401` response

`403` response

`500` response

Was this page helpful?

Email docs@grafana.com

Help and support

Community

Tests REST API

List all tests

Request parameters

200 response

Content type: application/json

OK example

400 response

401 response

403 response

500 response

Delete a load test

Request parameters

204 response

401 response

403 response

404 response

409 response

Content type: application/json

500 response

Get a load test by ID

Request parameters

200 response

Content type: application/json

OK example

401 response

403 response

404 response

500 response

Update a load test

Request parameters

Request body

Content type: application/json

Update example

204 response

400 response

401 response

403 response

404 response

409 response

Content type: application/json

500 response

Download the test script

Request parameters

200 response

Content type: application/x-tar

K6ArchiveScript example

Content type: text/javascript

TextScript example

401 response

403 response

404 response

500 response

Upload the script for a test

Request parameters

Request body

Content type: application/octet-stream

K6ArchiveScript example

TextScript example

204 response

400 response

401 response

403 response

404 response

500 response

Start a test in Grafana Cloud

Request parameters

200 response

Content type: application/json

Started example

401 response

403 response

404 response

500 response

List load tests in a project

Request parameters

200 response

Content type: application/json

OK example

400 response

401 response

`200` response

Content type: `application/json`

`400` response

`401` response

`403` response

`500` response

`204` response

`401` response

`403` response

`404` response

`409` response

Content type: `application/json`

`500` response

`200` response

Content type: `application/json`

`401` response

`403` response

`404` response

`500` response

Content type: `application/json`

`204` response

`400` response

`401` response

`403` response

`404` response

`409` response

Content type: `application/json`

`500` response

`200` response

Content type: `application/x-tar`

Content type: `text/javascript`

`401` response

`403` response

`404` response

`500` response

Content type: `application/octet-stream`

`204` response

`400` response

`401` response

`403` response

`404` response

`500` response

`200` response

Content type: `application/json`

`401` response

`403` response

`404` response

`500` response

`200` response

Content type: `application/json`

`400` response

`401` response

`403` response

`404` response

`500` response

Content type: `multipart/form-data`

`201` response

Content type: `application/json`

`400` response

`401` response

`403` response

`404` response

`409` response

Content type: `application/json`

`500` response

Content type: `application/json`

`200` response

Content type: `application/json`

`400` response

`401` response

`403` response

`500` response