Video Session List API

Query paginated video session rows for drill-down and root-cause analysis.

Returns a paginated list of individual video sessions. Use it for drill-down analysis and root-cause investigation.

Endpoint

GET /mm-apis/listsessions/{customerId}

This endpoint is exclusive to Video Analysis. There is no session-list endpoint for ad analytics.

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

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

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,...	List of Metrics and Dimensions to include
aggby	string	Yes	sessionid	sessionid	Group response records by sessionid
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
filter	string	No	—		Dimension-level filters
qoefilter	string	No	—		Metric-level session filters
orderby	string	No	—		Sort by metric
order	string	No	desc	asc , desc
limit	integer	No	1000		Max records per page
offset	integer	No	0		Pagination offset

Use any metric or dimension from Metric and Dimensions Dictionary as the first field in metrics. Then add the session fields you want returned.

Example requests

Sessions with highest startup delay

curl --request GET \
  --url 'https://smartsight3.mediamelon.com/mm-apis/listsessions/199493832?period=start=1775749962,end=1775836362&metrics=latency,starttime,endtime,assetname,watchtime,sessionid,sourcetype&aggby=sessionid&orderby=latency&order=desc&limit=25' \
  --header 'X-API-Key: <your-api-key>'

Sessions with severe buffering on Android

curl --request GET \
  --url 'https://smartsight3.mediamelon.com/mm-apis/listsessions/199493832?period=start=1775749962,end=1775836362&metrics=cirrbufferingratio,starttime,endtime,assetname,watchtime,sessionid,sourcetype&aggby=sessionid&filter=[platform=Android]&qoefilter=cirrbufferingratio>10&orderby=cirrbufferingratio&order=desc&limit=25' \
  --header 'X-API-Key: <your-api-key>'

Sessions for a specific subscriber

curl --request GET \
  --url 'https://smartsight3.mediamelon.com/mm-apis/listsessions/199493832?period=start=1775749962,end=1775836362&metrics=qualityofexperience,starttime,endtime,assetname,watchtime,sessionid,sourcetype&aggby=sessionid&filter=[subscriberid=user-12345]&orderby=starttime&order=desc' \
  --header 'X-API-Key: <your-api-key>'

Standard session fields

Field	Description
starttime	Session start time in epoch seconds
endtime	Session end time in epoch seconds
assetname	Name of the video asset played
watchtime	Total session watch time in seconds
sessionid	MediaMelon unique session identifier
sourcetype	Streaming format, such as HLS, DASH, or MP4

Common session metrics

Metric	API value	Description
Startup time (sec)	latency	Time from play attempt to first frame rendered for this session
Rebuffering percentage (%)	cirrbufferingratio	Percentage of this session's watch time spent rebuffering
Buffering time percentage (%)	bufferingratio	Percentage of watch time in any buffering state
Playback score	qualityofexperience	QoE score from 0 to 100 for this individual session
Playtime (mins)	playdur	Total content viewing time for this session
CDN change rate	cdn_change_rate	Frequency of CDN switches during this session
Errors	errors	Number of errors that occur during this session
Fatal errors	fatalerrors	Number of fatal errors during this session

Common session dimensions

Dimension	API value	Description
Country	country	Country derived from the viewer's IP address
Device type	device	Device category, such as mobile, TV, or desktop
Operating system	platform	OS name, such as Android, iOS, or Windows
Player name	player	Video player library name
CDN	cdn	CDN that serves the session
Asset name	assetname	Name of the content asset
Source format	sourcetype	Streaming format, such as HLS or DASH
Is live stream	islive	true for live streams and false for VOD
View status	status	Final session status, such as ended or dropped
Subscriber ID	subscriberid	Specific subscriber to look up sessions for
Error code	errorcode	Sessions that produce a specific error code
DRM	drmprotection	DRM system used during the session