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

***


---

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