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}

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.

Path parameters

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

Query parameters

Name	Type	Required	Default	Format / Possible Values	Description
period	string	Yes	—	start=<epoch>,end=<epoch>	Time range in Unix epoch seconds
metrics	string	Yes	—	metric1,metric2,...	Comma-separated metric field names
aggby	string	No	—	<dimension>, timestamp	Group by dimension or time
sessiontype	string	No	ended	ended , started	Sessions to include in the response. started: Add sessions that started in the period ended: Add sessions that ended in the period
allstatus	integer	No	0	0 , 1	1 includes sessions with any viewstatus value including RUNNING and LOADED sessions
granularity	string	No	auto	auto, minute, 5minute, 10minute, hour, day	Time bucket size. Set this parameter only with aggby=timestamp
filter	string	No	—	[dimension=value]	Dimension-level filters
qoefilter	string	No	—	metric1>value1 AND metric2>value2	Session-level metric filters
orderby	string	No	—	metric or dimension	Sort reocrds by the value of the metric or dimension
order	string	No	desc	asc or desc	Sort direction
limit	integer	No	1000	integer	Max records per page/query
offset	integer	No	0	integer	Pagination offset
concurrency	integer	No	0	0 , 1	1 indicates the metric value calculated is based on the metric related event occurrence in the requested time range. 0 indicates the metric value calculated is cumulative of all the occurrences of that metric related events.
businesserror	boolean	No	false	true , false	Include business exception errors in error metrics

Authenticate each request by adding X-API-Key HTTP request header to each request.

Use the Metric and Dimensions Dictionary for supported video and ad related metrics, dimensions, and aggregate variants available such as p95_latency.

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.

Example requests

Time-series graph - Rebuffering % over time

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>'

Dimension breakdown — Startup time by country (P95)

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>'

Filtered query — Buffering by CDN on Android

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>'

Example response

{
  "totalcount": 25,
  "pagecount": 4,
  "totalrecords": 100,
  "response": [
    {
      "country": "US",
      "latency": 1.82,
      "concurviewavg": 412
    },
    {
      "country": "GB",
      "latency": 2.14,
      "concurviewavg": 187
    }
  ]
}