DocumentationGrafana CloudTest applications and servicesPerformance TestingReference pagesCloud REST APIMetrics Values

Metrics Values REST API

Use these endpoints to query metrics values from test runs.

Query range values

GET /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 '.

Request Parameters

Example request:

http Copy

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: Token 56c166885f9a7fc1e588a1b3cb66f6dd

Example response

http Copy

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 Copy

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: Token 56c166885f9a7fc1e588a1b3cb66f6dd

Query aggregate values

GET /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 '.

Request Parameters

Example request:

http Copy

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: Token 56c166885f9a7fc1e588a1b3cb66f6dd

Example response

http Copy

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
          ]
        ]
      }
    ]
  }
}

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:

Copy

http_req_duration

Copy

http_req_duration{status="200"}

Copy

http_req_duration{status~="(2|3)\d\d"}

Copy

http_req_duration{status!="0"}

Copy

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

Gauge methods

Rate methods

Trend methods

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:

Copy

<method> by (<label list>)

Examples:

Copy

# 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:

Copy

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

Examples:

Copy

# 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)