Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.
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'{
"data": {
"attributes": {
"paused": false,
"running": true,
"tainted": false,
"vus": 1
},
"id": "default",
"type": "status"
}
}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"
}
}'{
"data": {
"type": "status",
"id": "default",
"attributes": {
"paused": true,
"vus": 1,
"running": true,
"tainted": false
}
}
}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'{
"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
PUT 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 '{
"data": {
"attributes": {
"data": {
"a": 1,
"b": 2
}
},
"id": "default",
"type": "setupData"
}
}'{
"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.
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
}
}
}'{
"data": {
"type": "status",
"id": "default",
"attributes": {
"stopped": true
}
}
}This call parses the JSON request body to update the status and stop a running test.
Was this page helpful?
Related resources from Grafana Labs
