Documentation

Grafana k6

Reference

k6 REST API

Open source

k6 REST API

k6 can expose an HTTP server with a REST API that can be used to control some parameters of the test execution.

Starting in k6 v2.0.0, this server is off by default. To enable it, opt in by passing the --address CLI flag (or setting the K6_ADDRESS environment variable) when starting k6:

k6 run --address=localhost:6565 script.js

The address you pass is where the REST API listens. The examples below assume you started k6 with --address=localhost:6565; if you use a different address, substitute it in the URLs.

In earlier versions of k6, this server was on by default and listened on localhost:6565 unless you opted out. The flag itself (--address) is unchanged.

With this API you can inspect execution status, pause or resume a test, stop a test, list groups, and set or get setup data.

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'

{
  "data": {
    "attributes": {
      "status": 7,
      "paused": false,
      "vus": 1,
      "vus-max": 1,
      "stopped": false,
      "running": true,
      "tainted": false
    },
    "id": "default",
    "type": "status"
  }
}

The status attribute is the numeric execution state:

Value	State
`0`	Created
`1`	Initializing VUs
`2`	Initializing executors
`3`	Initialization complete
`4`	Paused before the run
`5`	Started
`6`	Running setup
`7`	Running
`8`	Running teardown
`9`	Ended
`10`	Interrupted
`11`	Marked as failed

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
        },
        "id": "default",
        "type": "status"
    }
}'

{
  "data": {
    "type": "status",
    "id": "default",
    "attributes": {
      "status": 7,
      "paused": true,
      "vus": 1,
      "vus-max": 1,
      "stopped": false,
      "running": true,
      "tainted": false
    }
  }
}

This endpoint lets you pause, resume, or stop a running test. The vus and vus-max attributes are read-only. k6 doesn’t support updating the VU configuration during a run.

List Metrics

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

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

{
  "data": [
    {
      "type": "metrics",
      "id": "http_req_duration",
      "attributes": {
        "type": "trend",
        "contains": "time",
        "tainted": null,
        "sample": {
          "avg": 122.529465,
          "max": 179.098624,
          "med": 115.83006,
          "min": 107.743524,
          "p(90)": 136.9331272,
          "p(95)": 158.01587559999996
        }
      }
    },
    {
      "type": "metrics",
      "id": "http_req_connecting",
      "attributes": {
        "type": "trend",
        "contains": "time",
        "tainted": null,
        "sample": {
          "avg": 11.2357072,
          "max": 112.357072,
          "med": 0,
          "min": 0,
          "p(90)": 11.235707199999961,
          "p(95)": 61.796389599999884
        }
      }
    },
    {
      "type": "metrics",
      "id": "http_req_sending",
      "attributes": {
        "type": "trend",
        "contains": "time",
        "tainted": null,
        "sample": {
          "avg": 0.027994200000000004,
          "max": 0.106594,
          "med": 0.0192965,
          "min": 0.017486,
          "p(90)": 0.03165189999999997,
          "p(95)": 0.0691229499999999
        }
      }
    },
    {
      "type": "metrics",
      "id": "http_req_waiting",
      "attributes": {
        "type": "trend",
        "contains": "time",
        "tainted": null,
        "sample": {
          "avg": 122.33937080000001,
          "max": 179.021285,
          "med": 115.74006299999999,
          "min": 107.650352,
          "p(90)": 136.8561833,
          "p(95)": 157.93873414999996
        }
      }
    },
    {
      "type": "metrics",
      "id": "data_received",
      "attributes": {
        "type": "counter",
        "contains": "data",
        "tainted": null,
        "sample": {
          "count": 13830,
          "rate": 1119.9222882571698
        }
      }
    },
    {
      "type": "metrics",
      "id": "http_req_blocked",
      "attributes": {
        "type": "trend",
        "contains": "time",
        "tainted": null,
        "sample": {
          "avg": 11.364957999999998,
          "max": 113.611988,
          "med": 0.004173,
          "min": 0.003867,
          "p(90)": 11.365557499999959,
          "p(95)": 62.48877274999988
        }
      }
    },
    {
      "type": "metrics",
      "id": "http_req_receiving",
      "attributes": {
        "type": "trend",
        "contains": "time",
        "tainted": null,
        "sample": {
          "avg": 0.16209999999999997,
          "max": 0.757392,
          "med": 0.078622,
          "min": 0.057306,
          "p(90)": 0.2315264999999998,
          "p(95)": 0.4944592499999994
        }
      }
    },
    {
      "type": "metrics",
      "id": "http_reqs",
      "attributes": {
        "type": "counter",
        "contains": "default",
        "tainted": null,
        "sample": {
          "count": 10,
          "rate": 0.8097775041628127
        }
      }
    },
    {
      "type": "metrics",
      "id": "http_req_tls_handshaking",
      "attributes": {
        "type": "trend",
        "contains": "time",
        "tainted": null,
        "sample": {
          "avg": 0,
          "max": 0,
          "med": 0,
          "min": 0,
          "p(90)": 0,
          "p(95)": 0
        }
      }
    },
    {
      "type": "metrics",
      "id": "data_sent",
      "attributes": {
        "type": "counter",
        "contains": "data",
        "tainted": null,
        "sample": {
          "count": 860,
          "rate": 69.64086535800189
        }
      }
    },
    {
      "type": "metrics",
      "id": "iteration_duration",
      "attributes": {
        "type": "trend",
        "contains": "time",
        "tainted": null,
        "sample": {
          "avg": 1134.89821,
          "max": 1238.377413,
          "med": 1118.223518,
          "min": 1108.405498,
          "p(90)": 1185.348477,
          "p(95)": 1211.8629449999999
        }
      }
    },
    {
      "type": "metrics",
      "id": "iterations",
      "attributes": {
        "type": "counter",
        "contains": "default",
        "tainted": null,
        "sample": {
          "count": 10,
          "rate": 0.8097775041628127
        }
      }
    },
    {
      "type": "metrics",
      "id": "vus",
      "attributes": {
        "type": "gauge",
        "contains": "default",
        "tainted": null,
        "sample": {
          "value": 1
        }
      }
    }
  ]
}

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'

{
  "data": {
    "attributes": {
      "contains": "time",
      "sample": {
        "avg": 0.12641856097560983,
        "max": 1.1397,
        "med": 0.074412,
        "min": 0.057858,
        "p(90)": 0.208553,
        "p(95)": 0.218015
      },
      "tainted": null,
      "type": "trend"
    },
    "id": "http_req_receiving",
    "type": "metrics"
  }
}

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'

{
  "data": [
    {
      "type": "groups",
      "id": "d41d8cd98f00b204e9800998ecf8427e",
      "attributes": {
        "path": "",
        "name": "",
        "checks": null
      },
      "relationships": {
        "groups": {
          "data": [
            {
              "type": "groups",
              "id": "b0470a9324a4ae563b04e9ac49fbc9cf"
            }
          ]
        },
        "parent": {
          "data": null
        }
      }
    },
    {
      "type": "groups",
      "id": "b0470a9324a4ae563b04e9ac49fbc9cf",
      "attributes": {
        "path": "::visit homepage",
        "name": "visit homepage",
        "checks": null
      },
      "relationships": {
        "groups": {
          "data": []
        },
        "parent": {
          "data": {
            "type": "groups",
            "id": "d41d8cd98f00b204e9800998ecf8427e"
          }
        }
      }
    }
  ]
}

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'

{
  "data": {
    "type": "groups",
    "id": "b0470a9324a4ae563b04e9ac49fbc9cf",
    "attributes": {
      "path": "::visit homepage",
      "name": "visit homepage",
      "checks": null
    },
    "relationships": {
      "groups": {
        "data": []
      },
      "parent": {
        "data": {
          "type": "groups",
          "id": "d41d8cd98f00b204e9800998ecf8427e"
        }
      }
    }
  }
}

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'

{
  "data": {
    "type": "setupData",
    "id": "default",
    "attributes": {
      "data": {
        "a": 1
      }
    }
  }
}

This endpoint returns the current JSON-encoded setup data.

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

Run Setup

POST http://localhost:6565/v1/setup

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

{
  "data": {
    "type": "setupData",
    "id": "default",
    "attributes": {
      "data": {
        "a": 1
      }
    }
  }
}

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 '{"a": 1, "b": 2}'

{
  "data": {
    "type": "setupData",
    "id": "default",
    "attributes": {
      "data": {
        "a": 1,
        "b": 2
      }
    }
  }
}

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.

Run Teardown

POST http://localhost:6565/v1/teardown

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

This endpoint executes the teardown stage. A successful request returns an empty response with an HTTP 200 status code.

For more detail about the teardown 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 stop a running test. The response contains the complete status object, with stopped set to true.

Was this page helpful?

Create a GitHub issue

Email docs@grafana.com

Help and support

Community