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:
Parameter | Data Type | Description | Required |
---|---|---|---|
start | String | Indicates 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. |
end | String | Indicates 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. |
page | Integer | Page number of results to return. | Optional; default is 1 |
page_size | Integer | Number of items returned per page. | Optional; default is 1000 |
force | Boolean | If 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
/adbeacon
EndpointField | Data Type | Description |
---|---|---|
created_timestamp | String | Timestamp when the record was created. |
logged_timestamp | String | Timestamp when the event was logged. |
job_id | String | Unique identifier for the ad job. |
beacon_id | String | Unique identifier for the beacon event. |
event_callback_name | String | Type of event (e.g., midpoints ). |
url | String | URL of the event call. |
owner_id | String | Identifier of the owner. |
/adjob
Endpoint
/adjob
EndpointField | Data Type | Description |
---|---|---|
created_timestamp | String | Timestamp when the record was created. |
logged_timestamp | String | Timestamp when the event was logged. |
job_id | String | Unique identifier for the ad job. |
status | String | Status of the ad job (e.g., complete ). |
ad_request_index | Integer | Index of the ad request. |
channel_id | String | Channel ID associated with the ad. |
owner_name | String | Owner of the ad job. |
asset_type | String | Type of asset (e.g., live ). |
video_id | String | Video identifier. |
viewer_id | String | Viewer identifier. |
owner_id | String | Identifier of the owner. |
/adrequest
Endpoint
/adrequest
EndpointField | Data Type | Description |
---|---|---|
created_timestamp | String | Timestamp when the request was created. |
logged_event_timestamp | String | Timestamp when the event was logged. |
job_id | String | Unique identifier for the ad job. |
status | String | Status of the request (e.g., complete ). |
request_id | String | Unique identifier for the request. |
total_elapsed_request_time | Float | Total time taken for the request. |
connection_time | Float | Time taken to establish a connection. |
header_request_time | Float | Time taken for the header request. |
body_download_time | Float | Time taken to download the body. |
user_agent | String | User agent making the request. |
pod_location | String | Location in the ad pod (e.g., midroll ). |
failure_reason | String | Reason for failure, if applicable. |
request_succeeded | Boolean | Whether the request succeeded. |
is_wrapper | Boolean | Whether the request was a wrapper. |
start_timestamp | String | Start timestamp. |
end_timestamp | String | End timestamp. |
parent_request_id | String | Parent request ID, if applicable. |
owner_id | String | Identifier of the owner. |
/adresponse
Endpoint
/adresponse
EndpointField | Data Type | Description |
---|---|---|
created_timestamp | String | Timestamp when the response was created. |
logged_timestamp | String | Timestamp when the event was logged. |
job_id | String | Unique identifier for the ad job. |
status | String | Status of the response. |
request_id | String | Unique identifier for the request. |
ad_count | Integer | Number of ads returned. |
wrapper_count | Integer | Number of wrappers used. |
impression_count | Integer | Number of impressions recorded. |
range_bytes | Integer | Byte range of the response. |
event_error_message | Array | List of error messages, if any. |
owner_id | String | Identifier of the owner. |
This API enables robust tracking of ad performance, allowing for better analysis and optimization of ad workflows.