Metrics REST API
Documentationbreadcrumb arrow Grafana Cloudbreadcrumb arrow Testing and syntheticsbreadcrumb arrow Performance testingbreadcrumb arrow Reference pagesbreadcrumb arrow Cloud REST APIbreadcrumb arrow Metrics
Grafana Cloud

Metrics REST API

Use these endpoints to access metrics metadata and metrics values from test runs.

Note

The metrics endpoints use the v5 version of the Grafana Cloud k6 API. Make sure to use the correct version when defining the URL in your scripts or applications to avoid any errors.

List metrics

GET /cloud/v5/test_runs/:testRunId/metrics

Example request:

http 
GET https://api.k6.io/cloud/v5/test_runs/152779/metrics
Accept: application/json
Authorization: Bearer 56c166885f9a7fc1e588a1b3cb66f6dd

Example response

http 
HTTP/1.1 200
Content-Type: application/json

{
  "value": [
    {
      "id": "1af77c11-5b93-58ba-b7a2-c839b0402cf7",
      "name": "load_generator_file_handles",
      "origin": "builtin",
      "test_run_id": 152779,
      "type": "gauge"
    },
    {
      "id": "38ae6276-4630-5ad6-a3bb-d11f678d96dd",
      "name": "iteration_duration",
      "origin": "builtin",
      "test_run_id": 152779,
      "type": "trend"
    },
    {
      "id": "4643ca9f-9539-5e86-9937-2ae956f9dcc4",
      "name": "data_sent",
      "origin": "builtin",
      "test_run_id": 152779,
      "type": "counter"
    },
    {
      "id": "5d0b30bf-321c-5c2d-a318-ebfb7d79c915",
      "name": "vus",
      "origin": "builtin",
      "test_run_id": 152779,
      "type": "gauge"
    }
  ]
}

List time series

Note

This API output is similar to Prometheus series API

GET /cloud/v5/test_runs/:testRunId/series

ParameterDescription
match[]Repeated series selector argument that selects the series to return. At least one match[] argument must be provided.

Example request:

http 
GET https://api.k6.io/cloud/v5/test_runs/152777/series?match[]=http_req_duration{expected_response="true"}
Accept: application/json
Authorization: Bearer 56c166885f9a7fc1e588a1b3cb66f6dd

Example response

http 
HTTP/1.1 200
Content-Type: application/json

{
  "status": "success",
  "data": [
    {
      "__name__": "http_req_duration",
      "expected_response": "true",
      "group": "::g2",
      "load_zone": "amazon:us:columbus",
      "method": "GET",
      "name": "http://test.k6.io/",
      "proto": "HTTP/1.1",
      "scenario": "http_with_groups",
      "status": "200",
      "test_run_id": "152777",
      "url": "http://test.k6.io/"
    },
    {
      "__name__": "http_req_duration",
      "expected_response": "true",
      "group": "",
      "load_zone": "amazon:us:columbus",
      "method": "GET",
      "name": "http://test.k6.io/?q=3",
      "proto": "HTTP/1.1",
      "scenario": "http_simple",
      "status": "200",
      "test_run_id": "152777",
      "url": "http://test.k6.io/?q=3"
    }
  ]
}

Query label names

Note

This API output is similar to Prometheus labels API

GET /cloud/v5/test_runs/:testRunId/labels

ParameterDescription
match[]Optional: repeated series selector argument that selects the series from which to read the label names.

Example request:

http 
GET https://api.k6.io/cloud/v5/test_runs/152777/labels?match[]=http_req_duration
Accept: application/json
Authorization: Bearer 56c166885f9a7fc1e588a1b3cb66f6dd

Example response

http 
HTTP/1.1 200
Content-Type: application/json

{
  "status": "success"
  "data": [
    "__name__",
    "expected_response",
    "group",
    "load_zone",
    "method",
    "name",
    "proto",
    "scenario",
    "status",
    "test_run_id",
    "url"
  ],
}

Query label values

Note

This API output is similar to Prometheus label values API

GET /test_runs/:testRunId/label/:labelName/values

ParameterDescription
match[]Optional: repeated series selector argument that selects the series from which to read the label values.

Example request:

http 
GET https://api.k6.io/cloud/v5/test_runs/152777/label/load_zone/values?match[]=http_req_duration
Accept: application/json
Authorization: Bearer 56c166885f9a7fc1e588a1b3cb66f6dd

Example response

http 
HTTP/1.1 200
Content-Type: application/json

{
  "status": "success"
  "data": [
    "amazon:us:columbus",
    "amazon:eu:dublin",
  ],
}

Query range values

GET /cloud/v5/test_runs/:testRunId/query_range_k6(:parameters)

Range query returns multiple sample values for a given metric over a time range.

Parameters are a comma-separated list in the format of key=value. String values should be surrounded by single quotes '.

Note

This API output is similar to Prometheus range query API

Request Parameters

ParameterTypeDescription
querystringRequired: query expression for selecting metrics. Possible values depend on the metric type. See below for detailed list and examples.
metricstringRequired: name of the metric to query, with optional labels selector.
Example: `http_reqs{expected_response=“true”}
stepintOptional: The step size in seconds for the query range.
startiso8601Optional: The start timestamp for the query range. Default is test run start. Example: 2022-11-23T10:03:00Z
endiso8601Optional: The end timestamp for the query range. Default is test run end. Example: 2022-11-23T10:13:00Z

Example request:

http 
GET https://api.k6.io/cloud/v5/test_runs/152779/query_range_k6(query='increase by (name,status)',metric='http_reqs{status!="0"}',step=5)
Accept: application/json
Authorization: Bearer 56c166885f9a7fc1e588a1b3cb66f6dd

Example response

http 
HTTP/1.1 200
Content-Type: application/json

{
  "status": "success",
  "data": {
    "resultType": "matrix",
    "result": [
      {
        "metric": {
          "__name__": "http_reqs",
          "name": "login page",
          "status": "200",
          "test_run_id": "152779"
        },
        "values": [
          [
            1684949415,
            845
          ],
          [
            1684949420,
            1034
          ]
        ]
      },
      {
        "metric": {
          "__name__": "http_reqs",
          "name": "http://test.k6.io/",
          "status": "200",
          "test_run_id": "152779"
        },
        "values": [
          [
            1684949415,
            16035
          ],
          [
            1684949420,
            54535
          ],
        ]
      }
    ]
  }
}

Example request with a time filter:

http 
GET https://api.k6.io/cloud/v5/test_runs/152779/query_range_k6(query='increase by (name,status)',metric='http_reqs{method="GET",status="2\d\d"}',step=5,start=2022-11-23T10:03:00Z,end=2022-11-23T10:13:00Z)
Accept: application/json
Authorization: Bearer 56c166885f9a7fc1e588a1b3cb66f6dd

Cheat sheet

Get a chart of simultaneous VUs during the test run:

/cloud/v5/test_runs/:testRunId/query_range_k6(metric='vus',query='sum(last by (instance_id))')

Get a chart of requests per second:

/cloud/v5/test_runs/:testRunId/query_range_k6(metric='http_reqs',query='rate')

Get a chart of requests per second, excluding network errors (where status equals to "0"), separated by URL and HTTP method:

/cloud/v5/test_runs/:testRunId/query_range_k6(metric='http_reqs{status!="0"}',query='rate by (name,method)')

Get a chart of the 95th percentile of HTTP request response times, separated by URL, HTTP method, and HTTP status code, with 10 second resolution, and filtered for a specific time range:

/test_runs/:testRunId/query_range_k6(metric='http_req_duration',query='histogram_quantile(0.95) by (name,method,status)',step=10,start=2021-08-09T12:01:10Z,end=2021-08-09T12:09:13Z)

Query aggregate values

GET /cloud/v5/test_runs/:testRunId/query_aggregate_k6(:parameters)

Aggregate query returns a single sample value for a given metric over the duration of the test run.

Parameters are a comma-separated list in the format of key=value. String values should be surrounded by single quotes '.

Note

This API output is similar to Prometheus range query API

Request Parameters

ParameterTypeDescription
querystringRequired: query expression for selecting metrics. Possible values depend on the metric type. See below for detailed list and examples.
metricstringRequired: name of the metric to query, with optional labels selector.
Example: `http_reqs{expected_response=“true”}
startiso8601The start timestamp for the query range. Default is test run start. Example: 2022-01-02T10:03:00Z
endiso8601The end timestamp for the query range. Default is test run end. Example: 2022-01-02T10:13:00Z

Example request:

http 
GET https://api.k6.io/cloud/v5/test_runs/152779/query_aggregate_k6(query='histogram_quantile(0.95) by (name,status)',metric='http_req_duration')
Accept: application/json
Authorization: Bearer 56c166885f9a7fc1e588a1b3cb66f6dd

Example response

http 
HTTP/1.1 200
Content-Type: application/json

{
  "status": "success",
  "data": {
    "resultType": "vector",
    "result": [
      {
        "metric": {
          "__name__": "http_req_duration",
          "name": "http://test.k6.io/?q=2",
          "status": "200",
          "test_run_id": "152779"
        },
        "values": [
          [
            1684950639,
            14207
          ]
        ]
      },
      {
        "metric": {
          "__name__": "http_req_duration",
          "name": "http://test.k6.io/?q=1",
          "status": "500",
          "test_run_id": "152779"
        },
        "values": [
          [
            1684950639,
            28031
          ]
        ]
      }
    ]
  }
}

Cheat sheet

Get the total number of HTTP requests made during the test run:

/cloud/v5/test_runs/:testRunId/query_aggregate_k6(metric='http_reqs',query='increase')

Get the number of HTTP requests made within a specific time period:

/cloud/v5/test_runs/:testRunId/query_aggregate_k6(metric='http_reqs',query='increase',start=2021-08-09T12:01:10Z,end=2021-08-09T12:09:13Z)

Get the 95th percentile of HTTP request response times, separated by URL, HTTP method, and HTTP status code:

/cloud/v5/test_runs/:testRunId/query_aggregate_k6(metric='http_req_duration',query='historgam_quantile(0.95) by (name,method,status)')

Get the peak requests per second during the test run with 5 second precision, for requests with statuses 2xx and 3xx, separated by URL:

/cloud/v5/test_runs/:testRunId/query_aggregate_k6(metric='http_reqs{status~="[23][0-9]{2}"}',query='max_rate(5) by (name)')

Get peak CPU usage of each instance during test run, averaged between instances:

/cloud/v5/test_runs/:testRunId/query_aggregate_k6(metric='load_generator_cpu_percent',query='avg(max by (instance))')

Get peak simultaneous VUs during the test run:

/cloud/v5/test_runs/:testRunId/query_aggregate_k6(metric='vus',query='sum(max by (instance_id))')

Specifying metric name

The metric parameter can be used to specify the metric name and optional label filter. The syntax is similar to that of Prometheus selectors: metric name, e.g. http_reqs, followed by optional label filters in curly braces, e.g. {status="200"}.

The following operators are supported for label matching:

  • =: Equal to the provided string.
  • !=: Not equal to the provided string.
  • =~: Regex-match the provided string.
  • !~: Do not regex-match the provided string.

Examples:

http_req_duration
http_req_duration{status="200"}
http_req_duration{status~="(2|3)\d\d"}
http_req_duration{status!="0"}
http_req_duration{status!="0",name="login page"}

Specifying query expression

The query parameter can be used to specify the function applied to the metric to produce values.

Basic methods

A method is a basic function that gives a numerical value when applied to some time span of a metric.

For range queries (like the ones that produce graphs over time) the timespans are windows between each returned datapoint. For aggregate queries (like getting total number of requests in the test run) the timespan is the whole test run.

k6 has 4 metric types: Counter, Gauge, Rate and Trend. Each of these offer a distinct set of methods for operating that data type.

Counter methods

MethodDescriptionPromQL equivalent
increaseTotal increase of counter’s value in the time span. For a metric like http_reqs this will be the number of requests.increase(metric_name[$__interval])
rateAverage increase per second. Equals to increase divided by time span size in seconds.rate(metric_name[$__interval])
valueGrowing counter value.metric_name
cumrateCumulative rate from test run start. Equals to value divided by time elapsed since test run start.
max_rate(<interval>)Get rate for each <interval> seconds within time span and return the max value. Used e.g. for “peak RPS” value in test run stats.
<interval> must be an integer.		max_over_time(rate(metric_name[<interval>])[$__interval:<interval>])

Gauge methods

MethodDescriptionPromQL equivalent
lastLast observed value.metric_name
minMin observed value.min_over_time(metric_name[$__interval])
maxMax observed value.max_over_time(metric_name[$__interval])
avgAverage of observed values.avg_over_time(metric_name[$__interval])
last_timeTimestamp of last observed value.timestamp(metric_name)

Rate methods

MethodDescriptionPromQL equivalent
increase_totalTotal increase of all observations counter in the time span.increase(metric_name[$__interval])
rate_totalAverage increase per second of all observations counter.rate(metric_name[$__interval])
value_totalGrowing value of all observations counter.metric_name
increase_nzTotal increase of nonzero-value observations counter in the time span.increase(metric_name{nonzero="true"}[$__interval])
rate_nzAverage increase per second of nonzero-value observations counter.rate(metric_name{nonzero="true"}[$__interval])
value_nzGrowing value of nonzero-value observations counter.metric_name{nonzero="true"}
increase_zTotal increase of zero-value observations counter in the time span.increase(metric_name{nonzero="false"}[$__interval])
rate_zAverage increase per second of zero-value observations counter.rate(metric_name{nonzero="false"}[$__interval])
value_zGrowing value of zero-value observations counter.metric_name{nonzero="false"}
ratioRatio (fraction) of nonzero-value observations count increase to total increase.increase(metric_name{nonzero="false"}[$__interval]) / increase(metric_name[$__interval])

Trend methods

MethodDescriptionPromQL equivalent
histogram_maxMax observed value.
histogram_minMin observed value.
histogram_avgAverage of observed values.
histogram_stddevStandard deviation.
histogram_quantile(<quantile>)Quantile of histogram observations.
<quantile> parameter must be a number between 0 and 1.		histogram_quantile(<quantile>, rate(hist_metric_name_bucket[$__interval]))
histogram_count_increaseIncrease of observations counter.increase(hist_metric_name_count[$__interval])
histogram_count_valueGrowing value of observations counter.hist_metric_name

Returning multiple type series

Using a method as-is to query a metric produces a single time series, aggregating all values.

To preserve some labels and get multiple time series, use the following syntax:

<method> by (<label list>)

Examples:

# 95th-percentiles or "http_req_duration" metric (Trend), separated by URL ("name" label) and HTTP status ("status" label)
histogram_quantile(0.95) by (name, status)

# Peak CPU usage (Gauge) for each load generator instance
max by (instance_id)

Aggregating over labels dimension

You can further aggregate time series produced with queries using by syntax. Use aggregators to aggregate values for each time bucket across labels dimensions.

Supported aggregators are min, max, sum and avg.

They work similarly to Prometheus aggregation operators

Syntax:

<aggregator>(<method-expr>) [by (<label list>)]

Examples:

# Active VUs count on "vus" metric
sum(last by (instance_id))

# Average request rate on "http_reqs" metric across URLs, separated by HTTP method
avg(rate by (name, method)) by (method)