---
title: "Query reporting metrics"
method: POST
path: "/v2/reporting"
tags: ["Reporting"]
---

# Query reporting metrics

`POST /v2/reporting`

Returns time-series, scalar, and top-list analytics for AI usage, cost, latency, evaluator results, and guardrail outcomes. This API remains supported while the neutral telemetry envelope is proven against every reporting request shape.

## Request body

- QueryReportRequest
  - `metric` 'genai.requests' | 'genai.tokens' | 'genai.cost' | 'genai.errors' | 'genai.error_rate' | 'genai.latency.p50' | 'genai.latency.p95' | 'genai.latency.p99' | 'genai.ttft.avg' | 'genai.ttft.p50' | 'genai.ttft.p95' | 'genai.evaluator.runs' | 'genai.evaluator.pass_rate' | 'genai.evaluator.score.avg' | 'genai.guardrail.runs' | 'genai.guardrail.block_rate' | 'genai.guardrail.triggered' | 'genai.usage', required — Catalogue metric to query.
  - `from` string, date-time, required — Inclusive lower bound for the report window (RFC 3339, UTC).
  - `to` string, date-time, required — Exclusive upper bound for the report window (RFC 3339, UTC).
  - `grain` 'auto' | 'minute' | 'hour' | 'day' — Requested bucket grain. Use `auto` or omit the field to let the server choose based on the requested range.
  - `group_by` string[] — Reporting dimensions to break down by. Valid dimensions depend on the selected metric.
  - `filters` Filter[] — Up to 20 allowlisted predicates combined with AND.
    - `field` 'project' | 'identity' | 'provider' | 'model' | 'product' | 'api_key' | 'status_code' | 'http_status_code' | 'credential_type' | 'billing_billable' | 'dimension' | 'dimension_type' | 'tag' | 'agent' | 'tool' | 'deployment' | 'evaluator' | 'dataset' | 'prompt' | 'policy' | 'conversation' | 'thread' | 'memory_store' | 'knowledge' | 'sheet' | 'guardrail_origin' | 'evaluator_name' | 'evaluator_type' | 'evaluator_version' | 'result_type' | 'evaluation_stage' | 'guardrail_stage' | 'evaluator_stage' | 'guardrail_action' | 'result_label' — Public reporting dimension to filter on. Valid fields depend on the selected metric.
    - `op` 'eq' | 'neq' | 'in' | 'not_in' — Predicate operator. `eq` and `neq` accept exactly one value; `in` and `not_in` accept 1-100 values.
    - `values` string[] — Values compared against the selected field. Values are interpreted as public API strings, not SQL fragments.
  - `limit` integer — Maximum bucket rows returned. Defaults to 1000 and is capped at 5000.
  - `time_zone` string — IANA time zone applied to bucket boundaries, for example `America/New_York`. Response timestamps remain UTC. Empty means UTC.
  - `include_totals` boolean — When true, include a `totals` block aggregated across the full report window.
  - `mode` 'timeseries' | 'scalar' — Value shaping. `timeseries` (default) buckets by time; `scalar` returns one aggregated row per group over the whole window, ordered by value (top list), or a single row when `group_by` is empty.
  - `sort` 'desc' | 'asc' — Value ordering for `scalar` rows. Defaults to `desc`. Ignored for `timeseries`.

## Response `200`

OK

- QueryReportResponse
  - `object` 'report' — Object discriminator for typed SDKs and JSON parsers; always `report`.
  - `request` QueryReportRequest
    - `metric` 'genai.requests' | 'genai.tokens' | 'genai.cost' | 'genai.errors' | 'genai.error_rate' | 'genai.latency.p50' | 'genai.latency.p95' | 'genai.latency.p99' | 'genai.ttft.avg' | 'genai.ttft.p50' | 'genai.ttft.p95' | 'genai.evaluator.runs' | 'genai.evaluator.pass_rate' | 'genai.evaluator.score.avg' | 'genai.guardrail.runs' | 'genai.guardrail.block_rate' | 'genai.guardrail.triggered' | 'genai.usage', required — Catalogue metric to query.
    - `from` string, date-time, required — Inclusive lower bound for the report window (RFC 3339, UTC).
    - `to` string, date-time, required — Exclusive upper bound for the report window (RFC 3339, UTC).
    - `grain` 'auto' | 'minute' | 'hour' | 'day' — Requested bucket grain. Use `auto` or omit the field to let the server choose based on the requested range.
    - `group_by` string[] — Reporting dimensions to break down by. Valid dimensions depend on the selected metric.
    - `filters` Filter[] — Up to 20 allowlisted predicates combined with AND.
      - `field` 'project' | 'identity' | 'provider' | 'model' | 'product' | 'api_key' | 'status_code' | 'http_status_code' | 'credential_type' | 'billing_billable' | 'dimension' | 'dimension_type' | 'tag' | 'agent' | 'tool' | 'deployment' | 'evaluator' | 'dataset' | 'prompt' | 'policy' | 'conversation' | 'thread' | 'memory_store' | 'knowledge' | 'sheet' | 'guardrail_origin' | 'evaluator_name' | 'evaluator_type' | 'evaluator_version' | 'result_type' | 'evaluation_stage' | 'guardrail_stage' | 'evaluator_stage' | 'guardrail_action' | 'result_label' — Public reporting dimension to filter on. Valid fields depend on the selected metric.
      - `op` 'eq' | 'neq' | 'in' | 'not_in' — Predicate operator. `eq` and `neq` accept exactly one value; `in` and `not_in` accept 1-100 values.
      - `values` string[] — Values compared against the selected field. Values are interpreted as public API strings, not SQL fragments.
    - `limit` integer — Maximum bucket rows returned. Defaults to 1000 and is capped at 5000.
    - `time_zone` string — IANA time zone applied to bucket boundaries, for example `America/New_York`. Response timestamps remain UTC. Empty means UTC.
    - `include_totals` boolean — When true, include a `totals` block aggregated across the full report window.
    - `mode` 'timeseries' | 'scalar' — Value shaping. `timeseries` (default) buckets by time; `scalar` returns one aggregated row per group over the whole window, ordered by value (top list), or a single row when `group_by` is empty.
    - `sort` 'desc' | 'asc' — Value ordering for `scalar` rows. Defaults to `desc`. Ignored for `timeseries`.
  - `data` DataPoint[] — Time-ordered buckets.
    - `timestamp` string, date-time — Bucket start in UTC, RFC 3339. Clients that need epoch ms can call `Date.parse(timestamp)` or `new Date(timestamp).getTime()` — returning the int64 in JSON would force a string (protojson rule) and force callers to coerce anyway, so we ship ISO only. Unset for `mode=scalar` rows, which aggregate the whole window.
    - `dimensions` object — Public breakdown labels for this bucket, keyed by group-by column. Empty when no group-by was requested. Empty values are omitted so the caller never has to special-case `""`.
    - `metrics` object — Metric values for this bucket. Single-metric requests carry one entry keyed by the requested metric name (e.g. `"genai.cost"` → `0.000495`). Bundle metrics carry one entry per field. Numbers are pre-rounded to 10 significant digits to avoid IEEE-754 display noise like `0.00009900000000000001`.
  - `totals` Totals
    - `metrics` object — Same shape and rules as `DataPoint.metrics`, aggregated across the whole window.
  - `has_more` boolean — Pagination contract. Always populated; currently false because the server caps the response at `limit` instead of issuing cursors.
  - `meta` ResponseMeta
    - `effective_grain` 'minute' | 'hour' | 'day' — Bucket grain actually applied by the planner.
    - `row_count` integer — Number of rows in `data`. Cheap hint for clients that paginate client-side; mirrors `len(data)`.
    - `request_id` string — Stable identifier for this query. Forward in support tickets so server logs can be correlated. Also returned in the `X-Request-Id` response header.
    - `currency` 'USD' — ISO 4217 currency code for cost fields. Always `USD` today.
    - `warnings` string[] — Non-fatal warnings about the response. May contain `totals_unavailable` when totals were requested but failed.

---

[API](https://skmtc.net/orq-ai/apis/orq-ai-api.md) · [All operations](https://skmtc.net/orq-ai/apis/orq-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/orq-ai/orq-ai-api/versions/41c02aedc7c0/schema)