Get CMCD Statistics

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 to perform an HTTP GET:

https://services.uplynk.com/api/v4/monitoring/delivery/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:ss` Example: `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:ss` Example: `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/delivery/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
}