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:
Property | Data Type | Description |
---|---|---|
stream_ids | List of string values | Defines 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:
Name | Data Type | Description |
---|---|---|
@id | String | Indicates the relative path to this endpoint. |
@type | String | Returns Collection. |
items | List of dictionaries | Provides 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_items | Integer | Indicates 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:
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 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. |
mcs | Dictionary | Contains 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. |
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 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. |
mcs | Dictionary | Contains 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. |
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 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
}