---
title: "Get metrics with filtering and grouping"
method: POST
path: "/v2/metrics"
tags: ["metrics"]
---

# Get metrics with filtering and grouping

`POST /v2/metrics`

Retrieves metrics data with support for filtering, sorting, and pagination. Metrics are grouped by metric name with individual data points. Supports filtering by direct column fields (bool_value, trace_id, etc.), label fields (labels.agent_name, labels.trace_id), and attribute fields (attributes.*).

## Request body

- RequestGetMetricsRequest
  - `from_timestamp_sec` integer — Start time in Unix seconds timestamp.
  - `to_timestamp_sec` integer — End time in Unix seconds timestamp.
  - `cursor` integer — Pagination cursor for fetching the next page of results. The cursor is returned in the response to the previous request.
  - `environments` string[] — List of environments to filter by
  - `filters` SharedFilterCondition[]
    - `field` string — Field key to filter by. The key is labels attribute on the metric point from the response.metrics object
    - `operator` 'equals' | 'not_equals' | 'contains' | 'not_contains' | 'in' | 'not_in' — Comparison operator.
    - `value` string — Value to filter by.
    - `values` string[] — List of values to filter by. This is only used for the in and not_in operators.
  - `limit` integer — Maximum number of metrics to return per page.
  - `logical_operator` 'AND' | 'OR'
  - `metric_name` string — Metric name to filter by. The metric_name is a metric attribute that is set on the metric object.
  - `metric_source` string — Metric source to filter by. The metric_source is a metric attribute that is set on the metric object.
  - `sort_by` string — Field to sort by.
  - `sort_order` string — Sort order.

## Response `200`

Grouped metrics with data points

- ResponseGetMetricsResponse
  - `metrics` ResponsePaginatedMetricsResponse
    - `data` ResponseMetricGroup[]
      - `metric_name` string — Metric name.
      - `organization_id` string
      - `points` ResponseMetricPoint[] — List of data points for this metric. The `unit` field in each point's `labels` indicates the data type and determines which value field is populated: `bool_value` for booleans, `numeric_value` for numbers, or `enum_value` for strings.
        - `bool_value` boolean
        - `enum_value` string
        - `numeric_value` number
        - `event_time` integer
        - `labels` object — The labels are the attributes of the metric point. The labels are key-value pairs that are used to identify the metric point.
    - `next_cursor` string
    - `total_points` integer
    - `total_results` integer

## Other responses

- `400` — Invalid request parameters
- `404` — Not Found
- `500` — Internal server error

## Changes

> 11 revisions in range; 1 could not be searched.

- **2026-03-09** `1d1c1190a691` — 1 breaking, 2 warning, 6 info
  - request property `filters/items/operator` was restricted to a list of enum values
  - deleted the `path` request parameter `project_id`
  - removed the request property `filters/items/value_type`
  - added the new `contains` enum value to the request property `filters/items/operator`
  - …5 more
- **2026-02-26** `ed3a7440b9d0` — 1 warning, 1 info
  - removed the request property `filters/items/valueType`
  - added the new optional request property `filters/items/value_type`
- **2026-01-04** `ba3b59160a46` — 1 info
  - endpoint added
- **2026-01-01** `aef6c851927f` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/traceloop/apis/traceloop-api/changes/v2/metrics/post.md)

---

[API](https://skmtc.dev/traceloop/apis/traceloop-api.md) · [All operations](https://skmtc.dev/traceloop/apis/traceloop-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/traceloop/traceloop-api/revisions/9c12a04a5947/schema)