Retrieves the latest enhanced statistics for a live channel or live event provided that it has viewership. Identify a live channel or live event by its system-defined ID.
Where can I find a live channel ID?
- From the CMS, click the Live Channels tab.
- Select the desired live channel. Basic options and live channel information will be displayed on the Details tab.
- Find the live channel's system-defined ID under the GUID label.
Where can I find a live event ID?
- Navigate to the Live Events page. How? From the main menu, navigate to Events | Live Events.
- Select the desired live event.
- Verify that the Details tab is selected.
- Find the live event's system-defined ID under the GUID label.
Request
Request syntax:
GET /monitoring/stream_stats_enhanced/Live Channel or Live Event ID
Response
The response for a successful request contains the following properties:
| Name | Data Type | Description |
|---|---|---|
| @id | String | Indicates the relative path to this resource. |
| @type | String | Returns StreamStats. |
| id | String | Identifies the live channel or live event by its system-defined ID. |
| stats | Dictionary | Provides 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. |
| ts | Integer | Indicates the Unix time, in milliseconds, at which the statistics were gathered. |
| ts_iso | String | Indicates 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:
| Name | Data Type | Description | |
|---|---|---|---|
| auth_failures | Integer | Indicates the number of authentication failures that occurred. | |
| concurrent | Dictionary | Contains statistics for concurrent playback sessionsIdentifies a playback session with a duration of at least 1 minute. . | |
| domains | List of dictionaries | Contains the domains through which viewers requested your live stream. | |
| locations | List of dictionaries | Contains the locations from which viewers requested your live stream. | |
| new | Dictionary | Contains statistics for new playback sessionsIdentifies a playback session whose duration is less than 1 minute.. | |
| platforms | List of dictionaries | Contains the platforms (e.g., android or ios) from which viewers requested your live stream. | |
| type | String | Identifies the type of live stream. Valid values are: channel | event |
concurrent Dictionary
The concurrent dictionary provides statistics for playback sessions with a duration of at least 1 minute through the following properties:
Name | Data Type | Description |
|---|---|---|
ad_slate | Dictionary | Contains ad slate statistics for concurrent playback sessions over a given minute. This field is a dictionary keyed by the numeric reason code that triggered ad slate delivery. Each reason entry contains the following properties:
Ad slate delivery is expected when the total duration of returned ads is shorter than the configured ad break duration. In these cases, slate time typically does not exceed a few seconds. This metric does not include sessions that experience slate because no ad was requested (e.g., missing or invalid ad configuration in the URL query string). Ad Slate Reason Codes
|
mcs | Dictionary | Contains missing content slate statistics for concurrent playback sessions over a given minute. This field is a dictionary keyed by the numeric reason code that triggered missing content slate delivery.
Missing Content Slate Reason Codes
|
sessions | Integer | Indicates the number of concurrent playback sessions over a given minute. |
total_time | Float | Indicates 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:
| Name | Data Type | Description |
|---|---|---|
| ad_slate | Integer | Indicates 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. |
| domain | String | Indicates 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 |
| mcs | Integer | Indicates 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. |
| sessions | Integer | Indicates 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:
| Name | Data Type | Description |
|---|---|---|
| ad_slate | Integer | Indicates 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. |
| location | String | Identifies 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 |
| mcs | Integer | Indicates 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. |
| sessions | Integer | Indicates 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:
Name | Data Type | Description |
|---|---|---|
ad_slate | Dictionary | Contains ad slate statistics for new playback sessions. This field is a dictionary keyed by the numeric reason code that triggered ad slate delivery.
Ad slate delivery is expected when the total duration of returned ads is shorter than the configured ad break duration. In these cases, slate time typically does not exceed a few seconds. This metric does not include sessions that experience slate because no ad was requested (e.g., missing or invalid ad configuration in the URL query string). Ad Slate Reason Codes
|
mcs | Dictionary | Contains missing content slate statistics for new playback sessions. This field is a dictionary keyed by the numeric reason code that triggered missing content slate delivery.
Missing Content Slate Reason Codes
|
sessions | Integer | Indicates the number of new playback sessions over a given minute. |
total_time | Float | Indicates 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:
| Name | Data Type | Description |
|---|---|---|
| ad_slate | Integer | Indicates 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. |
| platform | String | Indicates the platform (e.g., windows and mac) on which the live stream was requested. |
| mcs | Integer | Indicates 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. |
| sessions | Integer | Indicates 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 a live channel whose system-defined ID is "114n9q6a847ieldd8bb8dbf67afef96b".
This code imports names from the api_auth module for V4 APIs (see below).
🦉
API Auth for Classic Authentication (V4 APIs)
Open Recipe
import json
import requests
from api_auth import APICredentials, APIParams
class GetEnhancedStatsSingleLiveStream:
def __init__(self):
self.host = "https://services.uplynk.com"
def run(self):
"""
Get enhanced statistics for a single live stream.
"""
self._get_enhanced_stats_single_live_stream()
def _get_enhanced_stats_single_live_stream(self):
stream_id = '114n9q6a847ieldd8bb8dbf67afef96b' # Replace with a live event or live channel ID.
url = "{}{}{}".format(self.host, "/api/v4/monitoring/stream_stats_enhanced/", stream_id)
response = requests.get(
url, params=APIParams(APICredentials()).get_params({})
)
print(response.json())
GetEnhancedStatsSingleLiveStream().run()Response:
{
"@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"
}