---
title: "Query telemetry"
method: POST
path: "/v3/telemetry/query"
tags: ["Telemetry"]
---

# Query telemetry

`POST /v3/telemetry/query`

Canonical neutral query envelope for traces, metrics, and logs. Select a source, compute list, and time range; optionally group, filter, bucket, sort, limit, and include totals. ReportingService.QueryReport and TraceQueryService.AggregateTraces remain supported compatibility contracts.

## Request body

- QueryTelemetryRequest
  - `source` 'TELEMETRY_SOURCE_UNSPECIFIED' | 'TELEMETRY_SOURCE_TRACES' | 'TELEMETRY_SOURCE_METRICS' | 'TELEMETRY_SOURCE_LOGS'
  - `from` string, date-time
  - `to` string, date-time
  - `compute` TraceCompute[]
    - `metric` string
    - `op` string
  - `grain` string — Empty string and "none" are equivalent: a single row per group instead of a time series.
  - `group_by` string[]
  - `filters` TraceFilter[]
    - `field` string
    - `op` string
    - `values` string[]
  - `filter_operator` string
  - `limit` integer — Scalar queries: maximum returned rows, default 100. Time-series queries: optional maximum number of distinct groups; exceeding it fails the query instead of truncating timelines. Time-series results are complete within safety budgets of 5000 rows, 5000 buckets, and 50000 metric values. Queries are limited to 90 days and 30 seconds of execution.
  - `time_zone` string
  - `include_totals` boolean
  - `mode` 'timeseries' | 'scalar' — Value shaping. `timeseries` buckets by grain; `scalar` returns one row per group. When omitted, grain selects the compatible shape.
  - `sort` 'desc' | 'asc' — Ordering for scalar/top-list rows. Defaults to `desc`.
  - `interval_seconds` integer — Explicit bucket width in seconds. Takes precedence over `grain` when both are set.
  - `selected_range_seconds` integer — The span originally selected, before live extended [from, to). `grain:"auto"` resolves bucket width from this span, independent of how far [from, to) has since grown.
  - `project_id` string — Pins the read to one project the caller can reach. Omit to keep the caller's token scope.

## Response `200`

OK

- QueryTelemetryResponse
  - `object` string
  - `data` TelemetryRow[]
    - `timestamp` string, date-time — Unset when the resolved grain is "none" — one row per group, not a time series.
    - `group` object
    - `metrics` object
  - `totals` TelemetryRow
    - `timestamp` string, date-time — Unset when the resolved grain is "none" — one row per group, not a time series.
    - `group` object
    - `metrics` object
  - `meta` QueryTelemetryMeta
    - `effective_grain` string
    - `warnings` string[]
    - `row_count` integer
    - `request_id` string
    - `currency` string
  - `request` QueryTelemetryRequest
    - `source` 'TELEMETRY_SOURCE_UNSPECIFIED' | 'TELEMETRY_SOURCE_TRACES' | 'TELEMETRY_SOURCE_METRICS' | 'TELEMETRY_SOURCE_LOGS'
    - `from` string, date-time
    - `to` string, date-time
    - `compute` TraceCompute[]
      - `metric` string
      - `op` string
    - `grain` string — Empty string and "none" are equivalent: a single row per group instead of a time series.
    - `group_by` string[]
    - `filters` TraceFilter[]
      - `field` string
      - `op` string
      - `values` string[]
    - `filter_operator` string
    - `limit` integer — Scalar queries: maximum returned rows, default 100. Time-series queries: optional maximum number of distinct groups; exceeding it fails the query instead of truncating timelines. Time-series results are complete within safety budgets of 5000 rows, 5000 buckets, and 50000 metric values. Queries are limited to 90 days and 30 seconds of execution.
    - `time_zone` string
    - `include_totals` boolean
    - `mode` 'timeseries' | 'scalar' — Value shaping. `timeseries` buckets by grain; `scalar` returns one row per group. When omitted, grain selects the compatible shape.
    - `sort` 'desc' | 'asc' — Ordering for scalar/top-list rows. Defaults to `desc`.
    - `interval_seconds` integer — Explicit bucket width in seconds. Takes precedence over `grain` when both are set.
    - `selected_range_seconds` integer — The span originally selected, before live extended [from, to). `grain:"auto"` resolves bucket width from this span, independent of how far [from, to) has since grown.
    - `project_id` string — Pins the read to one project the caller can reach. Omit to keep the caller's token scope.
  - `has_more` boolean

## Changes

> 350 revisions in range; 136 not diffed.

- **2026-09-28** `3c7d859558ee` — 1 info
  - endpoint added
- **2026-09-21** `8f82880fa08a` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/orq-ai/apis/orq-ai-api/changes/v3/telemetry/query/post.md)

---

[API](https://skmtc.dev/orq-ai/apis/orq-ai-api.md) · [All operations](https://skmtc.dev/orq-ai/apis/orq-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/orq-ai/apis/orq-ai-api/revisions/3c7d859558ee?raw)