Retrieves either:

Up to 500 schedule entries associated with a live channel for a specific time period.

We restrict the number of schedule entries that may be retrieved through this endpoint to 500. If the number of schedule entries in the requested time period exceeds this limit, then we will return the results for a shorter time period. Your script should check whether the requested end time (i.e., &end=End Time) matches the timestamp returned by the end response property. If there is a mismatch, then your script should submit another request with the start time set to the timestamp returned by the end response property and the end time set to the original requested end time.

Identify gaps within your schedule by including the include_empty=1 query string parameter. This parameter adds a placeholder schedule entry for each gap in your schedule within the requested time period. This occurs regardless of the duration of the gap in the schedule. For example, if you request schedule entries for a 12 hour period and have only scheduled entries for the first 7 hours, then the response will include a 5 hour placeholder schedule entry. Let's assume that there is also a 30 minute gap within the first 7 hours. In that case, the response will include 2 schedule entries whose durations are 30 minutes and 5 hours, respectively.
Recently updated schedule entries.

Information describing a scheduled entry is retained for 30 days after its end time.

Request

Request syntax (time period):

GET /channels/Live Channel ID/schedules?start=Start Time&end=End Time&include_deleted=1&include_empty=1&slicer_assets=1

Request syntax (recently updated schedule entries):

GET /channels/Live Channel ID/schedules?after=Last Modified Time

Define the following URL segment when submitting one of the above requests:

VariableA variable represents a value that must be replaced. A variable consists of either a URL segment (e.g., "0001" in /0001/) or a query string value (e.g., "3" in mediaTypes=3).	Description
Live Channel ID Required	Identifies a live channel by its system-defined ID.

Define the following optional query string parameters when submitting one of the above requests:

Parameter	Description
start=Start Time	Time Period Only Identifies the start of the time period for which schedule entries will be retrieved. Specify a timestamp (ISO 8601 - milliseconds; UTC). Syntax: YYYY-MM-DDThh:mm:ss.sssZ Example: start=2023-01-08T20:31:11.510Z Default value: The default value varies according to whether the end parameter has been defined. _ If the end parameter has been defined, then the default value is: End Time - 15 minutes _ If the end parameter has been omitted, then the default value is the point-in-time at which the request is submitted.
end=End Time	Time Period Only Identifies the end of the time period for which schedule entries will be retrieved. Specify a timestamp (ISO 8601 - milliseconds; UTC). Syntax: YYYY-MM-DDThh:mm:ss.sssZ Example: end=2023-01-08T20:31:11.510Z Default value: The default value varies according to whether the start parameter has been defined. _ If the start parameter has been defined, then the default value is: Start Time + 15 minutes _ If the start parameter has been omitted, then the default value is the point-in-time at which the request is submitted.
include_deleted=1	Time Period Only Pass include_deleted=1 to include deleted schedule entries in the response. The deleted response property is included for deleted schedule entries. Omit it to exclude this information.
include_empty=1	Time Period Only Pass include_empty=1 to include a placeholder schedule entry for each gap within your schedule for the requested time period. A placeholder schedule entry is limited to the following response properties: @id	@type	id	desc	dur	end	start	type The type property for placeholder schedule entries is set to Empty.
slicer_assets=1	Time Period Only Pass slicer_assets=1 to include information that describes assets played within a live channel as a result of a Live Slicer. Omit it to exclude this information.
after=Last Modified Time	Recently Updated Only Identifies a point-in-time for retrieving recently updated schedule entries. The response will only include schedule entries that were updated after this point-in-time. Specify a timestamp (ISO 8601 - milliseconds; UTC). The specified point-in-time may not exceed 10 minutes into the past. If you specify a point-in-time that is older than 10 minutes, then we will only return schedule entries that have been updated within the last 10 minutes. The after query string parameter takes precedence over the start and end parameters. Syntax: YYYY-MM-DDThh:mm:ss.sssZ Example: after=2023-01-08T20:31:11.510Z Default value: The default value is 10 minutes.

Response

The response for a successful request contains the following properties:

Name	Data Type	Description
@id	String	Indicates the relative path to the requested endpoint.
@type	String	This property's value varies according to whether you requested data by: _ Time Period: If you requested to retrieve schedule entries by time period through the start and end parameters, then this property returns TimeSeries. _ Recently Updated Schedule Entries: if you requested to retrieve recently updated schedule entries through the after parameter, then this property returns Collection.
start	String	Indicates the timestamp (ISO 8601 - milliseconds; UTC) that identifies the start of the time period for which schedule entries were retrieved. Syntax: YYYY-MM-DDThh:mm:ss.sssZ
end	String	Indicates the timestamp (ISO 8601 - milliseconds; UTC) that identifies the end of the time period for which schedule entries were retrieved. We restrict the number of schedule entries that may be retrieved through this endpoint to 500. If the number of schedule entries in the requested time period exceeds this limit, then we will return the results for a shorter time period. Your script should check whether the requested end time (i.e., &end=End Time) matches the timestamp returned by the end response property. If there is a mismatch, then your script should submit another request with the start time set to the timestamp returned by the end response property and the end time set to the original requested end time. Syntax: YYYY-MM-DDThh:mm:ss.sssZ
items	List of dictionaries	Contains a list of schedule entries.
@included	List of dictionaries	slicer_assets=1 Only Contains a list of assets that were played within a live channel as a result of a Live Slicer. This list is restricted to the assets that were played during the time period defined by the start and end response parameter.
@links	Dictionary	slicer_assets=1 Only Contains the assets dictionary. The assets dictionary contains the following property: * href: A string value that indicates the relative path to an endpoint through which you may retrieve more information about assets.
total_items	Integer	after={Last Modified Time} Only Indicates the total number of recently updated schedule entries.

items List

The items list describes each schedule entry through the following properties:

Name	Data Type	Description
@id	String	Indicates the relative path to an endpoint that returns this schedule entry. You may not retrieve placeholder schedule entries by ID since they do not actually exist. Our system returns an invalid endpoint for placeholder schedule entries that starts with empty-.
@type	String	Returns Schedule.
ad_breaks	List of integers	Indicates the duration for each ad break associated with the asset.
content_id	String	content_type: asset or slicer Identifies an asset by its system-defined ID or a Live Slicer by the ID defined within the SlicerID setting of its Live Slicer configuration file.
content_owner	String	content_type: slicer Only Identifies the user that owns the scheduled Live Slicer by its system-defined ID. This property is only returned for Live Slicers that belong to another user.
content_type	String	Indicates whether the schedule entry points to an asset, ad break, or Live Slicer, or previously scheduled content. Valid values are: ad	asset	slicer	replay_source
created	String	Indicates the timestamp (UTC) at which the schedule entry was created. Syntax (ISO 8601): YYYY-MM-DDThh:mm:ss.sssZ
deleted	String	include_deleted=1 Only Indicates the timestamp (UTC) at which the schedule entry was deleted. Syntax (ISO 8601): YYYY-MM-DDThh:mm:ss.sssZ
desc	String	Indicates the schedule entry's description. If the schedule entry does not have a description, then this property's value varies by the type of schedule entry. _ Asset: Indicates the name assigned to the asset. _ Ad Break: Returns Ad Break. * Slicer: Returns an empty string. Schedule entries created through the CMS are not assigned a description.
dur	Integer	Indicates the schedule entry's duration in milliseconds.
end	String	Indicates the schedule entry's end time (UTC). Syntax (ISO 8601): YYYY-MM-DDThh:mm:ss.sssZ
external_id	String	Indicates a schedule entry's custom ID.
id	String	Identifies a schedule entry by its system-defined ID.
lastmod	String	Indicates the timestamp (UTC) at which the schedule entry was last modified. Syntax (ISO 8601): YYYY-MM-DDThh:mm:ss.sssZ
offset	Integer	Indicates playback offset in milliseconds. Playback offset occurs when an asset or ad break is scheduled to start in the past. Example: An offset value of 60000 is reported when an asset is scheduled for a minute in the past. For example, scheduling an asset for 11:00 AM when the current time is 11:01 AM generates an offset value of 60000.
owner	String	Indicates the system-defined ID for the user that owns the live channel associated with this schedule entry.
replaced_by	String	Indicates the system-defined ID for the schedule entry that overwrote the current schedule entry.
replay_source	String	content_type only Specifies the time frame of the content that should be played. Required values for replay_source as content_type: content_id, content_type, desc, dur, replay_source_start, replay_source_end.
replay_source_end	String	content_type: replay_source only Specifies the time (UTC) the content should stop playing. Syntax (ISO 8601): YYYY-MM-DDThh:mm:ss.sssZ
replay_source_start	String	content_type: replay_source only Specifies the time (UTC) the content should begin playing. Syntax (ISO 8601): YYYY-MM-DDThh:mm:ss.sssZ
source	Dictionary	Identifies the playlist from which this schedule entry was created.
start	String	Indicates the schedule entry's start time (UTC). Syntax (ISO 8601): YYYY-MM-DDThh:mm:ss.sssZ
type	String	Indicates the type of schedule entry. Valid values are: _ Time: Identifies an actual schedule entry. _ Empty: Identifies a placeholder schedule entry that identifies a gap in the schedule.

source Dictionary

The source dictionary identifies the playlist from which this schedule entry was created.

Name	Data Type	Description
id	String	Indicates the system-defined ID for the playlist from which this schedule entry was created.
type	String	Returns playlist.

@included List

The @included list describes each asset played within a live channel as a result of a Live Slicer through the following properties:

Name	Data Type	Description
id	String	Reserved for future use.
slicer_id	String	Indicates the ID for the Live Slicer that sliced the asset. A Live Slicer's ID is determined by the SlicerID setting within the Live Slicer's configuration file.
channel	String	Indicates the system-defined ID for the live channel on which the asset was played.
content_id	String	Indicates the asset's system-defined ID (i.e., asset ID).
content_type	slicer-asset	Returns slicer-asset.
created	String	Indicates the timestamp (UTC) at which the asset was created. Syntax (ISO 8601): YYYY-MM-DDThh:mm:ss.sssZ
desc	String	Indicates the asset's name as determined by the description setting in the Live Slicer's configuration file
lastmod	String	Indicates the timestamp (UTC) at which the asset was last modified. Syntax (ISO 8601): YYYY-MM-DDThh:mm:ss.sssZ
dur	Integer	Indicates the number of milliseconds from the asset that were included in the live channel. Example: A Live Slicer starts slicing an asset an hour before it is scheduled start time. If the Live Slicer's schedule entry is 30 minutes and it does not contain ads, then this property returns 1800000. if the Live Slicer is stopped or starts slicing a new asset immediately after the scheduled entry ends, then the actual_dur property returns 5400000.
actual_dur	Integer	Indicates the asset's duration in milliseconds.
end	String	Indicates the timestamp (UTC) at which the Live Slicer stopping sending a feed that contains this asset. Syntax (ISO 8601): YYYY-MM-DDThh:mm:ss.sssZ
external_id	String	Indicates the asset's external ID.
owner	String	Indicates the system-defined ID (i.e., user ID) assigned to the user that owns the asset.
start	String	Indicates the timestamp (UTC) at which the Live Slicer started sending a feed that contains this asset. Syntax (ISO 8601): YYYY-MM-DDThh:mm:ss.sssZ
from_schedule	Boolean	Indicates whether the asset was included in the live channel as a result of a schedule entry. Valid values are: _ True: The asset was included in the live channel as a result of a scheduled Live Slicer. _ False: The asset was included in the live channel for a time period during which an entry was not scheduled. This means that the asset's content was provided by the live channel's Live Slicer.

Sample Request/Response

The code below (Python 3) shows how to retrieve up to 500 entries scheduled within the next two hours.

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

import requests, datetime, time
from api_auth import APICredentials, APIParams
channel_id = 'Hak3zjnPLSW5o0j8GMpzRMsa' # Replace with the ID for the desired live channel.

def convert_ts(utc_tstamp):
    """
        Convert a UTC timestamp to ISO 8601 format (YYYY-MM-DDThh:mm:ss.sZ).
        :param utc_tstamp: The UTC timestamp to convert (expected milliseconds)
    """
    iso_format = "%Y-%m-%dT%H:%M:%S.%fZ"
    try:
        _ts = float("{0:.3f}".format(utc_tstamp/1000.0))
        return "{}{}".format(datetime.datetime.utcfromtimestamp(_ts).strftime(iso_format)[:-4], "Z")
    except Exception:
        print ("Invalid timestamp: {}".format(utc_tstamp))
        raise

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

    def run(self):
        self._get_multiple_schedule_entries()

    def _get_multiple_schedule_entries(self):
        start = int(time.time() * 1000.0) # Now
        end = start + (120 * 60 * 1000)  # 120 minutes later
        start = convert_ts(start)
        end = convert_ts(end)
        url = "{}{}{}{}{}{}{}".format(self.host, "/api/v4/channels/", channel_id, "/schedules?start=", start, "&end=", end)

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

        response = requests.get(
            url, params=APIParams(APICredentials()).get_params({}), headers=headers
        )

        print(response.json())

ScheduleEntry().run()

Response:

{
	'@id': '/channels/Hak3zjnPLSW5o0j8GMpzRMsa/schedules?start=2021-02-15T22:58:10.835Z&end=2021-02-16T00:58:10.835Z',
	'@type': 'TimeSeries',
	'start': '2021-02-15T22:58:10.835Z',
	'end': '2021-02-16T00:58:10.835Z',
	'items': [{
			'@id': '/channels/Hak3zjnPLSW5o0j8GMpzRMsa/schedules/2158c7452b7841158972e019a5bd5f12',
			'@type': 'Schedule',
			'created': '2021-02-16T00:57:10.402Z',
			'lastmod': '2021-02-16T00:57:10.402Z',
			'id': '2158c7452b7841158972e019a5bd5f12',
			'owner': 'ab533864a92b46a1a286cdd49b0a9bd3',
			'content_id': 'ae071e89574248c2ab179fe73d436c3e',
			'content_type': 'asset',
			'desc': 'Sports Segment',
			'dur': 2343598,
			'external_id': '',
			'start': '2021-02-16T00:57:10.402Z',
			'end': '2021-02-16T01:36:14.000Z',
			'type': 'Time',
			'ad_breaks': []
		}
	]
}