--- title: "Metrics REST API | Grafana Cloud documentation" description: "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." --- # 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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```http GET https://api.k6.io/cloud/v5/test_runs/152779/metrics Accept: application/json Authorization: Bearer 56c166885f9a7fc1e588a1b3cb66f6dd ``` **Example response** http ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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 metrics across multiple test runs These endpoints allow you to list metrics metadata from multiple test runs within a load test. This is useful for understanding which metrics are available across multiple runs and their associated labels. ### List metrics from last N runs `GET /cloud/v5/load_tests/:loadTestId/metrics` `GET /cloud/v5/load_tests/:loadTestId/metrics(test_run_count=:count)` Lists metrics from the last `test_run_count` runs in the load test. If no `test_run_count` is specified, returns metrics from the last 30 runs. **Parameters**: Expand table | Parameter | Type | Description | |------------------|---------|------------------------------------------------------------------------| | `test_run_count` | integer | Optional: Number of last runs to include. Default is 30. Example: `20` | **Example request**: http ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```http GET https://api.k6.io/cloud/v5/load_tests/1529/metrics(test_run_count=5) Accept: application/json Authorization: Bearer 56c166885f9a7fc1e588a1b3cb66f6dd ``` ### List metrics from specific runs `GET /cloud/v5/load_tests/:loadTestId/metrics(test_run_ids=[:id1,:id2,...])` Lists metrics from specific test runs by their IDs. **Parameters**: Expand table | Parameter | Type | Description | |----------------|---------------|--------------------------------------------------------------------| | `test_run_ids` | integer array | Required: Array of test run IDs. Example: `[152779,152782,152785]` | **Example request**: http ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```http GET https://api.k6.io/cloud/v5/load_tests/1529/metrics(test_run_ids=[152779,152782,152785]) Accept: application/json Authorization: Bearer 56c166885f9a7fc1e588a1b3cb66f6dd ``` **Example response** (for both endpoints): http ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```http HTTP/1.1 200 Content-Type: application/json { "value": [ { "name": "http_req_duration", "type": "trend", "labels": ["expected_response", "group", "method", "name", "proto", "scenario", "status", "url"] }, { "name": "http_reqs", "type": "counter", "labels": ["expected_response", "group", "method", "name", "proto", "scenario", "status", "url"] }, { "name": "vus", "type": "gauge", "labels": ["load_zone"] } ] } ``` ### Response format The response contains an array of metric objects with the following fields: Expand table | Field | Type | Description | |----------|-----------|-------------------------------------------------------------------------------| | `name` | string | The name of the metric. | | `type` | string | The metric type: `counter`, `gauge`, `rate`, or `trend`. | | `labels` | string\[] | Array of label names available for this metric across the selected test runs. | ### Notes - If a metric has different types across multiple runs, the type from the latest run is used. - The `labels` field contains all unique label names found across all selected test runs for each metric. - Metrics are returned in alphabetical order by name. ### Alternative endpoint paths All `/metrics` endpoints also support an `/ms` alias to prevent issues with ad blockers: - `GET /cloud/v5/load_tests/:loadTestId/ms` - `GET /cloud/v5/load_tests/:loadTestId/ms(test_run_count=:count)` - `GET /cloud/v5/load_tests/:loadTestId/ms(test_run_ids=[:id1,:id2,...])` ## List time series > Note > > This API output is similar to [Prometheus series API](https://prometheus.io/docs/prometheus/latest/querying/api/#finding-series-by-label-matchers) `GET /cloud/v5/test_runs/:testRunId/series` Expand table | Parameter | Description | |-----------|------------------------------------------------------------------------------------------------------------------------| | `match[]` | Repeated series selector argument that selects the series to return. At least one `match[]` argument must be provided. | **Example request**: http ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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](https://prometheus.io/docs/prometheus/latest/querying/api/#getting-label-names) `GET /cloud/v5/test_runs/:testRunId/labels` Expand table | Parameter | Description | |-----------|---------------------------------------------------------------------------------------------------------| | `match[]` | Optional: repeated series selector argument that selects the series from which to read the label names. | **Example request**: http ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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](https://prometheus.io/docs/prometheus/latest/querying/api/#querying-label-values) `GET /test_runs/:testRunId/label/:labelName/values` Expand table | Parameter | Description | |-----------|----------------------------------------------------------------------------------------------------------| | `match[]` | Optional: repeated series selector argument that selects the series from which to read the label values. | **Example request**: http ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries) ### Request Parameters Expand table | Parameter | Type | Description | |-----------|---------|----------------------------------------------------------------------------------------------------------------------------------------| | query | string | Required: query expression for selecting metrics. Possible values depend on the metric type. See below for detailed list and examples. | | metric | string | Required: name of the metric to query, with optional labels selector.
*Example*: \`http\_reqs{expected\_response=“true”} | | step | int | Optional: The step size in seconds for the query range. | | start | iso8601 | Optional: The start timestamp for the query range. Default is test run start. *Example*: `2022-11-23T10:03:00Z` | | end | iso8601 | Optional: The end timestamp for the query range. Default is test run end. *Example*: `2022-11-23T10:13:00Z` | **Example request**: http ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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: ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```none /cloud/v5/test_runs/:testRunId/query_range_k6(metric='vus',query='sum(last by (instance_id))') ``` Get a chart of requests per second: ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```none /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: ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```none /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: ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```none /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](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries) ### Request Parameters Expand table | Parameter | Type | Description | |-----------|---------|----------------------------------------------------------------------------------------------------------------------------------------| | query | string | Required: query expression for selecting metrics. Possible values depend on the metric type. See below for detailed list and examples. | | metric | string | Required: name of the metric to query, with optional labels selector.
*Example*: \`http\_reqs{expected\_response=“true”} | | start | iso8601 | The start timestamp for the query range. Default is test run start. *Example*: `2022-01-02T10:03:00Z` | | end | iso8601 | The end timestamp for the query range. Default is test run end. *Example*: `2022-01-02T10:13:00Z` | **Example request**: http ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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: ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```none /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: ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```none /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: ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```none /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: ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```none /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: ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```none /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: ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```none /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, for example `http_reqs`, followed by optional label filters in curly braces, for example `{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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```none http_req_duration ``` ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```none http_req_duration{status="200"} ``` ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```none http_req_duration{status~="(2|3)\d\d"} ``` ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```none http_req_duration{status!="0"} ``` ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```none 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](/docs/k6/latest/using-k6/metrics/): *Counter*, *Gauge*, *Rate* and *Trend*. Each of these offer a distinct set of *methods* for operating that data type. ### Counter methods Expand table | Method | Description | PromQL equivalent | |------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------| | `increase` | Total 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])` | | `rate` | Average increase per second. Equals to `increase` divided by time span size in seconds. | `rate(metric_name[$__interval])` | | `value` | Growing counter value. | `metric_name` | | `cumrate` | Cumulative rate from test run start. Equals to `value` divided by time elapsed since test run start. | | | `max_rate()` | Get `rate` for each `` seconds within time span and return the max value. Used e.g. for “peak RPS” value in test run stats.
`` must be an integer. | `max_over_time(rate(metric_name[])[$__interval:])` | ### Gauge methods Expand table | Method | Description | PromQL equivalent | |-------------|-----------------------------------|-------------------------------------------| | `last` | Last observed value. | `metric_name` | | `min` | Min observed value. | `min_over_time(metric_name[$__interval])` | | `max` | Max observed value. | `max_over_time(metric_name[$__interval])` | | `avg` | Average of observed values. | `avg_over_time(metric_name[$__interval])` | | `last_time` | Timestamp of last observed value. | `timestamp(metric_name)` | ### Rate methods Expand table | Method | Description | PromQL equivalent | |------------------|----------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------| | `increase_total` | Total increase of all observations counter in the time span. | `increase(metric_name[$__interval])` | | `rate_total` | Average increase per second of all observations counter. | `rate(metric_name[$__interval])` | | `value_total` | Growing value of all observations counter. | `metric_name` | | `increase_nz` | Total increase of nonzero-value observations counter in the time span. | `increase(metric_name{nonzero="true"}[$__interval])` | | `rate_nz` | Average increase per second of nonzero-value observations counter. | `rate(metric_name{nonzero="true"}[$__interval])` | | `value_nz` | Growing value of nonzero-value observations counter. | `metric_name{nonzero="true"}` | | `increase_z` | Total increase of zero-value observations counter in the time span. | `increase(metric_name{nonzero="false"}[$__interval])` | | `rate_z` | Average increase per second of zero-value observations counter. | `rate(metric_name{nonzero="false"}[$__interval])` | | `value_z` | Growing value of zero-value observations counter. | `metric_name{nonzero="false"}` | | `ratio` | Ratio (fraction) of nonzero-value observations count increase to total increase. | `increase(metric_name{nonzero="false"}[$__interval]) / increase(metric_name[$__interval])` | ### Trend methods Expand table | Method | Description | PromQL equivalent | |----------------------------------|-----------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------| | `histogram_max` | Max observed value. | | | `histogram_min` | Min observed value. | | | `histogram_avg` | Average of observed values. | | | `histogram_stddev` | Standard deviation. | | | `histogram_quantile()` | Quantile of histogram observations.
`` parameter must be a number between 0 and 1. | `histogram_quantile(, rate(hist_metric_name_bucket[$__interval]))` | | `histogram_count_increase` | Increase of observations counter. | `increase(hist_metric_name_count[$__interval])` | | `histogram_count_value` | Growing 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: ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```none by (