> 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 %}