Get Enhanced Statistics - Multiple Live Streams

Retrieves the latest statistics for all of the live channels or live events defined in the stream_ids request body property.

Request

Request syntax:

POST /monitoring/stream_stats_enhanced

Request body:

Define the desired live channels or live events by passing the following property within a JSON body:

PropertyData TypeDescription
stream_idsList of string valuesDefines the set of live channels or live events for which statistics will be returned.

Identify each live channel or live event by its system-defined ID.

Where can I find a live channel ID?
1. From the CMS, click the Live Channels tab.
2. Select the desired live channel. Basic options and live channel information will be displayed on the Details tab.
3. Find the live channel's system-defined ID under the GUID label.

Where can I find a live event ID?
1. Navigate to the Live Events page
2. Select the desired live event.
3. Verify that the Details tab is selected.
4. Find the live event's system-defined ID under the GUID label.

Response

The response for a successful request contains the following properties:

NameData TypeDescription
@idStringIndicates the relative path to this endpoint.
@typeStringReturns Collection.
itemsList of dictionariesProvides the latest statistics for each live channel or live event that satisfies the following conditions: _ It was defined in the stream_ids request body property. _ Data was reported for that live channel or live event within the last 24 hours. Statistics are reported for each live channel or live event that has viewership.
total_itemsIntegerIndicates the number of live channels or live events for which statistics were reported.

items List

The items list provides statistics for one or more live channels/live events through the following properties:

NameData TypeDescription
@idStringIndicates the relative path to this resource.
@typeStringReturns StreamStats.
idStringIdentifies the live channel or live event by its system-defined ID.
statsDictionaryProvides statistics for the live channel or live event identified by the id property. Statistics are measured over the minute prior to the time identified by the ts_iso property.
tsIntegerIndicates the Unix time, in milliseconds, at which the statistics were gathered.
ts_isoStringIndicates the date and time (UTC) at which the statistics were gathered. Syntax: YYYY-MM-DDThh:mm:ss.ssssssZ Example: 2023-01-08T20:31:11.510000Z
stats Dictionary

The stats dictionary provides statistics for one or more live channels/live events through the following properties:

NameData TypeDescription
auth_failuresIntegerIndicates the number of authentication failures that occurred.
concurrentDictionaryContains statistics for concurrent playback sessionsIdentifies a playback session with a duration of at least 1 minute. .
domainsList of dictionariesContains the domains through which viewers requested your live stream.
locationsList of dictionariesContains the locations from which viewers requested your live stream.
newDictionaryContains statistics for new playback sessionsIdentifies a playback session whose duration is less than 1 minute..
platformsList of dictionariesContains the platforms (e.g., android or ios) from which viewers requested your live stream.
typeStringIdentifies the type of live stream. Valid values are: channelevent

concurrent Dictionary

The concurrent dictionary provides statistics for playback sessions with a duration of at least 1 minute through the following properties:

NameData TypeDescription
ad_slateDictionaryContains ad slate statistics for concurrent playback sessions over a given minute. This dictionary contains a dictionary for each reason that ad slate was served. Reasons for ad slate are identified by their numeric code. Each of these dictionaries contains the following properties: time: Indicates the number of seconds that ad slate was served over a given minute. sessions: Indicates the number of playback sessions over a given minute that served ad slate.
mcsDictionaryContains missing content slate statistics for concurrent playback sessions over a given minute. This dictionary contains a dictionary for each reason that missing content slate was served. Reasons for missing content slate are identified by their numeric code.
sessionsIntegerIndicates the number of concurrent playback sessions over a given minute.
total_timeFloatIndicates the number of seconds of video served for concurrent playback sessions.

Statistics are measured over the minute prior to the time identified by the ts_iso property.

domains Dictionary

The domains dictionary provides statistics for each domain through which your live stream was requested for playback sessions with a duration of at least 1 minute:

NameData TypeDescription
ad_slateIntegerIndicates the number of playback sessions over a given minute that meet the following conditions: _ It requested the live stream from the domain identified in the domain property. _ It served ad slate. Ad slate delivery is the expected behavior when ad duration is shorter than the total ad break duration. Typically, ad slate delivery will not exceed a few seconds when this occurs. This metric does not include sessions experiencing slate when an ad has not been requested. For example, it is not triggered if an ad configuration is not defined in the URL query string or if an invalid ad configuration is defined.
domainStringIndicates the domain through which the live stream was requested. Example: This property reports content.uplynk.com for the following playback URL: https://content.uplynk.com/channel/cd772adbd60a4e898d1c3b1f46c58cea.m3u8
mcsIntegerIndicates the number of playback sessions over a given minute that meet the following conditions: _ It requested the live stream from the domain identified in the domain property. _ It served missing content slate.
sessionsIntegerIndicates the number of playback sessions that requested the live stream from the domain identified in the domain property over a given minute.

locations Dictionary

The locations dictionary provides statistics for each location from which your live stream was requested for playback sessions with a duration of at least 1 minute:

NameData TypeDescription
ad_slateIntegerIndicates the number of playback sessions over a given minute that meet the following conditions: _ It requested the live stream from the location identified in the location property. _ It served ad slate. Ad slate delivery is the expected behavior when ad duration is shorter than the total ad break duration. Typically, ad slate delivery will not exceed a few seconds when this occurs. This metric does not include sessions experiencing slate when an ad has not been requested. For example, it is not triggered if an ad configuration is not defined in the URL query string or if an invalid ad configuration is defined.
locationStringIdentifies the location from which the viewer requested your live stream. Syntax: Country CodeRepresents a two-character ISO 3166 country code.:RegionRepresents an abbreviation for the region from which the live stream was requested. View a list of country codes. If our service cannot determine a viewer's region, then we return a ?? value for the region (e.g., il:??). Example: The following location identifies a viewer that requested your live stream from California, USA. us:ca
mcsIntegerIndicates the number of playback sessions over a given minute that meet the following conditions: _ It requested the live stream from the location identified in the location property. _ It served missing content slate.
sessionsIntegerIndicates the number of playback sessions that requested the live stream from the location identified in the location property over a given minute.

new Dictionary

The new dictionary provides statistics for playback sessions whose duration is less than 1 minute through the following properties:

NameData TypeDescription
ad_slateDictionaryContains ad slate statistics for new playback sessions. This dictionary contains a dictionary for each reason that ad slate was served. Reasons for ad slate are identified by their numeric code. Each of these dictionaries contains the following properties: time: Indicates the number of seconds that ad slate was served over a given minute. sessions: Indicates the number of playback sessions over a given minute that served ad slate.
mcsDictionaryContains missing content slate statistics for new playback sessions. This dictionary contains a dictionary for each reason that missing content slate was served. Reasons for missing content slate are identified by their numeric code.
sessionsIntegerIndicates the number of new playback sessions over a given minute.
total_timeFloatIndicates the number of seconds of video served for new playback sessions.

platforms Dictionary

The platforms dictionary provides statistics for each platform from which your live stream was requested for playback sessions with a duration of at least 1 minute:

NameData TypeDescription
ad_slateIntegerIndicates the number of playback sessions over a given minute that meet the following conditions: _ It requested the live stream from the platform identified in the platform property. _ It served ad slate. Ad slate delivery is the expected behavior when ad duration is shorter than the total ad break duration. Typically, ad slate delivery will not exceed a few seconds when this occurs. This metric does not include sessions experiencing slate when an ad has not been requested. For example, it is not triggered if an ad configuration is not defined in the URL query string or if an invalid ad configuration is defined.
platformStringIndicates the platform (e.g., windows and mac) on which the live stream was requested.
mcsIntegerIndicates the number of playback sessions over a given minute that meet the following conditions: _ It requested the live stream from the platform identified in the platform property. _ It served missing content slate.
sessionsIntegerIndicates the number of playback sessions that requested the live stream on the platform identified in the platform property over a given minute.

Statistics are measured over the minute prior to the time identified by the ts_iso property.

Sample Request/Response

The code below (Python 3) shows how to retrieve the latest statistics for three live channels.

Note: This example requires proper API authentication. Make sure you have the necessary credentials and authentication setup before running this code.

import json
import requests
from api_auth import APICredentials, APIParams

class GetEnhancedStatsMultipleLiveStreams:
    def __init__(self):
        self.host = "https://services.uplynk.com"

    def run(self):
        """
        Get the enhanced statistics for multiple live streams.
        """
        self._get_enhanced_stats_multiple_live_streams()

    def _get_enhanced_stats_multiple_live_streams(self):
        url = "{}{}".format(self.host, "/api/v4/monitoring/stream_stats_enhanced")

        stream_ids = ['114n9q6a847ieldd8bb8dbf67afef96b', 'k30y636fa2f143eb95c7a41d96d581c4', 'n2fj4f8knf83nf81347fh12347fhjwse']
        # Replace with the IDs for the desired live channel(s) and live event(s).

        headers = {'Content-Type': 'application/json'}

        response = requests.post(
            url, params=APIParams(APICredentials()).get_params({}), json={"stream_ids": json.dumps(stream_ids)}, headers=headers
        )

        print(response.json())

GetEnhancedStatsMultipleLiveStreams().run()

Response:

{
	'@id': '/api/v4/monitoring/stream_stats_enhanced',
	'@type': 'Collection',
	'items': [{
			"@id": "/api/v4/monitoring/stream_stats_enhanced/114n9q6a847ieldd8bb8dbf67afef96b",
			"@type": "StreamStats",
			"id": "114n9q6a847ieldd8bb8dbf67afef96b",
			"stats": {
				"concurrent": {
					"sessions": 8193,
					"total_time": 494023.5793121638,
					"mcs": {
						"1": {
							"time": 60.416000000000004,
							"sessions": 1
						}
					}
				},
				"locations": [{
						'location': 'us:ca',
						'sessions': 4215,
						'mcs': 0,
						'ad_slate': 0
					}, {
						"location": "us:ny",
						"sessions": 3978,
						"mcs": 1,
						"ad_slate": 0
					}
				],
				"platforms": [{
						"platform": "mac",
						"sessions": 701,
						"mcs": 1,
						"ad_slate": 0
					}, {
						'platform': 'windows',
						'sessions': 7492,
						'mcs': 0,
						'ad_slate': 0
					}
				],
				"domains": [{
						"domain": "content.uplynk.com",
						"sessions": 8193,
						"mcs": 1,
						"ad_slate": 0
					}
				],
				"type": "channel"
			},
			"ts": 1649318700773,
			"ts_iso": "2022-04-07T08:05:00.773Z"
		}, {
			'@id': '/api/v4/monitoring/stream_stats_enhanced/k30y636fa2f143eb95c7a41d96d581c4',
			'@type': 'StreamStats',
			'id': 'k30y636fa2f143eb95c7a41d96d581c4',
			'stats': {
				'concurrent': {
					'sessions': 4,
					'total_time': 258.048
				},
				'locations': [{
						'location': 'us:ca',
						'sessions': 4,
						'mcs': 0,
						'ad_slate': 0
					}
				],
				'platforms': [{
						'platform': 'windows',
						'sessions': 3,
						'mcs': 0,
						'ad_slate': 0
					}, {
						'platform': 'mac',
						'sessions': 1,
						'mcs': 0,
						'ad_slate': 0
					}
				],
				'domains': [{
						'domain': 'content.uplynk.com',
						'sessions': 4,
						'mcs': 0,
						'ad_slate': 0
					}
				],
				'type': 'channel'
			},
			'ts': 1649801640042,
			'ts_iso': '2022-04-12T22:14:00.042Z'
		}, {
			'@id': '/api/v4/monitoring/stream_stats_enhanced/n2fj4f8knf83nf81347fh12347fhjwse',
			'@type': 'StreamStats',
			'id': 'n2fj4f8knf83nf81347fh12347fhjwse',
			'stats': None,
			'ts': None,
			'ts_iso': None
		}
	],
	'total_items': 3
}