Ad Metric Query

Query aggregated ad metrics with the SmartSight metric query endpoint.

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

Endpoint

GET /mm-apis/metricquery/{customerId}

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.

Path parameters

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

Query parameters

Parameter	Type	Required	Default	Format	Description
period	string	Yes	—	start=<epoch>,end=<epoch>	Time range in Unix epoch seconds
metrics	string	Yes	—	metric1,metric2,...	Comma-separated ad metric field names
aggby	string	No	—	<dimension>, timestamp, or sessionid	Group by dimension, time, or session for session-level ad rows
sessiontype	string	No	ended	ended or started	Session completion status
allstatus	integer	No	0	0 or 1	1 includes RUNNING and LOADED sessions
granularity	string	No	auto	auto, minute, 5minute, 10minute, hour, day	Time bucket size. Requires aggby=timestamp
filter	string	No	—	[dimension=value]	Dimension-level filters
qoefilter	string	No	—	metric>value AND ...	Session-level metric filters
orderby	string	No	—	metric or dimension	Sort column
order	string	No	desc	asc or desc	Sort direction
limit	integer	No	1000	integer	Max records per page
offset	integer	No	0	integer	Pagination offset
businesserror	boolean	No	false	true or false	Include business exception errors in error metrics where applicable

concurrency is not supported for ad queries. For rate-based ad reports, include adimpression and totaladimpression as context metrics.

Use the Metric and Dimensions Dictionary for ad metrics, ad dimensions, shared dimensions, percentile variants, and context metrics such as adimpression and totaladimpression.

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

Common shared dimensions

Example requests

Trend graph — Ad playtime over time

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)

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

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

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

{
  "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
    }
  ]
}

---