Menu
Grafana Cloud

Test runs REST API

List all runs of a load test

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

List all runs of a load test.

Request parameters

NameDescriptionInRequiredType
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.
headertrueinteger
$countInclude collection length in the response object as @count.queryfalseboolean
$skipThe initial index from which to return the results.queryfalseinteger
$topNumber of results to return per page.
Default: 1000
Maximum: 1000
queryfalseinteger
idID of the load test.pathtrueinteger

200 response

OK.

Content type: application/json

TestRunListResponse properties:

NameDescriptionRequiredType
@countObject count in the collection.falseinteger
@nextLinkA reference to the next page of results. The property is included until there are no more pages of results to retrieve.falsestring , format: uri
valueList of the resulting values.trueArray[TestRunApiModel]

The API model for a test run.

TestRunApiModel properties:

NameDescriptionRequiredType
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.
trueTestCostApiModel | null
createdDate and time when the test run was started.truestring , format: date-time
distributionList of the load zones configured for the test and the corresponding distribution percentages.truearray | null
endedDate and time when the test run ended. Unset if the test is still running.truestring | null , format: date-time
idID of the test run.trueinteger
noteUser-defined note for the test run.truestring
optionsThe original options object if available.trueobject | null
project_idID of the parent project.trueinteger
resultTest run result. passed if there were no issues, failed if thresholds were breached, error if the execution was not completed.truestring | null
result_detailsAdditional information about the test run result.trueobject | null
retention_expiryTimestamp after which the test run results are deleted or null if the test run is saved.truestring | null , format: date-time
started_byEmail of the user who started the test if started with a user token.truestring | null , format: email
statusCurrent test run status.truestring
status_detailsDetails of the current test run status.trueStatusApiModel
status_historyList of test run status objects sorted by the enter time representing the status history.trueArray[StatusApiModel]
test_idID of the parent test.trueinteger

Details of the test run status.

StatusApiModel properties:

NameDescriptionRequiredType
enteredDate and time when the test run entered the status.truestring , format: date-time
extraExtra information about the indicated status.falseStatusExtraApiModel | null
typeType of simple test run status: created, queued, initializing, running, processing_metrics, completed or aborted.truestring

StatusExtraApiModel properties:

NameDescriptionRequiredType
by_userEmail of the user that set the status if applicable.truestring | null , format: email
codeService-defined error code if applicable.trueinteger | null
messageHuman-readable string describing the error if applicable.truestring | null

TestCostApiModel properties:

NameDescriptionRequiredType
breakdowntrueTestCostBreakdownApiModel
total_vuhTotal number of VUH charged for the test run.true

Breakdown details of the test cost.

TestCostBreakdownApiModel properties:

NameDescriptionRequiredType
browser_vuhNumber of VUH charged for the browser part of the test run.true
protocol_vuhNumber of VUH charged for the protocol part of the test run.true
OK example
{
  "@count": 123,
  "@nextLink": "https://api.k6.io/cloud/v6/load_tests/123/test_runs?$skip=50\u0026$top=20",
  "value": [
    {
      "cost": {
        "breakdown": {
          "browser_vuh": 0,
          "protocol_vuh": 10
        },
        "total_vuh": 10
      },
      "created": "2024-06-01T19:00:00Z",
      "distribution": [
        {
          "load_zone": "amazon:us:ashburn",
          "percent": 100
        }
      ],
      "ended": null,
      "id": 1234,
      "note": "User-defined note for the test run.",
      "options": {
        "cloud": {
          "distribution": {
            "amazon:us:ashburn": {
              "loadZone": "amazon:us:ashburn",
              "percent": 100
            }
          },
          "projectID": 12
        },
        "stages": [
          {
            "duration": "10m",
            "target": 10
          },
          {
            "duration": "20m",
            "target": 10
          }
        ]
      },
      "project_id": 12,
      "result": null,
      "result_details": {},
      "retention_expiry": "2024-07-01T19:30:30Z",
      "started_by": "user@example.com",
      "status": "running",
      "status_details": {
        "entered": "2024-06-01T19:00:20Z",
        "type": "running"
      },
      "status_history": [
        {
          "entered": "2024-06-01T19:00:00Z",
          "type": "created"
        },
        {
          "entered": "2024-06-01T19:00:10Z",
          "type": "initializing"
        },
        {
          "entered": "2024-06-01T19:00:20Z",
          "type": "running"
        }
      ],
      "test_id": 123
    }
  ]
}

400 response

401 response

403 response

404 response

500 response

List all test runs

GET /cloud/v6/test_runs

List all available test runs.

Request parameters

NameDescriptionInRequiredType
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.
headertrueinteger
$countInclude collection length in the response object as @count.queryfalseboolean
$skipThe initial index from which to return the results.queryfalseinteger
$topNumber of results to return per page.
Default: 1000
Maximum: 1000
queryfalseinteger

200 response

OK.

Content type: application/json

TestRunListResponse properties:

NameDescriptionRequiredType
@countObject count in the collection.falseinteger
@nextLinkA reference to the next page of results. The property is included until there are no more pages of results to retrieve.falsestring , format: uri
valueList of the resulting values.trueArray[TestRunApiModel]

The API model for a test run.

TestRunApiModel properties:

NameDescriptionRequiredType
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.
trueTestCostApiModel | null
createdDate and time when the test run was started.truestring , format: date-time
distributionList of the load zones configured for the test and the corresponding distribution percentages.truearray | null
endedDate and time when the test run ended. Unset if the test is still running.truestring | null , format: date-time
idID of the test run.trueinteger
noteUser-defined note for the test run.truestring
optionsThe original options object if available.trueobject | null
project_idID of the parent project.trueinteger
resultTest run result. passed if there were no issues, failed if thresholds were breached, error if the execution was not completed.truestring | null
result_detailsAdditional information about the test run result.trueobject | null
retention_expiryTimestamp after which the test run results are deleted or null if the test run is saved.truestring | null , format: date-time
started_byEmail of the user who started the test if started with a user token.truestring | null , format: email
statusCurrent test run status.truestring
status_detailsDetails of the current test run status.trueStatusApiModel
status_historyList of test run status objects sorted by the enter time representing the status history.trueArray[StatusApiModel]
test_idID of the parent test.trueinteger

Details of the test run status.

StatusApiModel properties:

NameDescriptionRequiredType
enteredDate and time when the test run entered the status.truestring , format: date-time
extraExtra information about the indicated status.falseStatusExtraApiModel | null
typeType of simple test run status: created, queued, initializing, running, processing_metrics, completed or aborted.truestring

StatusExtraApiModel properties:

NameDescriptionRequiredType
by_userEmail of the user that set the status if applicable.truestring | null , format: email
codeService-defined error code if applicable.trueinteger | null
messageHuman-readable string describing the error if applicable.truestring | null

TestCostApiModel properties:

NameDescriptionRequiredType
breakdowntrueTestCostBreakdownApiModel
total_vuhTotal number of VUH charged for the test run.true

Breakdown details of the test cost.

TestCostBreakdownApiModel properties:

NameDescriptionRequiredType
browser_vuhNumber of VUH charged for the browser part of the test run.true
protocol_vuhNumber of VUH charged for the protocol part of the test run.true
OK example
{
  "@count": 123,
  "@nextLink": "https://api.k6.io/cloud/v6/test_runs?$skip=50\u0026$top=20",
  "value": [
    {
      "cost": {
        "breakdown": {
          "browser_vuh": 0,
          "protocol_vuh": 10
        },
        "total_vuh": 10
      },
      "created": "2024-06-01T19:00:00Z",
      "distribution": [
        {
          "load_zone": "amazon:us:ashburn",
          "percent": 100
        }
      ],
      "ended": null,
      "id": 1234,
      "note": "User-defined note for the test run.",
      "options": {
        "cloud": {
          "distribution": {
            "amazon:us:ashburn": {
              "loadZone": "amazon:us:ashburn",
              "percent": 100
            }
          },
          "projectID": 12
        },
        "stages": [
          {
            "duration": "10m",
            "target": 10
          },
          {
            "duration": "20m",
            "target": 10
          }
        ]
      },
      "project_id": 12,
      "result": null,
      "result_details": {},
      "retention_expiry": "2024-07-01T19:30:30Z",
      "started_by": "user@example.com",
      "status": "running",
      "status_details": {
        "entered": "2024-06-01T19:00:20Z",
        "type": "running"
      },
      "status_history": [
        {
          "entered": "2024-06-01T19:00:00Z",
          "type": "created"
        },
        {
          "entered": "2024-06-01T19:00:10Z",
          "type": "initializing"
        },
        {
          "entered": "2024-06-01T19:00:20Z",
          "type": "running"
        }
      ],
      "test_id": 123
    }
  ]
}

400 response

401 response

403 response

500 response

Delete a test run

DELETE /cloud/v6/test_runs/{id}

Delete a test run.

Request parameters

NameDescriptionInRequiredType
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.
headertrueinteger
idID of the load test run.pathtrueinteger

204 response

OK.

401 response

403 response

404 response

409 response

Cannot delete test while it’s running.

Content type: application/json

ErrorResponseApiModel properties:

NameDescriptionRequiredType
errortrueErrorApiModel

Details of the error.

ErrorApiModel properties:

NameDescriptionRequiredType
codeService-defined error code.truestring
detailsArray of objects with more specific error information when applicable.falsearray | null
messageHuman-readable string describing the error.truestring
targetA string indicating the target of the error. For example, the name of the property in error.falsestring | null

500 response

Get a test run by ID

GET /cloud/v6/test_runs/{id}

Fetch a single test run.

Request parameters

NameDescriptionInRequiredType
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.
headertrueinteger
idID of the load test run.pathtrueinteger

200 response

OK.

Content type: application/json

The API model for a test run.

TestRunApiModel properties:

NameDescriptionRequiredType
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.
trueTestCostApiModel | null
createdDate and time when the test run was started.truestring , format: date-time
distributionList of the load zones configured for the test and the corresponding distribution percentages.truearray | null
endedDate and time when the test run ended. Unset if the test is still running.truestring | null , format: date-time
idID of the test run.trueinteger
noteUser-defined note for the test run.truestring
optionsThe original options object if available.trueobject | null
project_idID of the parent project.trueinteger
resultTest run result. passed if there were no issues, failed if thresholds were breached, error if the execution was not completed.truestring | null
result_detailsAdditional information about the test run result.trueobject | null
retention_expiryTimestamp after which the test run results are deleted or null if the test run is saved.truestring | null , format: date-time
started_byEmail of the user who started the test if started with a user token.truestring | null , format: email
statusCurrent test run status.truestring
status_detailsDetails of the current test run status.trueStatusApiModel
status_historyList of test run status objects sorted by the enter time representing the status history.trueArray[StatusApiModel]
test_idID of the parent test.trueinteger

Details of the test run status.

StatusApiModel properties:

NameDescriptionRequiredType
enteredDate and time when the test run entered the status.truestring , format: date-time
extraExtra information about the indicated status.falseStatusExtraApiModel | null
typeType of simple test run status: created, queued, initializing, running, processing_metrics, completed or aborted.truestring

StatusExtraApiModel properties:

NameDescriptionRequiredType
by_userEmail of the user that set the status if applicable.truestring | null , format: email
codeService-defined error code if applicable.trueinteger | null
messageHuman-readable string describing the error if applicable.truestring | null

TestCostApiModel properties:

NameDescriptionRequiredType
breakdowntrueTestCostBreakdownApiModel
total_vuhTotal number of VUH charged for the test run.true

Breakdown details of the test cost.

TestCostBreakdownApiModel properties:

NameDescriptionRequiredType
browser_vuhNumber of VUH charged for the browser part of the test run.true
protocol_vuhNumber of VUH charged for the protocol part of the test run.true
Completed example
{
  "cost": {
    "breakdown": {
      "browser_vuh": 0,
      "protocol_vuh": 10
    },
    "total_vuh": 10
  },
  "created": "2024-06-01T19:00:00Z",
  "distribution": [
    {
      "load_zone": "amazon:us:ashburn",
      "percent": 100
    }
  ],
  "ended": "2024-06-01T19:30:30Z",
  "id": 1234,
  "note": "User-defined note for the test run.",
  "options": {
    "cloud": {
      "distribution": {
        "amazon:us:ashburn": {
          "loadZone": "amazon:us:ashburn",
          "percent": 100
        }
      },
      "projectID": 12
    },
    "stages": [
      {
        "duration": "10m",
        "target": 10
      },
      {
        "duration": "20m",
        "target": 10
      }
    ]
  },
  "project_id": 12,
  "result": "success",
  "result_details": {},
  "retention_expiry": "2024-07-01T19:30:30Z",
  "started_by": "user@example.com",
  "status": "completed",
  "status_details": {
    "entered": "2024-06-01T19:30:30Z",
    "type": "completed"
  },
  "status_history": [
    {
      "entered": "2024-06-01T19:00:00Z",
      "type": "created"
    },
    {
      "entered": "2024-06-01T19:00:10Z",
      "type": "initializing"
    },
    {
      "entered": "2024-06-01T19:00:20Z",
      "type": "running"
    },
    {
      "entered": "2024-06-01T19:30:20Z",
      "type": "processing_metrics"
    },
    {
      "entered": "2024-06-01T19:30:30Z",
      "type": "completed"
    }
  ],
  "test_id": 123
}
Running example
{
  "cost": {
    "breakdown": {
      "browser_vuh": 0,
      "protocol_vuh": 10
    },
    "total_vuh": 10
  },
  "created": "2024-06-01T19:00:00Z",
  "distribution": [
    {
      "load_zone": "amazon:us:ashburn",
      "percent": 100
    }
  ],
  "ended": null,
  "id": 1234,
  "note": "User-defined note for the test run.",
  "options": {
    "cloud": {
      "distribution": {
        "amazon:us:ashburn": {
          "loadZone": "amazon:us:ashburn",
          "percent": 100
        }
      },
      "projectID": 12
    },
    "stages": [
      {
        "duration": "10m",
        "target": 10
      },
      {
        "duration": "20m",
        "target": 10
      }
    ]
  },
  "project_id": 12,
  "result": null,
  "result_details": {},
  "retention_expiry": "2024-07-01T19:30:30Z",
  "started_by": "user@example.com",
  "status": "running",
  "status_details": {
    "entered": "2024-06-01T19:00:20Z",
    "type": "running"
  },
  "status_history": [
    {
      "entered": "2024-06-01T19:00:00Z",
      "type": "created"
    },
    {
      "entered": "2024-06-01T19:00:10Z",
      "type": "initializing"
    },
    {
      "entered": "2024-06-01T19:00:20Z",
      "type": "running"
    }
  ],
  "test_id": 123
}
ValidationError example
{
  "cost": null,
  "created": "2024-06-01T19:00:00Z",
  "distribution": null,
  "ended": "2024-06-01T19:00:10Z",
  "id": 1234,
  "note": "",
  "options": null,
  "project_id": 12,
  "result": "error",
  "result_details": {},
  "retention_expiry": "2024-07-01T19:00:10Z",
  "started_by": "user@example.com",
  "status": "aborted",
  "status_details": {
    "entered": "2024-06-24T19:44:36.46Z",
    "extra": {
      "by_user": null,
      "code": 123,
      "message": "Validation error"
    },
    "type": "aborted"
  },
  "status_history": [
    {
      "entered": "2024-06-01T19:00:00Z",
      "type": "created"
    },
    {
      "entered": "2024-06-01T19:00:10Z",
      "extra": {
        "by_user": null,
        "code": 123,
        "message": "Validation error"
      },
      "type": "aborted"
    }
  ],
  "test_id": 123
}

401 response

403 response

404 response

500 response

Update a test run

PATCH /cloud/v6/test_runs/{id}

Update a test run.

Request parameters

NameDescriptionInRequiredType
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.
headertrueinteger
idID of the load test run.pathtrueinteger

Request body

Content type: application/json

PatchTestRunApiModel properties:

NameDescriptionRequiredType
noteUser-defined note for the test run.truestring
Update example
{
  "note": "New note for the test run"
}

204 response

OK.

400 response

401 response

403 response

404 response

500 response

Abort a running test

POST /cloud/v6/test_runs/{id}/abort

Abort a running test.

Request parameters

NameDescriptionInRequiredType
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.
headertrueinteger
idID of the load test run.pathtrueinteger

204 response

OK.

401 response

403 response

404 response

409 response

Cannot abort a non-running test.

Content type: application/json

ErrorResponseApiModel properties:

NameDescriptionRequiredType
errortrueErrorApiModel

Details of the error.

ErrorApiModel properties:

NameDescriptionRequiredType
codeService-defined error code.truestring
detailsArray of objects with more specific error information when applicable.falsearray | null
messageHuman-readable string describing the error.truestring
targetA string indicating the target of the error. For example, the name of the property in error.falsestring | null

500 response

Save test run results

POST /cloud/v6/test_runs/{id}/save

Persist test run results to keep them past the data-retention period.

Request parameters

NameDescriptionInRequiredType
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.
headertrueinteger
idID of the load test run.pathtrueinteger

204 response

OK.

401 response

403 response

404 response

409 response

The test run results have been deleted, or the maximum number of saved test runs has been reached.

Content type: application/json

ErrorResponseApiModel properties:

NameDescriptionRequiredType
errortrueErrorApiModel

Details of the error.

ErrorApiModel properties:

NameDescriptionRequiredType
codeService-defined error code.truestring
detailsArray of objects with more specific error information when applicable.falsearray | null
messageHuman-readable string describing the error.truestring
targetA string indicating the target of the error. For example, the name of the property in error.falsestring | null
Deleted example
{
  "error": {
    "code": "conflict",
    "message": "Test run has been deleted"
  }
}
LimitReached example
{
  "error": {
    "code": "conflict",
    "message": "The maximum number of saved test runs has been reached"
  }
}

500 response

Download the test run script

GET /cloud/v6/test_runs/{id}/script

Download the test run script.

Request parameters

NameDescriptionInRequiredType
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.
headertrueinteger
idID of the load test run.pathtrueinteger

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

Unsave test run results

POST /cloud/v6/test_runs/{id}/unsave

Disable persistence of the test run results past the data-retention period.

The data will be automatically deleted at the end of the retention period.

Request parameters

NameDescriptionInRequiredType
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.
headertrueinteger
idID of the load test run.pathtrueinteger

204 response

OK.

401 response

403 response

404 response

500 response