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

# POST /v2/observability/query

`POST /v2/observability/query`

## Request

- Base URL: `https://api.vercel.com`
- URL: `https://api.vercel.com/v2/observability/query`
- Auth: none required

## 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.
- `404`
- `408`
- `410`
- `413`
- `422`
- `500`
- `503`

## Changes

- **2026-09-30** `099fbe1f521c`: 1 info
  - added the non-success response with the status `404`
- **2026-09-04** `f68cf4bd73b4`: 4 info
  - added the non-success response with the status `413`
  - added the non-success response with the status `422`
  - added the non-success response with the status `500`
  - added the non-success response with the status `503`
- **2026-07-21** `2ae10ee9d21c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/vercel/apis/vercel-api/changes/v2/observability/query/post.md)

---

[API](https://skmtc.dev/vercel/apis/vercel-api.md) - [All operations](https://skmtc.dev/vercel/apis/vercel-api/llms.txt) - [OpenAPI document](https://skmtc.dev/vercel/apis/vercel-api/revisions/60686c0e1f6a?raw)