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.

Base URL

Use the following base URL to perform an HTTP GET:

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

Where {endpoint} is one of the following:

Endpoint	Description
`ads/beacons`	Ad beacon events, including squeezeback ad beacons.
`ads/requests`	Ad requests sent to the ad server. Useful for identifying missed ad opportunities.
`ads/responses`	Ad responses received from the ad server.
`ads/jobs`	Ad job records.

These endpoints support HTTP GET only.

Request Parameters

Parameter	Data Type	Description	Required
start	String	Indicates the date and time (UTC) at which the statistics period should begin. Syntax: `YYYY-MM-DDThh:mm:ss` Example: `2026-08-11T14:53:00`	Either `start` or `end` is required. If only `start` is passed, the system fills in the `end`.
end	String	Indicates the date and time (UTC) at which the statistics period should end. Syntax: `YYYY-MM-DDThh:mm:ss` Example: `2026-08-11T14:57:00`	Either `start` or `end` is required. If only `end` is passed, the system fills in the `start`.
period	Integer	Aggregates the data over a defined time interval in seconds, grouping data points within consistent time windows. Accepted values: `10`, `20`, `30`, `40`, `50`, `60`, `120`	Optional; default is none
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` returns what is available. Otherwise, a `202` response is returned with the current maximum timestamp available.	Optional; default is `false`

📘
Maximum time range
The difference between start and end cannot exceed 5 minutes. Requesting a wider range returns a 422 Unprocessable Entity response.

Response Codes

Code	Meaning
200	Request succeeded. Results are returned in the `items` array.
202	Data for the requested range is still being processed. Pass `force=true` to return what is currently available.
400	Neither `start` nor `end` was supplied, or `period` was set to an unsupported value.
422	The range between `start` and `end` exceeds 5 minutes.

Sample Request

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

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 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': '2026-08-11T14:53:00',
            'end': '2026-08-11T14:57:00',
            'page': 1,
            'page_size': 1000,
            'force': True,
        }

        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("ads/beacons").run()

Response Structure

All endpoints return the same top-level structure. Records are returned in the items array.

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 range in `YYYY-MM-DDThh:mm:ss.SSSZ` format.
end	String	The end time of the requested range in `YYYY-MM-DDThh:mm:ss.SSSZ` format.
items	Array	List of records for the requested endpoint.
total_items	Integer	The total number of records returned.
max_pages	Integer	The total number of pages available.
current_page	Integer	The page number returned.

The fields returned inside items depend on the endpoint requested. Each endpoint is described below.

`ads/beacons`

Returns ad beacon events. This is the only endpoint that reports squeezeback ad data.

Field	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, for example `inserted`, `impressions`, or `midpoints`.
url	String	URL of the event call.
owner_id	String	Identifier of the owner.
owner_name	String	Owner account name.
channel_id	String	Channel ID.
channel_desc	String	Channel description.
event_id	String	Live event ID.
event_desc	String	Live event description.
asset_id	String	Asset or video ID.
asset_desc	String	Asset description.
creative_id	String	Ad creative ID.
creative_name	String	Ad creative name.
ad_id	String	Ad ID from the ad response.
initial_ad_id	String	First ad ID in the wrapper chain.
ad_duration	Float	Duration of the inserted ad, in seconds.
ad_index	String	Index of the ad within the ad break.
break_index	String	Index of the ad break.
break_type	String	Ad break type. Possible values are `standard`, `l-shape`, and `double-box`.
euid	String	End user ID, defined by the customer.
viewer_guid	String	Viewer session GUID.
ip_address	String	Viewer IP address.
user_agent	String	Viewer user agent.
meta_data	String	Flexible metadata, returned as a JSON-encoded string. Contents vary by workflow and may include game, team, or league information.
event_type	String	Beacon type. `uplynk_beacon` identifies a squeezeback ad. `ad_beacon` identifies a standard ad.

📘
Squeezeback ads
Squeezeback ads, including L-shape and double-box formats, are reported through this endpoint only. Use break_type to identify the squeezeback format and event_type to distinguish squeezeback beacons from standard ad beacons. The squeezeback fields listed above are not returned by the other ad endpoints.

📘
Reading meta_data
meta_data is a JSON-encoded string rather than a nested object, so it must be parsed before its values can be read. Workflow-specific identifiers, such as a game ID, are carried inside meta_data rather than as separate fields.

Sample Response

{
  "@id": "/api/v4/monitoring/ads/beacons?start=2026-07-29T20:55:00&end=2026-07-29T20:59:00",
  "@type": "TimeSeries",
  "start": "2026-07-29T20:55:00.000Z",
  "end": "2026-07-29T20:59:00.000Z",
  "items": [
    {
      "created_timestamp": "2026-07-29T20:55:57.280520Z",
      "logged_timestamp": "2026-07-29T20:55:57.280540Z",
      "job_id": "068d79141a2850069f6ec3620e447728",
      "beacon_id": "068d79141a2850069f6ec3620e447728-0-0--inserted",
      "event_callback_name": "inserted",
      "url": "",
      "owner_id": "9c6ea431f66e460388524de702bfeead",
      "owner_name": "[email protected]",
      "channel_id": "65adae02e9674a859deca87a02f7f3cc",
      "channel_desc": "test",
      "event_id": "",
      "event_desc": "",
      "asset_id": "82f293f0d18e47c9a54204be306a7595",
      "asset_desc": "Example Game 07/22/2026",
      "creative_id": "c87977e451ab4503863c8139d85ad499",
      "creative_name": "c87977e451ab4503863c8139d85ad499",
      "ad_id": "",
      "initial_ad_id": "",
      "ad_duration": 30.13,
      "ad_index": "0",
      "break_index": "0",
      "break_type": "l-shape",
      "euid": "",
      "viewer_guid": "d7398b4d49ef480c945479ae9173954c",
      "ip_address": "203.0.113.10",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/150.0.0.0 Safari/537.36",
      "meta_data": "{\"away_team\":\"Team A\",\"envType\":\"live\",\"game_id\":\"072226example\",\"home_team\":\"Team B\",\"league\":\"EXL\"}",
      "event_type": "uplynk_beacon"
    }
  ],
  "total_items": 1,
  "max_pages": 1,
  "current_page": 1
}

`ads/requests`

Returns ad requests sent to the ad server.

Field	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, for example `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, for example `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.

📘
Missed ad opportunities
When there is a missed ad opportunity, status is fail and failure_reason describes why the failure occurred.

`ads/responses`

Returns ad responses received from the ad server.

Field	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.

`ads/jobs`

Returns ad job records.

Field	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, for example `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, for example `live`.
video_id	String	Video identifier.
viewer_id	String	Viewer identifier.
owner_id	String	Identifier of the owner.

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