---
title: "POST /v1/metrics/{metricId}/query"
method: POST
path: "/v1/metrics/{metricId}/query"
tags: ["metrics"]
---

# POST /v1/metrics/{metricId}/query

`POST /v1/metrics/{metricId}/query`

## Request

- Base URL: `https://help.steep.app` (the document declares no server; this is the origin it was published from)
- URL: `https://help.steep.app/v1/metrics/{metricId}/query`
- Auth: none declared

Query data for a metric, optionally for a specific slice. Returns metric values for the requested date range. Omit `timeGrain` for a single aggregate over the period; set it for time-series data. Supports breakdown dimensions and filters.

## Path parameters

- `metricId` string, required: `metric.id` — Unique resource ID (opaque).

## Request body

- object
  - `timeGrain` 'daily' | 'weekly' | 'monthly' | 'quarterly' | 'yearly': Time grain for aggregation. Omit for a single aggregate over the whole period. Most metrics accept any range, but for a metric with restricted grains (check its allowed time grains) both ends must align to whole-period boundaries of an allowed grain — and without an explicit timeGrain the range may have to be a single whole period, so to span several periods set timeGrain to an allowed grain and align to its boundaries. E.g. a monthly-only metric: one whole calendar month 2026-05-01 to 2026-05-31, or timeGrain=monthly over month-aligned dates to span months; never use today's date as a boundary (2026-06-01 to 2026-06-24 is rejected).
  - `fromDate` string, required: Start of the query period (ISO 8601). Inclusive — it is part of the range, so a colloquial period spans exactly its calendar days. With a timeGrain, align to the first day of a period (e.g. monthly: 2026-05-01).
  - `toDate` string, required: End of the query period (ISO 8601). Inclusive — the last day counts, so one month is 2026-05-01 to 2026-05-31, not 2026-06-01. With a timeGrain, align to the last day of a period (e.g. monthly: 2026-05-31).
  - `breakdownDimensionIds` string[]: Dimension `id`s to break down by.
  - `sliceId` string: Slice `id` to fetch query data for.
  - `filters` object[]: Dimension filters to apply.
    - `dimensionId` string, required: Dimension `id` to filter by.
    - `filterValues` string[], required: Filter values for this dimension.
  - `limit` integer: Maximum number of rows to return. When the row limit is reached, response `hasMore` is `true`. For a more complete result, increase `limit` or reduce the result set (eg. shorter time period, coarser `timeGrain`, stricter filters).

## Response `200`

Response for status 200

- object
  - `cacheTtlInSeconds` number, required
  - `refreshedAt` string, date-time, required
  - `sql` string, required
  - `limit` number, required: The effective row limit applied to this query.
  - `hasMore` boolean, required: Indicates there is more data beyond the row limit.
  - `data` object[], required
    - `time` string, date-time: The time of the data point. Undefined if timeGrain is not provided.
    - `metric` unknown, required

## Other responses

- `401`: Response for status 401
- `403`: Response for status 403
- `422`: Response for status 422
- `429`: Response for status 429
- `500`: Response for status 500

---

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