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

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

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

---