Ad Server Debug API

The Ad Server Debug API retrieves ad jobs.

Get Ad Jobs

Retrieves up to 100 ad jobs. For search results that are greater than 100 ad jobs, we only return the most recent ones.

Use search filters to refine your search results.

Request

Request syntax:

GET https://services.uplynk.com/api/v3/adproxy/ad-debug/jobs

Query string parameters:

Filter search results by passing the following optional parameters:

Parameter	Description
channel_guid	Filters ad job data by the live channel or live event during which it was requested. 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?. Select the desired live event. Verify that the Details tab is selected. Find the live event's system-defined ID under the GUID label.
debug_name	Filters ad job data by tagged playback session(s). Tag a playback session by passing the ad_debug parameter in the playback URL.
end	Filters ad job data by the time period during which the ad was requested. Set this parameter to the desired end time (UTC). If you pass the end parameter without the start parameter, then ad job data prior to the specified end time will be returned. Syntax: YYYY-MM-DDThh:mm:ss.ssssssZ Example: 2024-01-08T20:31:11.510000Z
includes	Determines whether transactions and beacon data will be included in the response. Valid values are: ads_info: Pass this value to include ad parameters in the response. callbacks: Pass this value to include beacons in the response. transactions: Pass this value to include transaction in the response. Use the following syntax to include ad parameters, transactions, and beacon data in the response: includes=transactions,callbacks,ads_info Default value: transactions
playback_type	Identifies whether ad jobs for live streams or VOD content will be retrieved. Valid values are: live \| vod
start	Filters ad job data by the time period during which the ad was requested. Set this parameter to the desired start time (UTC). If you pass the start parameter without the end parameter, then the end parameter will be set to the time at which the request was delivered. Syntax: YYYY-MM-DDThh:mm:ss.ssssssZ Example: 2024-01-08T20:31:11.510000Z
status	Filters ad job data by status. Learn more.
video_guid	Filters ad job data by the VOD asset during which it was requested. Identify an asset by its system-defined ID. Where can I find an asset ID? Navigate to the CMS library by clicking the Content tab. Select the desired asset. The asset ID corresponding to the asset selected in the previous step is listed under the GUID label.
viewer_guid	Filters ad job data by the playback session for which it was requested. Identify your playback session by its system-defined ID. Where can I find a playback session ID? Implement the Preplay API within your custom player to retrieve the playback session ID. Alternatively, inspect your playback URL to find out your own playback session. Learn more.

Authentication

Pass a digital signature based off of msg.

Learn more.

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 Job<Collection>.
items	List of dictionaries	Contains ad jobs.
total_items	Integer	Indicates the total number of ad jobs that were included in the response.

items List

The items list describes one or more ad jobs via the following parameters:

Name	Data Type	Description
ad_request_index	Integer	Indicates the position of the ad break.
ads_info	Dictionary	Indicates the data that was passed to the ad decision server. This data is only included in the response when the includes parameter contains ads_info.
ads_info_parameters	Dictionary	Contains the playback_url parameter. playback_url Indicates the playback URL. Use this playback URL to replicate the viewing experience when troubleshooting ad delivery issues.
callbacks	List of dictionaries	Contains the set of beacons associated with the current ad job. Beacon data is only included in the response when the includes parameter contains callbacks.
channel_guid	String	Indicates the system-defined ID of the live channel or live event that spawned the ad request.
created_at	String	Indicates the date and time (UTC) at which the ad job was initiated. Syntax: YYYY-MM-DDThh:mm:ss.ffffffZ Learn more.
failure_reason	String	Indicates an ad job's failure reason.
id	String	Indicates the system-defined ID assigned to this ad job.
owner_guid	String	Indicates the user IDA user ID uniquely identifies a user account via an alpanumeric system-defined ID. for the account that owns the live channel that spawned the ad request.
playback_type	String	Indicates whether the ad job was spawned from a live stream or VOD. Valid values are: live \| vod
prebid_transaction	Dictionary	Indicates the request and response from the Prebid server.
status	String	Indicates the ad job's status. Valid values are: complete \| fail \| pending \| processing Learn more.
transactions	List of dictionaries	Contains the set of transactions associated with the current ad job. By default, transaction data is included in the response. Use the includes query string parameter to hide transactions.
unfulfilled_requests	List	Contains failed transactions.
updated_at	String	Indicates the date and time (UTC) at which this ad job was last updated. Syntax: YYYY-MM-DDThh:mm:ss.ffffffZ Learn more.
video_guid	String	Indicates the system-defined ID for the VOD asset associated with this playback session.
viewer_guid	String	Indicates the playback session ID.

callbacks Dictionary

The callbacks dictionary describes a beacon via the following properties:

Name	Data Type	Description
name	String	Identifies a beacon by its name.
show_browser	Boolean	Returns True for clickthrough beacons.
tracking_urls	List of string values	Contains a list of URLs for beaconing data.
type	String	Identifies the type of beacon.
url	String	Indicates the URL to which beacon data was sent.

prebid_transaction Dictionary

The prebid_transaction dictionary describes a request and response to a Prebid server using the following properties:

Name	Data Type	Description
body_download_time	Float	Indicates the total amount of time, in seconds, that it took for the request body to be downloaded.
connection_time	Float	Indicates the total amount of time, in seconds, that it took to establish a HTTP connection to the Prebid server.
created_at	String	Indicates the date and time (UTC) at which this request was initiated. Syntax: YYYY-MM-DDThh:mm:ss.ssssss Example: 2024-01-08T20:31:11.510000
failure_reason	String	Indicates the reason that a request to the Prebid server failed.
header_request_time	Float	Indicates the total amount of time, in seconds, that it took to generate request headers.
invalid_data		Indicates errors with the request parameters passed to the Prebid server.
raw_response	String	Contains the raw XML response provided by the Prebid server.
redirects	List of string values	Contains a list of URL redirects.
request_params		Identifies each query string parameter included in the request.
request_succeeded	Boolean	Indicates whether the request to the Prebid server was successful.
request_url	String	Indicates the request's URL.
status_code	String	Indicates the status code for the response from the Prebid server.
total_elapsed_request_time	Float	Indicates the total amount of time, in seconds, that it took for the request to be submitted to the Prebid server.
warnings	Dictionary	Contains the set of warnings that occurred. Each dictionary identifies a type of warning. Example: "warnings": { "ValuelessParameter": { "industry": 5, "_fw_asset": 16 }

transactions List

The transactions list describes each transaction using the following properties:

Name	Data Type	Description
body_download_time	Float	Indicates the total amount of time, in seconds, that it took for the request body to be downloaded.
connect_timeout	Float	Indicates the connection timeout in seconds. A transaction will timeout and fail when the value reported in the connnection_time parameter exceeds this value.
connection_time	Float	Indicates the total amount of time, in seconds, that it took to establish a HTTP connection to the ad decision server.
created_at	String	Indicates the date and time (UTC) at which this request was initiated. Syntax: YYYY-MM-DDThh:mm:ss.ssssss Example: 2024-01-08T20:31:11.510000
creative_ids	List of Dictionaries	Contains the IDs for each ad creative.
end_time	String	Indicates the timestamp at which our servers parsed the response from the ad decision server.
errors	List of string values	Contains a list of errors that occurred when processing the response.
failure_code	Integer	Indicates the transaction's failure code. A transaction may contain multiple ads.
failure_reason	String	Indicates the transaction's failure reason. A transaction may contain multiple ads.
header_request_time	Float	Indicates the total amount of time, in seconds, that it took to generate request headers.
id	Integer	Indicates the transaction's system-defined ID.
is_wrapper	String	Indicates whether the transaction represents the initial ad request or a wrapper. Valid values are: true: Indicates that the transaction is a wrapper. false: Indicates that the transaction represents the initial ad request.
num_ads	Integer	Indicates the number of ads contained within the response.
num_beacons		Indicates the number of beacons included in the ad response.
num_wrappers	Integer	Indicates the number of wrappers contained within the response.
parent_id	Integer	Indicates the system-defined ID assigned to the transaction that corresponds to this request.
pod_location	String	Identifies the position of the ad break within the live stream or VOD asset.
raw_response	String	Contains the raw XML response provided by the ad decision server.
read_timeout	Float	Indicates the timeout, in seconds, for reading the request. A request will timeout when we establish a connection to the ad decision server and the amount of time that the download is interrupted exceeds this value.
redirects	List of string values	Contains a list of URL redirects.
request_headers	Dictionary	Describes each header included in the request using a key-value pair.
request_method	String	Identifies the request's HTTP method (e.g., GET).
request_params		Identifies each query string parameter included in the request.
request_succeeded	Boolean	Indicates whether the ad request succeeded.
request_url	String	Indicates the request's URL.
response_byte_size	Integer	Indicates the size, in bytes, of the response.
start_time	String	Indicates the timestamp at which our service started processing the transaction. This timestamp occurs before the request is submitted to the ad decision server.
status	String	Indicates the transaction's status. Valid values are: Complete \| Fail \| Pending \| Processing
total_elapsed_request_time	Float	Indicates the total amount of time, in seconds, that it took for the request to be submitted to the ad decision server.
user_agent	String	Identifies the user agent (e.g., media player) associated with the ad request.
warnings	Dictionary	Contains the set of warnings that occurred. Each dictionary identifies a type of warning. Example: "warnings": { "ValuelessParameter": { "industry": 5, "_fw_asset": 16 }
wrapper_depth	Integer	Identifies the number of times that an ad decision server forwarded this ad request to another server.

creative_ids List

The creative_ids list describes each ad creative via the following properties:

Name	Data Type	Description
creative_id	String	Indicates the ad creative's ID.
external_id	String	Indicates the ID that identifies the ad creative's ID and URL.
universal_id	String	Indicates the unique ID assigned to an ad. This ID is returned in the response provided by the ad decision server.

Name

Data Type

Description

creative_id

String

Indicates the ad creative's ID.

external_id

String

Indicates the ID that identifies the ad creative's ID and URL.

universal_id

String

Indicates the unique ID assigned to an ad.

This ID is returned in the response provided by the ad decision server.

Sample Request/Response

Call the get_ad_jobs module (Python 3) to retrieve ad jobs.

import json, requests
from api_auth import APICredentials, APIParams

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

    def run(self):
        self._get_ad_jobs()

    def _get_ad_jobs(self):
        url = "{}{}".format(self.host, "/api/v3/adproxy/ad-debug/jobs?status=Completed")

        headers = {'Content-Type': 'application/json'}
  
        response = requests.get(
            url, params=APIParams(APICredentials()).get_params({}), data=json.dumps(payload), headers=headers
        )
  
        print(response.json())
  
GetAdJobs().run()