Ads Statistics

The Ads Stats API provides insights into ad-related monitoring data, including ad beacons, ad jobs, ad requests, and ad responses. This API allows you to retrieve statistics about ad performance, request timing, and response handling across multiple ad-serving endpoints. The collected data enables better tracking and optimization of ad delivery and performance.

Where {endpoint} can be one of the following:

  • /adbeacon
  • /adjob
  • /adrequest
  • /adresponse

Base URL

Use the following base URL:

https://services.uplynk.com/api/v4/monitoring/{endpoint}

Request Parameters

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

ParameterData TypeDescriptionRequired
startStringIndicates the date and time (UTC) at which the statistics start period should begin.
Syntax: YYYY-MM-DDThh:mm:ss
Example: 2023-01-08T20:31:11
Either start or end is required. If only start is passed, the system will fill the end based on a 15-minute block.
endStringIndicates the date and time (UTC) at which the statistics start period should end.
Syntax: YYYY-MM-DDThh:mm:ss
Example: 2023-01-08T20:31:11
Either start or end is required. If only end is passed, the system will fill a start based on a 15-minute block.
pageIntegerPage number of results to return.Optional; default is 1
page_sizeIntegerNumber of items returned per page.Optional; default is 1000
forceBooleanIf data for a portion of the date range specified is not yet processed, force=true will return what is available. Otherwise, a 202 response will be returned with the current maximum timestamp available.Optional; default is false

Sample Request

import json
import requests
from api_auth import APICredentials, APIParams  

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

    def run(self):
        """
        Get the latest Ad statistics for the specified endpoint.
        """
        self._get_latest_ad_stats()

    def _get_latest_ad_stats(self):
        params = {
            'start': '2025-02-12T15:53:00',
            'end': '2025-02-12T15:57:10',
            'page': 1,
            'page_size': 5000,
            'force': False,
        }
        
        url = f"{self.host}/api/v4/monitoring/{self.endpoint}"

        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__":
    GetLatestAdStats("adrequest").run()

Response Schema

The response structure depends on the requested endpoint. Below are example schemas for each:


/adbeacon Endpoint

FieldData TypeDescription
created_timestampStringTimestamp when the record was created.
logged_timestampStringTimestamp when the event was logged.
job_idStringUnique identifier for the ad job.
beacon_idStringUnique identifier for the beacon event.
event_callback_nameStringType of event (e.g., midpoints).
urlStringURL of the event call.
owner_idStringIdentifier of the owner.

/adjob Endpoint

FieldData TypeDescription
created_timestampStringTimestamp when the record was created.
logged_timestampStringTimestamp when the event was logged.
job_idStringUnique identifier for the ad job.
statusStringStatus of the ad job (e.g., complete).
ad_request_indexIntegerIndex of the ad request.
channel_idStringChannel ID associated with the ad.
owner_nameStringOwner of the ad job.
asset_typeStringType of asset (e.g., live).
video_idStringVideo identifier.
viewer_idStringViewer identifier.
owner_idStringIdentifier of the owner.

/adrequest Endpoint

FieldData TypeDescription
created_timestampStringTimestamp when the request was created.
logged_event_timestampStringTimestamp when the event was logged.
job_idStringUnique identifier for the ad job.
statusStringStatus of the request (e.g., complete).
request_idStringUnique identifier for the request.
total_elapsed_request_timeFloatTotal time taken for the request.
connection_timeFloatTime taken to establish a connection.
header_request_timeFloatTime taken for the header request.
body_download_timeFloatTime taken to download the body.
user_agentStringUser agent making the request.
pod_locationStringLocation in the ad pod (e.g., midroll).
failure_reasonStringReason for failure, if applicable.
request_succeededBooleanWhether the request succeeded.
is_wrapperBooleanWhether the request was a wrapper.
start_timestampStringStart timestamp.
end_timestampStringEnd timestamp.
parent_request_idStringParent request ID, if applicable.
owner_idStringIdentifier of the owner.

/adresponse Endpoint

FieldData TypeDescription
created_timestampStringTimestamp when the response was created.
logged_timestampStringTimestamp when the event was logged.
job_idStringUnique identifier for the ad job.
statusStringStatus of the response.
request_idStringUnique identifier for the request.
ad_countIntegerNumber of ads returned.
wrapper_countIntegerNumber of wrappers used.
impression_countIntegerNumber of impressions recorded.
range_bytesIntegerByte range of the response.
event_error_messageArrayList of error messages, if any.
owner_idStringIdentifier of the owner.

This API enables robust tracking of ad performance, allowing for better analysis and optimization of ad workflows.