> For the complete documentation index, see [llms.txt](https://docs.mediamelon.com/mediamelon/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mediamelon.com/mediamelon/smartsight-apis/metric-query-api.md).

# Metric Query API

Use `metricquery` API endpoint to get video session & ad related metrics and breakdowns by dimension values.

### Endpoint

`GET /mm-apis/metricquery/{customerId}`

{% hint style="warning" %}
As of July 2025, `/mm-apis/qbrData/vod` and `/mm-apis/session` are deprecated. Use `/mm-apis/metricquery` instead. Backward compatibility remains available, but `/mm-apis/metricquery` provides access to newer features.
{% endhint %}

### Path parameters

<table><thead><tr><th width="166.953125">Parameter</th><th width="156.546875">Type</th><th width="155.13671875">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>customerId</code></td><td>integer</td><td>Yes</td><td>Numeric tenant identifier from your SmartSight profile</td></tr></tbody></table>

### Query parameters

<table data-first-column-sticky><thead><tr><th width="109.3671875">Name</th><th width="101.72265625">Type</th><th width="92.47265625">Required</th><th width="126.375">Default</th><th>Format / Possible Values</th><th>Description</th></tr></thead><tbody><tr><td><code>period</code></td><td>string</td><td>Yes</td><td>—</td><td><code>start=&#x3C;epoch>,end=&#x3C;epoch></code></td><td>Time range in Unix epoch seconds</td></tr><tr><td><code>metrics</code></td><td>string</td><td>Yes</td><td>—</td><td><code>metric1,metric2,...</code></td><td>Comma-separated metric field names</td></tr><tr><td><code>aggby</code></td><td>string</td><td>No</td><td>—</td><td><code>&#x3C;dimension></code>, <code>timestamp</code></td><td>Group by dimension or time</td></tr><tr><td><code>sessiontype</code></td><td>string</td><td>No</td><td><code>ended</code></td><td><code>ended</code> , <code>started</code></td><td><p>Sessions to include in the response. </p><ul><li><code>started</code>: Add sessions that started in the <code>period</code>  </li><li><code>ended</code>: Add sessions that ended in the <code>period</code> </li></ul></td></tr><tr><td><code>allstatus</code></td><td>integer</td><td>No</td><td><code>0</code></td><td><code>0</code> , <code>1</code></td><td><code>1</code> includes sessions with any <code>viewstatus</code> value including <code>RUNNING</code> and <code>LOADED</code> sessions</td></tr><tr><td><code>granularity</code></td><td>string</td><td>No</td><td><code>auto</code></td><td><code>auto</code>, <code>minute</code>, <code>5minute</code>, <code>10minute</code>, <code>hour</code>, <code>day</code></td><td><p>Time bucket size. <br></p><p>Set this parameter only with <code>aggby=timestamp</code></p></td></tr><tr><td><code>filter</code></td><td>string</td><td>No</td><td>—</td><td><code>[dimension=value]</code></td><td>Dimension-level filters</td></tr><tr><td><code>qoefilter</code></td><td>string</td><td>No</td><td>—</td><td><code>metric1>value1 AND metric2>value2</code></td><td>Session-level metric filters</td></tr><tr><td><code>orderby</code></td><td>string</td><td>No</td><td>—</td><td>metric or dimension</td><td>Sort reocrds by the value of the metric or dimension</td></tr><tr><td><code>order</code></td><td>string</td><td>No</td><td><code>desc</code></td><td><code>asc</code> or <code>desc</code></td><td>Sort direction</td></tr><tr><td><code>limit</code></td><td>integer</td><td>No</td><td><code>1000</code></td><td>integer</td><td>Max records per page/query</td></tr><tr><td><code>offset</code></td><td>integer</td><td>No</td><td><code>0</code></td><td>integer</td><td>Pagination offset</td></tr><tr><td><code>concurrency</code></td><td>integer</td><td>No</td><td><code>0</code></td><td><code>0</code> , <code>1</code></td><td><code>1</code> indicates the metric value calculated is based on the metric related event occurrence in the requested time range. <br><br><code>0</code> indicates the metric value calculated is cumulative of all the occurrences of that metric related events. </td></tr><tr><td><code>businesserror</code></td><td>boolean</td><td>No</td><td><code>false</code></td><td><code>true</code> , <code>false</code></td><td>Include business exception errors in error metrics</td></tr></tbody></table>

{% hint style="info" %}
Authenticate each request by adding `X-API-Key` HTTP request header to each request.
{% endhint %}

{% hint style="info" %}
Use the [Metric and Dimensions Dictionary](/mediamelon/smartsight-apis/metrics.md) for supported video and ad related metrics, dimensions, and aggregate variants available such as `p95_latency`.
{% endhint %}

### API Considerations

* Always request metric data for completed time buckets. For real-time monitoring, set the `period` start and end time interval to the most recently completed time bucket. For example, request `2026-05-25 10:00:00` to `2026-05-25 10:00:59` if the current time is `2026-05-25 10:01:35`.
* Set API response timeouts based on the requested time range. For example, use a `10s` timeout when the `period` covers `1 min` to `30 mins`. Use higher timeout values for longer ranges such as `1 day`, `7 days`, or `30 days`.
* Use pagination with `limit` and `offset`, especially for high-cardinality breakdown queries. For example, Rebuffering % breakdown by `cdn`, `asn`, and `region` can return `100k+` records. A good practice is to fetch `5k` to `10k` records per API call.<br>

### Example requests

#### Time-series graph - Rebuffering % over time

{% code overflow="wrap" %}

```bash
curl --request GET \
  --url 'https://smartsight3.mediamelon.com/mm-apis/metricquery/199493832?  
    period=start=1775749920,end=1775836379&
    metrics=timestamp,cirrbufferingratio,concurviewavg&
    aggby=timestamp&
    granularity=5minute&
    orderby=timestamp& 
    order=asc&
    allstatus=0' \
  --header 'X-API-Key: <your-api-key>'
```

{% endcode %}

#### Dimension breakdown — Startup time by country (P95)

{% code overflow="wrap" %}

```bash
curl --request GET \
  --url 'https://smartsight3.mediamelon.com/mm-apis/metricquery/199493832?  
    period=start=1775749920,end=1775836379&
    metrics=p95_latency,concurviewavg&
    aggby=country&
    orderby=p95_latency&
    order=desc&
    limit=25' \
  --header 'X-API-Key: <your-api-key>'
```

{% endcode %}

#### Filtered query — Buffering by CDN on Android

{% code overflow="wrap" %}

```bash
curl --request GET \
  --url 'https://smartsight3.mediamelon.com/mm-apis/metricquery/199493832?  
    period=start=1775749920,end=1775836379&
    metrics=cirrbufferingratio,attempts&
    aggby=cdn&
    filter=[platform=Android]&
    orderby=cirrbufferingratio&
    order=desc' \
  --header 'X-API-Key: <your-api-key>'
```

{% endcode %}

### Example response

{% code lineNumbers="true" %}

```json
{
  "totalcount": 25,
  "pagecount": 4,
  "totalrecords": 100,
  "response": [
    {
      "country": "US",
      "latency": 1.82,
      "concurviewavg": 412
    },
    {
      "country": "GB",
      "latency": 2.14,
      "concurviewavg": 187
    }
  ]
}
```

{% endcode %}


---

# 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:

```
GET https://docs.mediamelon.com/mediamelon/smartsight-apis/metric-query-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.