The CMCD Stats API provides insights into Common Media Client Data (CMCD) that specifies how media players can convey Quality of Experience (QoE) client-side metrics with each request. This can be done either as a custom HTTP request header, as an HTTP query argument, or as a JSON object. These metrics are sent to the Content Delivery Network (CDN) serving a particular player and Uplynk retrieves this data from the CDN(s) being used.
The CMCD specification was published by the Consumer Technology Association under specification CTA-5004. The complete CMCD specification is found here.
At the current time, Uplynk stores CMCD statistics for a minimum of 24 hours.
Base URL
Use the following base URL:
https://services.uplynk.com/api/v4/monitoring/cmcd
Request Parameters
The following table details the required and optional parameters for making a request to the CMCD Stats API:
| Parameter | Data Type | Description | Required |
|---|---|---|---|
period | Integer | Aggregates the data over a defined time interval in seconds, simplifying analysis by grouping data points within consistent time windows. Accepted Values: 10, 20, 30, 40, 50, 60, 120 | Optional; default is None |
start | String | Indicates the date and time (UTC) at which the statistics start period should begin. Syntax: YYYY-MM-DDThh:mm:ssExample: 2025-09-04T20:31:11 | Either start or end is required. If only start is passed, the system will fill the end based on a 5-minute block. |
end | String | Indicates the date and time (UTC) at which the statistics start period should end. Syntax: YYYY-MM-DDThh:mm:ssExample: 2025-09-04T20:35:11 | Either start or end is required. If only end is passed, the system will fill a start based on a 5-minute block. |
page | Integer | Page number of results to return. | Optional; default is 1 |
page_size | Integer | Number of items returned per page. | Optional; default is 1000 |
force | Boolean | If data for a portion of the date range specified is not yet processed, force=true will return what is available. Otherwise, a 202 response will be returned with the current maximum timestamp available. | Optional; default is false |
Sample Request
import json
import requests
from api_auth import APICredentials, APIParams
class GetCMCDStats:
def __init__(self):
self.host = "https://services.uplynk.com"
def run(self):
"""
Get the latest CMCD statistics.
"""
self._get_cmcd_stats()
def _get_cmcd_stats(self):
params = {
'period': 120,
'start': '2025-09-04T18:49:00',
'end': '2025-09-04T18:53:00',
'force': False,
}
url = f"{self.host}/api/v4/monitoring/cmcd"
response = requests.get(
url, params={**params, **APIParams(APICredentials()).get_params({})}
)
if response.status_code == 200:
print(json.dumps(response.json(), indent=2)) # Pretty print JSON response
else:
print("Error:", response.status_code)
print(response.json())
if __name__ == "__main__":
GetCMCDStats().run()
Response Schema
The response returns CMCD data provided by playback clients to the CDN used for caching.
| Field | Data Type | Description |
|---|---|---|
| @id | String | The request URL with query parameters included. |
| @type | String | The type of response, which is always TimeSeries. |
| start | String | The start time of the requested statistics range in YYYY-MM-DDThh:mm:ss.SSSZ format. |
| end | String | The end time of the requested statistics range in YYYY-MM-DDThh:mm:ss.SSSZ format. |
| items | Array | List of CMCD statistics (schema below). |
| total_items | Integer | The total number of CMCD statistics returned. |
| max_pages | Integer | Total number of pages in the API response. |
| current_page | Integer | Current page number of the API response. |
CMCD Statistics Item Schema
| Field | Data Type | Description |
|---|---|---|
| logged_event_timestamp | String | This is the timestamp associated with the occurrence of the beacon as captured from the CDN log data. This is the timestamp that all of the information in the CMCD Statistics item should be measured against. |
| logged_exec_timestamp | String | This is an internal Uplynk timestamp for when processing is started/executed on the beacon log. |
| owner_id | String | The Uplynk Owner ID. |
| beam_id | String | The Uplynk Beam ID. |
| c_ip | String | The IP address of player. |
| country | String | The country where player is located. |
| state | String | The state where player is located. |
| town | String | The town/city where player is located. |
| asn | Integer | The Autonomous System Number of the network. |
| isp | String | This is the name of the Internet Service Provider used. |
| longitude | Float | The longitude where the player is located. |
| latitude | Float | The latitude where the player is located. |
| cs_uri_stem | String | This represents the URI (Uniform Resource Identifier) path of the resource requested by the client, excluding any query strings or parameters. |
| cmcd_encoded_bitrate | Integer | The encoded bitrate of the streamed content (kbps). |
| cmcd_buffer_length | Integer | The buffer length associated with the media object being requested (msec). |
| cmcd_buffer_starvation | Integer | A key is included without a value if the buffer was starved at some point between the prior request and this object request, resulting in the player being in a rebuffering state and the video or audio playback being stalled. |
| cmcd_content_id | String | A unique string identifying the current content. Maximum length is 64 characters. This value is consistent across multiple different sessions and devices and is defined and updated at the discretion of the service provider. |
| cmcd_object_duration | Integer | The playback duration of the object being requested (msec). |
| cmcd_deadline | Integer | The deadline from the request time until the first sample of this Segment/Object needs to be available in order to not create a buffer underrun or any other playback problems (msec). |
| cmcd_measured_throughput | Integer | The throughput between client and server, as measured by the client (kbps). |
| cmcd_next_object_request | String | This is the relative path of the next object to be requested. This can be used to trigger pre-fetching by the CDN. |
| cmcd_next_range_request | String | If the next request will be a partial object request, then this string denotes the byte range to be requested. If the "cmcd_next_object_request" field is not set, then the object is assumed to match the object currently being requested. Valid combinations are: - <range-start> - <range-start>-<range-end> - <suffix-length> |
| cmcd_object_type | String | The media type of the current object being requested: - m = text file, such as a manifest or playlist - a = audio only - v = video only - av = muxed audio and video - i = init segment - c = caption or subtitle - tt = ISOBMFF timed text track - k = cryptographic key, license or certificate. - o = other |
| cmcd_playback_rate | Integer | Indicator of the playback rater where 1 if real-time, 2 if double speed, 0 if not playing. |
| cmcd_requested_maximum_throughput | Integer | The requested maximum throughput that the client considers sufficient for delivery of the asset (kbps). |
| cmcd_streaming_format | String | The streaming format that defines the current request: - d = MPEG DASH - h = HTTP Live Streaming (HLS) - s = Smooth Streaming - o = other |
| cmcd_session_id | String | A GUID identifying the current playback session. A playback session typically ties together segments belonging to a single media asset. |
| cmcd_stream_type | String | One of two possible token values: - v = all segments are available – e.g., VOD - l = segments become available over time – e.g., LIVE |
| cmcd_startup | Integer | A key is included without a value if the object is needed urgently due to startup, seeking or recovery after a buffer-empty event. |
| cmcd_top_bitrate | Integer | The highest bitrate rendition in the manifest or playlist that the client is allowed to play, given current codec, licensing and sizing constraints (kbps). |
| cmcd_version | Integer | This is the version of the CMCD specification used (e.g., 1). |
| user_agent | String | The value contained in the User-Agent field in the HTTP header. |
| cs_uri_query | String | This represents the query string portion of a URL, which typically contains parameters passed to the server during an HTTP request. |
| ua_environment | String | This is the User-Agent environment used (e.g., CTV). |
| ua_ott_device_group | String | This is the User-Agent OTT device group for the deivce. |
| ua_ott_device | String | This is the User-Agent OTT device used. |
| ua_os | String | This is the User-Agent Operating System. |
| ua_os_version | String | This is the User-Agent OS version. |
| ua_device | String | This is the User-Agent device used. |
| ua_browser | String | This is the User-Agent browser. |
| ua_browser_version | String | This is the User-Agent browser version. |
The values returned for CMCD Statistics data is dependent on what the player itself sent to the CDN so some data may be missing or incomplete.
Sample Response
{
"@id": "/api/v4/monitoring/cmcd?start=2025-09-04T15:53:00&end=2025-09-04T15:57:10&page=1&page_size=1&period=120",
"@type": "TimeSeries",
"start": "2025-09-04T15:53:00.000Z",
"end": "2025-09-04T15:57:01.000Z",
"items": [
{
"logged_event_timestamp": "2025-09-04T15:54:24+00:00",
"logged_exec_timestamp": "2025-00-04T15:54:40+00:00",
"owner_id": "d09b16c953aa40c98dd8c513526xxxxx",
"beam_id": "0707395972e64d28b48e8a32ea8xxxxx",
"c_ip": "24.117.XXX.XXX",
"country": "United States",
"state": "Idaho",
"town": "Acme",
"asn": 12345,
"isp": "ACME, Inc.",
"longitude": -118.56346,
"latitude": 46.54072,
"cs_uri_stem": "/ause/slices/070/d09b16c953aa40c98dd8c513526aca5a/0707395972e64d28b48e8a32ea8e64fe/F00000008.ts?pbs=548367634366424bb08f156e135052dc&_jt=e&euid=SEC_VDMS&chid=-&event=6f92863fe44f45c08cf883cb6b86770e&cloud=aws&ptid=EVENTS_VDMS&cdn=cfi&si=2",
"cmcd_encoded_bitrate": 8099,
"cmcd_buffer_length": 125300,
"cmcd_buffer_starvation": 0,
"cmcd_content_id": "3778721911",
"cmcd_object_duration": 2048,
"cmcd_deadline": 0,
"cmcd_measured_throughput": 75900,
"cmcd_next_object_request": "F00000009.ts%253Fpbs%253D548367634366424bb08f156e135052dc%2526_jt%253De%2526euid%253DSEC_VDMS%2526chid%253D-%2526event%253D6f92863fe44f45c08cf883cb6b86770e%2526cloud%253Daws%2526ptid%253DEEVENTS_VDMS%2526cdn%253Dcfi%2526si%253D2",
"cmcd_next_range_request": "",
"cmcd_object_type": "av",
"cmcd_playback_rate": 0,
"cmcd_requested_maximum_throughput": 0,
"cmcd_streaming_format": "h",
"cmcd_session_id": "PL01-a3f4240f34236251",
"cmcd_stream_type": "l",
"cmcd_startup": 0,
"cmcd_top_bitrate": 8099,
"cmcd_version": 1,
"user_agent": "Roku/DVP-14.6%20(14.6.4.9915-CR)",
"cs_uri_query": "pbs=548367634366424bb08f156e135052dc&_jt=e&euid=SEC_VDMS&chid=-&event=6f92863fe44f45c08cf883cb6b86770e&cloud=aws&ptid=EVENTS_VDMS&cdn=cfi&si=2",
"ua_environment": "CTV",
"ua_ott_device_group": "OTT & Streaming Media Player",
"ua_ott_device": "Roku",
"ua_os": "Roku OS",
"ua_os_version": "14.6",
"ua_device": "Roku DVP",
"ua_browser": "Roku App",
"ua_browser_version": "14.6"
}
],
"total_items": 1,
"max_pages": 303,
"current_page": 1
}