Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
startTime | string | No | Filter events starting on or after this date (ISO 8601 format, e.g., 2026-01-01) |
endTime | string | No | Filter events starting on or before this date (ISO 8601 format, e.g., 2026-01-31) |
Examples
GET /ads/exportClient # Default behavior (events before now)
GET /ads/exportClient?startTime=2026-01-01 # Events starting on/after Jan 1
GET /ads/exportClient?endTime=2026-01-31 # Events starting on/before Jan 31
GET /ads/exportClient?startTime=2026-01-01&endTime=2026-01-31 # Date range
Example API Usage
Here are examples of how to fetch data from the Addressable.tv API endpoint in different programming languages:import requests
url = "https://api.addressable.tv/ads/exportClient"
headers = {
"x-api-key": "YOUR_API_KEY",
"client": "YOUR_CLIENT_KEY"
}
# Optional: filter by date range
params = {
"startTime": "2026-01-01",
"endTime": "2026-01-31"
}
response = requests.get(url, headers=headers, params=params)
data = response.json()
print(data)
const fetch = require('node-fetch');
// Optional: add query params for date filtering
const params = new URLSearchParams({
startTime: '2026-01-01',
endTime: '2026-01-31',
});
const url = `https://api.addressable.tv/ads/exportClient?${params}`;
const headers = {
'x-api-key': 'YOUR_API_KEY',
client: 'YOUR_CLIENT_KEY',
};
fetch(url, { headers })
.then((response) => response.json())
.then((data) => console.log(data))
.catch((error) => console.error(error));
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
public class FetchData {
public static void main(String[] args) {
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.addressable.tv/ads/exportClient"))
.header("x-api-key", "YOUR_API_KEY")
.header("client", "YOUR_CLIENT_KEY")
.build();
client.sendAsync(request, HttpResponse.BodyHandlers.ofString())
.thenApply(HttpResponse::body)
.thenAccept(System.out::println)
.join();
}
}
package main
import (
"fmt"
"io/ioutil"
"net/http"
)
func main() {
url := "https://api.addressable.tv/ads/exportClient"
client := &http.Client{}
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-api-key", "YOUR_API_KEY")
req.Header.Add("client", "YOUR_CLIENT_KEY")
resp, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer resp.Body.Close()
body, _ := ioutil.ReadAll(resp.Body)
fmt.Println(string(body))
}
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
static async Task Main()
{
var client = new HttpClient();
var request = new HttpRequestMessage
{
Method = HttpMethod.Get,
RequestUri = new Uri("https://api.addressable.tv/ads/exportClient")
};
request.Headers.Add("x-api-key", "YOUR_API_KEY");
request.Headers.Add("client", "YOUR_CLIENT_KEY");
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
var data = await response.Content.ReadAsStringAsync();
Console.WriteLine(data);
}
}
#include <curl/curl.h>
#include <iostream>
#include <string>
static size_t WriteCallback(void *contents, size_t size, size_t nmemb, void *userp)
{
((std::string*)userp)->append((char*)contents, size * nmemb);
return size * nmemb;
}
int main()
{
CURL *curl;
CURLcode res;
std::string readBuffer;
curl = curl_easy_init();
if(curl) {
struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "x-api-key: YOUR_API_KEY");
headers = curl_slist_append(headers, "client: YOUR_CLIENT_KEY");
curl_easy_setopt(curl, CURLOPT_URL, "https://api.addressable.tv/ads/exportClient");
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, WriteCallback);
curl_easy_setopt(curl, CURLOPT_WRITEDATA, &readBuffer);
res = curl_easy_perform(curl);
if(res != CURLE_OK)
std::cout << "curl_easy_perform() failed: " << curl_easy_strerror(res) << std::endl;
curl_easy_cleanup(curl);
curl_slist_free_all(headers);
}
std::cout << readBuffer << std::endl;
return 0;
}
Response Schema
The API returns an array of ad delivery records. Each record contains detailed information about ad performance including impressions, video completion metrics, and hourly breakdowns.Example Response
[
{
"campaignName": "Holiday_2024",
"orderName": "Holiday Campaign - NFL Week 10",
"orderNickName": "NFL_W10",
"client": "ACME",
"agency": "MediaCo",
"cluster": "Sports",
"event": "NFL: Cowboys vs Eagles",
"network": "ESPN",
"eventType": "SPORTS",
"eventSubType": "NFL",
"deliveryDate": "2025-11-10T18:00:00.000Z",
"hourlyDelivery": [
{
"datetime": "2025-11-10T18:00:00.000Z",
"impressions": 12500,
"firstQuartile": 12400,
"midpoint": 12300,
"thirdQuartile": 12100,
"complete": 11900,
"creative": "Holiday_30s_v1"
}
],
"markets": "New York(501), Los Angeles(803)",
"creative": "Holiday_30s_v1",
"cpm": 45.0,
"cost": 562.5,
"impressionsDelivered": 12500,
"firstQuartile": 12400,
"midpoint": 12300,
"thirdQuartile": 12100,
"complete": 11900,
"uid": "12345",
"clientAgency": "",
"lid": "67890",
"pid": "11111",
"oid": 1234,
"aid": 5678
}
]
Response Fields
| Field | Type | Description |
|---|---|---|
campaignName | string | Campaign name |
orderName | string | Order name |
orderNickName | string | Order nickname / short name |
client | string | Client name |
agency | string | Agency name |
cluster | string | Order category/cluster (e.g., “Sports”, “Entertainment”) |
event | string | Event name where ad was delivered |
network | string | Network/channel where ad ran |
eventType | string | Event type (e.g., “SPORTS”, “ENTERTAINMENT”) |
eventSubType | string | Event sub-category (e.g., “NFL”, “College Football”, “NBA”) |
deliveryDate | string (ISO 8601) | Event start datetime (UTC) |
hourlyDelivery | array | Hourly breakdown of delivery metrics (see below for object structure) |
markets | string | Comma-separated list of targeted markets (DMA name with code, ZIP names, or “NATIONAL”) |
creative | string | Creative name(s) used, comma-separated if multiple |
cpm | number | CPM rate |
cost | number | Total cost calculated as cpm × (impressions / 1000) |
impressionsDelivered | number | Total impressions delivered |
firstQuartile | number | Count of 25% video completions |
midpoint | number | Count of 50% video completions |
thirdQuartile | number | Count of 75% video completions |
complete | number | Count of 100% video completions |
uid | string | number | Campaign unique identifier (your campaign ID) |
clientAgency | string | Agency of Record (AOR) for the campaign |
lid | string | number | Line/Order unique identifier (your order/line ID) |
pid | string | Order PID identifier |
oid | number | Our internal order ID |
aid | number | Our internal activation ID |
Hourly Delivery Object
Each item in thehourlyDelivery array contains granular hourly performance data:
| Field | Type | Description |
|---|---|---|
datetime | string (ISO 8601) | Hour timestamp |
impressions | number | Impressions delivered in this hour |
firstQuartile | number | 25% video completions in this hour |
midpoint | number | 50% video completions in this hour |
thirdQuartile | number | 75% video completions in this hour |
complete | number | 100% video completions in this hour |
creative | string | Creative name served in this hour |
Notes
- Only ads with delivered impressions (
impressions > 0) are included - By default, only live/past events are included (events that have already started)
- Use
startTimeandendTimequery parameters to filter events by date range

