> 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/ad-metric-query.md).

# Ad Metric Query

Use this endpoint for ad trend graphs, dimension breakdowns, comparison views, and KPI tiles.

### Endpoint

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

{% hint style="info" %}
This endpoint serves both video and ad analytics. Use ad-specific metrics for ad queries. There is no separate session-list endpoint for ad analytics.
{% endhint %}

### Path parameters

| Parameter    | Type    | Required | Description                                            |
| ------------ | ------- | -------- | ------------------------------------------------------ |
| `customerId` | integer | Yes      | Numeric tenant identifier from your SmartSight profile |

### Query parameters

<table><thead><tr><th>Parameter</th><th width="126.01171875">Type</th><th width="132.890625">Required</th><th width="124.61328125">Default</th><th>Format</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 ad 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>, or <code>sessionid</code></td><td>Group by dimension, time, or session for session-level ad rows</td></tr><tr><td><code>sessiontype</code></td><td>string</td><td>No</td><td><code>ended</code></td><td><code>ended</code> or <code>started</code></td><td>Session completion status</td></tr><tr><td><code>allstatus</code></td><td>integer</td><td>No</td><td><code>0</code></td><td><code>0</code> or <code>1</code></td><td><code>1</code> includes <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>Time bucket size. Requires <code>aggby=timestamp</code></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>metric>value AND ...</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 column</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</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>businesserror</code></td><td>boolean</td><td>No</td><td><code>false</code></td><td><code>true</code> or <code>false</code></td><td>Include business exception errors in error metrics where applicable</td></tr></tbody></table>

{% hint style="info" %}
`concurrency` is not supported for ad queries. For rate-based ad reports, include `adimpression` and `totaladimpression` as context metrics.
{% endhint %}

{% hint style="info" %}
Use the [Metric and Dimensions Dictionary](/mediamelon/smartsight-apis/metrics.md) for ad metrics, ad dimensions, shared dimensions, percentile variants, and context metrics such as `adimpression` and `totaladimpression`.
{% endhint %}

{% tabs %}
{% tab title="Ad-specific dimensions" %}

| Dimension               | API value       | Description                      |
| ----------------------- | --------------- | -------------------------------- |
| Ad ID                   | `adid`          | Unique ad creative identifier    |
| Ad server name          | `adserver`      | Ad server that delivered the ad  |
| Ad break placement      | `adposition`    | `Pre`, `Mid`, or `Post`          |
| Ad break position index | `adpodindex`    | Numeric index of the ad break    |
| Ad position in pod      | `adpodposition` | Position within the ad pod       |
| Pod length              | `adpodlength`   | Total ad pod duration in seconds |
| {% endtab %}            |                 |                                  |

{% tab title="Common shared dimensions" %}
Most commonly used dimensions:

| Category          | Dimension        | API value        | Description                                        |
| ----------------- | ---------------- | ---------------- | -------------------------------------------------- |
| Network and geo   | Country          | `country`        | Country derived from the viewer's IP address       |
| Device            | Device type      | `device`         | Device category, such as mobile, TV, or desktop    |
| Device            | Operating system | `platform`       | OS name, such as Android, iOS, or Windows          |
| Player and app    | App name         | `appname`        | Name of the client application                     |
| Content           | Asset name       | `assetname`      | Name of the content asset where the ad ran         |
| Content           | Content type     | `contenttype`    | Type of content, such as episode or live event     |
| Subscriber        | Subscriber type  | `subscribertype` | Subscription tier, such as premium or free         |
| Session attribute | Is live stream   | `islive`         | Whether the ad ran in a live stream or VOD session |
| {% endtab %}      |                  |                  |                                                    |
| {% endtabs %}     |                  |                  |                                                    |

### Example requests

#### Trend graph — Ad playtime over time

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

#### Dimension breakdown — Ad startup time by ad server (P95)

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

#### Completion funnel — Ad completion by placement

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

#### Click-through rate by country

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

### Example response

{% code lineNumbers="true" %}

```json
{
  "totalcount": 2,
  "pagecount": 1,
  "totalrecords": 2,
  "response": [
    {
      "adserver": "FreeWheel",
      "p95_adlatency": 1.24,
      "adimpression": 12034,
      "totaladimpression": 19002
    },
    {
      "adserver": "Google Ad Manager",
      "p95_adlatency": 1.67,
      "adimpression": 6968,
      "totaladimpression": 19002
    }
  ]
}
```

{% endcode %}

***