k6 REST API

When k6 starts, it spins up an HTTP server with a REST API that can be used to control some parameters of the test execution. By default, that server listens on localhost:6565, but that can be modified by the --address CLI flag.

With this API you can see and control different execution aspects like number of VUs, Max VUs, pause or resume the test, list groups, set and get the setup data and so on.

You can also find practical usage examples in this blog post.

Get Status

GET http://localhost:6565/v1/status

curl -X GET \
  http://localhost:6565/v1/status \
  -H 'Content-Type: application/json'

Update Status

PATCH http://localhost:6565/v1/status

curl -X PATCH \
  http://localhost:6565/v1/status \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
        "attributes": {
            "paused": true,
            "vus": 1,
        },
        "id": "default",
        "type": "status"
    }
}'

This endpoint lets you pause/resume a running test and set the number of vus and vus-max during the test.

List Metrics

GET http://localhost:6565/v1/metrics

curl -X GET \
  http://localhost:6565/v1/metrics \
  -H 'Content-Type: application/json'

This endpoint will give you all the metrics in the current time. You can see more details on all metrics available and how to create new ones in Metrics.

Get Metric

GET http://localhost:6565/v1/metrics/id

curl -X GET \
  http://localhost:6565/v1/metrics/http_req_receiving \
  -H 'Content-Type: application/json'

This endpoint will give you details for the given metric in the current time.

You can see more on all metrics available and how to create new ones in Metrics.

List Groups

GET http://localhost:6565/v1/groups

curl -X GET \
  http://localhost:6565/v1/groups \
  -H 'Content-Type: application/json'

This endpoint returns all groups available on the test.

For more details on how to create groups please go to Tags and Groups.

Get Group

GET http://localhost:6565/v1/groups/id

curl -X GET \
  http://localhost:6565/v1/groups/b0470a9324a4ae563b04e9ac49fbc9cf \
  -H 'Content-Type: application/json'

This endpoint returns the Group with the given ID.

For more details on how to create groups, please go to Tags and Groups.

Get Setup Data

GET http://localhost:6565/v1/setup

curl -X GET \
  http://localhost:6565/v1/setup \
  -H 'Content-Type: application/json'

This endpoint returns the current JSON-encoded setup data.

For more detail about the setup stage please go to Test life cycle.

Run Setup

PUT http://localhost:6565/v1/setup

curl -X POST \
  http://localhost:6565/v1/setup \
  -H 'Content-Type: application/json'

This endpoint executes the Setup stage and returns the result.

For more detail about the setup stage please go to Test life cycle.

Update Setup

PUT http://localhost:6565/v1/setup

curl -X PUT \
  http://localhost:6565/v1/setup \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
        "attributes": {
            "data": {
                "a": 1,
                "b": 2
            }
        },
        "id": "default",
        "type": "setupData"
    }
}'

This endpoint parses the JSON request body and sets the result as Setup data.

For more detail about the setup stage please go to Test life cycle.

Stop Test

PATCH http://localhost:6565/v1/status

curl -X PATCH \
  http://localhost:6565/v1/status \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "status",
       "id": "default",
       "attributes": {
        "stopped": true
       }
    }
}'

This call parses the JSON request body to update the status and stop a running test.