---
title: "POST /v2/observability/query"
method: POST
path: "/v2/observability/query"
---

# POST /v2/observability/query

`POST /v2/observability/query`

## Request body

- object
  - `metric` string, required — Metric id
  - `scope` object, required — Owner or project scope for the query
  - `aggregation` string — Aggregation function to apply. Some aggregations require a dimension: use <agg>/<dimension>, for example unique/visitor_id.
  - `groupBy` string[] — Dimensions to group results by. JSON dimensions support nested refs, for example event_data/checkout_step. Nested keys containing characters that OData cannot parse as an identifier, such as '-', spaces, quotes, or '/', must be wrapped in single quotes (escape embedded single quotes by doubling them), for example flags/'enable-comments-view' or event_data/'some property''s/value'.
  - `filter` string — Filter to apply to the query. JSON dimensions support nested refs, for example event_data/checkout_step eq 'payment'. Nested keys containing characters that OData cannot parse as an identifier, such as '-', spaces, quotes, or '/', must be wrapped in single quotes (escape embedded single quotes by doubling them), for example flags/'enable-comments-view' eq true or event_data/'some property''s/value' eq true.
  - `limit` number — Maximum number of results
  - `orderBy` string — Rollup column to order grouped results by. Use the generated rollup key for the requested metric and aggregation. Defaults to the query engine count rollup.
  - `orderDirection` 'asc' | 'desc' — Direction to order grouped results by. Defaults to desc.
  - `granularity` object — Time bucket size
  - `startTime` string — Start timestamp
  - `endTime` string — End timestamp
  - `bucketTimezone` string — IANA timezone (e.g. Europe/Paris) used only to align calendar buckets (1d/1mo) to that zone's day/month boundaries. startTime/endTime and all output timestamps are always UTC. No effect on sub-day granularities.

## Response `200`

- object

## Other responses

- `400` — One of the provided values in the request body is invalid.
- `401` — The request is not authorized.
- `402`
- `403` — You do not have permission to access this resource.
- `408`
- `410`

---

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