> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/concepts/foundations/activation/apis/getting-started/querying-data-products/metrics.md).

# Metrics

The Metric API is the shortest path for querying `METRIC` models. It builds the full [REST](/concepts/foundations/activation/apis/getting-started/querying-data-products/rest.md) query for you and always includes `measure`, `ts`, and declared segments.

**Mount:** `/api/v1/query/metric/{metric_name}`

### Response lifecycle

`GET` or `POST /api/v1/query/metric/{metric_name}` returns `202 Accepted` and a statement `id`. Poll `GET /api/v1/query/statement/{id}` until `status` is `SUCCESS` or `FAILED`. Fetch rows from `GET /api/v1/query/statement/{id}/result?format=json` only after `SUCCESS`.

Status codes, deduplication, and export formats: see [Statement lifecycle](/concepts/foundations/activation/apis/getting-started/querying-data-products/statement-lifecycle.md).

### METRIC model layout

Every metric shares the same column structure:

| Column      | `kind`           | Purpose                          |
| ----------- | ---------------- | -------------------------------- |
| `measure`   | measure          | Headline KPI — always this name  |
| `ts`        | dimension (time) | Time axis — always this name     |
| others      | dimension        | Slice dimensions (names vary)    |
| `*_segment` | segment          | Optional pre-defined row filters |

`default_granularity` sets the time bucket when you omit granularity (for example `day`).

```json
{
  "name": "store_revenue",
  "kind": "METRIC",
  "default_granularity": "day",
  "columns": [
    { "name": "measure", "kind": "measure", "ltype": "number" },
    { "name": "ts", "kind": "dimension", "ltype": "time" },
    { "name": "product_category", "kind": "dimension", "ltype": "string" },
    { "name": "sales_channel", "kind": "dimension", "ltype": "string" },
    { "name": "orders_completed_orders", "kind": "segment", "ltype": "boolean" }
  ]
}
```

Slice dimensions use plain names in the Metric API (`product_category`) but qualified names in REST and SQL (`store_revenue.product_category`).

You cannot turn off auto-included `measure`, `ts`, or metric segments. For period-over-period comparison, cross-model mixing, or queries without time bucketing, use REST directly.

### GET — no filters

```bash
GET /api/v1/query/metric/store_revenue?dimensions=product_category,sales_channel&granularity=day&timezone=UTC&limit=1000
```

| Param         | Default                       | Description                                     |
| ------------- | ----------------------------- | ----------------------------------------------- |
| `dimensions`  | —                             | Comma-separated **alias** names (not qualified) |
| `granularity` | model's `default_granularity` | Time bucket                                     |
| `timezone`    | UTC                           | IANA timezone                                   |
| `limit`       | 10,000                        | Max 50,000                                      |
| `offset`      | 0                             | Rows to skip                                    |

### POST — with filters

```bash
POST /api/v1/query/metric/store_revenue
```

```json
{
  "dimensions": ["product_category", "sales_channel"],
  "granularity": "day",
  "timezone": "UTC",
  "filters": [
    {
      "member": "store_revenue.sales_channel",
      "operator": "equals",
      "values": ["web"]
    }
  ],
  "limit": 1000
}
```

Dimensions use alias names (`product_category`). Filter `member` fields always use qualified names (`store_revenue.sales_channel`). Filter syntax matches [REST](/concepts/foundations/activation/apis/getting-started/querying-data-products/rest.md).

### What GET expands to

`GET …/metric/store_revenue?dimensions=product_category&granularity=day` is equivalent to:

```json
{
  "measures": ["store_revenue.measure"],
  "dimensions": ["store_revenue.product_category", "store_revenue.ts.day"],
  "segments": ["<any segments declared on the metric>"],
  "timeDimensions": [
    {
      "dimension": "store_revenue.ts",
      "granularity": "day"
    }
  ]
}
```

### Metric API vs REST

| Need                                      | Metric API | REST                 |
| ----------------------------------------- | ---------- | -------------------- |
| Simple KPI query, minimal setup           | Best fit   | Works                |
| Plain dimension aliases                   | Yes        | Qualified names only |
| `compareDateRange`                        | No         | Yes                  |
| Mix metric with semantic members          | No         | Yes                  |
| Suppress auto-included `ts` / `measure`   | No         | Yes                  |
| Default granularity applied automatically | Yes        | No                   |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://v2.dataos.info/concepts/foundations/activation/apis/getting-started/querying-data-products/metrics.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.