> 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/references/interfaces/apis/data-product-apis/querying-data-products/metrics.md).

# Metrics

A focused interface for reading approved KPI time series.

Use the Metric API when the business question starts with one approved KPI: total revenue, units sold, average order value, or another named metric. A metric fixes the governed measure and time axis; the caller chooses the time grain, optional dimensions, filters, and result window.

This is the smallest and safest query contract for KPI tiles, alerts, scorecards, and repeated reporting.

**Endpoint:** `GET` or `POST /api/v1/query/metric/{metric_name}`

## Discover metrics

Call `GET /api/v1/metadata/semantic` and find entries with `kind: METRIC`. Use the exact metric name in the URL and its declared dimension aliases in `dimensions`.

Every metric exposes:

| Member           | Purpose                                                                         |
| ---------------- | ------------------------------------------------------------------------------- |
| `measure`        | The metric's governed KPI. Always included.                                     |
| `ts`             | The metric's time axis. Always included and bucketed.                           |
| Other dimensions | Optional slices, such as `product_category` or `store_region`.                  |
| Segments         | Optional predefined filters. Automatically applied when declared by the metric. |

The metric's `default_granularity` is used when the caller does not provide one.

## Simple query with GET

Use GET when you only need a grain, dimension slices, timezone, and pagination.

```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_delivered", "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`  | (none)                        | 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": "Asia/Kolkata",
  "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](https://v2.dataos.info/references/interfaces/apis/data-product-apis/querying-data-products/rest.md).

### What GET expands to

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

```json
{
  "query": {
    "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"
      }
    ]
  }
}
```

## Guardrails

* The metric name must exist; otherwise the API returns `404`.
* Dimension aliases belong to that metric; arbitrary semantic dimensions are rejected.
* An unknown dimension or invalid order member returns `400` and lists available values.
* Consumers cannot replace or suppress the metric's measure, time axis, or declared segments.
* Both GET and POST return `202 Accepted` and use the shared [query lifecycle](https://v2.dataos.info/references/interfaces/apis/data-product-apis/querying-data-products/advanced/query-lifecycle.md).

If a consumer needs multiple independent measures in one result, use [REST](https://v2.dataos.info/references/interfaces/apis/data-product-apis/querying-data-products/rest.md), [Semantic SQL](https://v2.dataos.info/references/interfaces/apis/data-product-apis/querying-data-products/semantic-sql.md), or [GraphQL](https://v2.dataos.info/references/interfaces/apis/data-product-apis/querying-data-products/graphql.md).

## Next steps

* Use [REST](https://v2.dataos.info/references/interfaces/apis/data-product-apis/querying-data-products/rest.md) when a KPI request needs broader query control.
* Create a [Perspectives](https://v2.dataos.info/references/interfaces/apis/data-product-apis/querying-data-products/perspectives.md) to share a successful result through a stable URL.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://v2.dataos.info/references/interfaces/apis/data-product-apis/querying-data-products/metrics.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
