Get Session Statistics

The Session Statistics API provides insights into individual Uplynk sessions to be able to detect or debug issues. This allows for analysis of playback issues that a single person or device may be having.

Data for this API is saved by the system for a 48 hour sliding window. Requesting data beyond 48 hours in the past is not allowed.

Data is requested in a maximum of five minute blocks to prevent queries from taking too long given the amount of data that needs to be searched and reconciled. Multiple API calls can be used if the incident time is not known to that granularity.

Base URL

Use the following base URL to perform an HTTP GET:

https://services.uplynk.com/api/v4/monitoring/delivery/session

Request Parameters

The following table details the required and optional parameters for making a request to the Session Statistics API:

Parameter	Data Type	Description	Required
euid	String	External Workspace ID for playback session	There must be one of `euid`, `user_ip`, or `playback_session_id` specified.
user_ip	String	IP Address for playback session	There must be one of `euid`, `user_ip`, or `playback_session_id` specified.
playback_session_id	String	Playback Session ID for playback session	There must be one of `euid`, `user_ip`, or `playback_session_id` specified.
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-02-12T15:53:00`	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-02-12T15:57:10`	Either `start` or `end` is required. If only `end` is passed, the system will fill the `start` based on a 5-minute block.
force	Boolean	If data for a portion of the date range specified is not yet processed, `force=false` will return what is available. Otherwise, a `202` response will be returned with the current maximum timestamp available.	Optional; default is`false`.

Sample Request

The code below (Python 3) shows how to retrieve session statistics.

This code imports names from the api_auth module for V4 APIs (see below).

import json
import requests
from api_auth import APICredentials, APIParams
  
class GetDeliverySession:
    def __init__(self):
        self.host = "https://services.uplynk.com"

    def run(self):
        """
        Get the delivery session statistics.
        """
        self._get_delivery_session()
  
    def _get_delivery_session(self):
        params = {
            'user_ip':   '127.168.208.58',
            'period': 60,
            'start': '2025-11-06T14:00:00',
            'end':   '2025-11-06T14:05:00',
            'force': False, 
        }
        
        url = f"{self.host}/api/v4/monitoring/delivery/session"
  
        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__":  
    GetDeliverySession().run()

Response Schema

The response returns statistics on an invidual playback session.

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 session statistics objects.
total_items	Integer	The total number of DRM statistics objects returned.

Session Statistics Item Schema

Field	Data Type	Description
period_timestamp	String	Timestamp of when error occurred (UTC)
error_source	String	Source of error ("drm" or "manifest")
errors	String	Error description

Sample Response using IP Address

{
  "@id": "/api/v4/monitoring/delivery/session?user_ip=127.168.208.58&period=60&start=2025-11-06T14:00:00&end=2025-11-06T14:05:00&force=False",
  "@type": "TimeSeries",
  "start": "2025-11-06T14:00:00.000Z",
  "end": "2025-11-06T14:05:00.000Z",
  "items": [
    {
      "period_timestamp": "2025-11-06T14:02:00+00:00",
      "error_source": "drm",
      "errors": "Beam not in window"
    },
    {
      "period_timestamp": "2025-11-06T14:04:00+00:00",
      "error_source": "drm",
      "errors": "Beam not in window"
    }
  ],
  "total_items": 2
}

Sample Response using EUID

{
  "@id": "/api/v4/monitoring/delivery/session?euid=05531eeae69cd37cd12462c89293f499916b3ca217b5d82b27332b3beebbbbbb&period=60&start=2025-11-13T23:35:00&end=2025-11-13T23:40:00&force=False",
  "@type": "TimeSeries",
  "start": "2025-11-13T23:35:00.000Z",
  "end": "2025-11-13T23:40:00.000Z",
  "items": [
    {
      "period_timestamp": "2025-11-13T23:35:00+00:00",
      "error_source": "drm",
      "errors": "Couldn't find beam based on Widevine request"
    }
  ],
  "total_items": 1
}