API Introduction
The Reporting API allows you to pull reporting information from the Teads Ad Manager platform.
In order to use the Reporting API you first need to obtain a valid API key, which you then use to make requests. The reporting access that you will have via the API is the same access as the owner of the API key.
The Reporting API is asynchronous and the data is made available to you in a CSV file format.
Rate Limits
Reporting API relies on rate limits to help provide a predictably pleasant experience for users.
Endpoints | Limit |
| 1 call / 30 seconds |
All others | 1 call / 5 seconds |
Please note, the rate limit applies at seat level. It means that 2 different tokens on the same seat lead to share the same limit.
Authorization & Payload
All the API calls require authorization. Authorization is done by sending a header named Authorization and with the value being the API key.
Example request
POST https://ads.teads.tv/api/reports/run
Headers:
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: application/json
Body:
{
"filters": {
"date": {
"start": "2017-11-01T00:00:00.000",
"end": "2018-11-30T23:59:59.000",
"timezone": "America/New_York"
},
"demand_source": "connect"
},
"dimensions": [
"country_code", "country_name"
],
"metrics": ["impression"]
}
Example response
{
"id": "5f82a2a6-7f6f-aaaa-bb-c73d2457d2e9",
"start": "2018-11-13T07:15:00.045Z",
"lastStatusUpdate": "2018-11-13T07:15:00.045Z",
"status": "queued",
"valid": true,
"reportProgress": {
"stepMax": 4
}
}
Reporting Methods
There are two ways to retrieve the reporting data and you should choose the method that better suits your use-case.
Method #1: One-time Reports:
Using one-time reports is flexible because it allows you to define the report filters, dimensions and metrics in the API payload.
The downside is that your report will be slower to run.
Steps:
Create your report by sending the filters, dimensions and metrics that you want (Run One-Time Report)
Get the status of the run using the run id (Get Status of Run)
When run is finished download the CSV file via HTTPS
Method #2: Saved Reports:
You can create your report once (using the Teads Ad Manager UI) and then use the API to run and download the results for your saved report.
When creating a report from the UI, you can optionally schedule the report so that it runs periodically (every day, every week, etc). If you have a scheduled report then your results will be immediately available via the API.
Non-scheduled reports:
Define your report using the Teads Ad Manager UI
Run the report using the report id you copied from the UI (Run Saved Report)
Get the status of the run using the run id (Get Status of Run)
When run is finished download the CSV file via HTTPS
Scheduled reports:
Define your report using the Teads Ad Manager UI and select the Schedule option
(next-day) Get the latest file for the report (Get Latest File for Saved Report)
Download the CSV file via HTTPS
