Introduction to Reporting API
The Reporting API allows you to retrieve reporting information from Teads Ad Manager.
This functions asynchronously, and the data is provided in a CSV file format.
Refer to the guides below to start using Teads' Reporting API
Manage and generate API keys
Manage and generate API keys
In order to use the Teads Ad Manager APIs, you will require a valid API key.
API keys are defined at the user & seat level, and will have the same level of access as the user (in the corresponding seat) who owns the API key.
If a user has access to multiple seats, a single API key can be used to report on all these seats. Alternatively, distinct API keys can be generated for each of those seats.
Follow the steps below to generate API Keys:
Open "Settings" screen by clicking on the gear icon located in the header.
Click the "Generate API Key" button in the "API Keys" section.
Optional - Click edit icon to change the API Key name.
Rate limits
Rate limits
The reporting API relies on rate limits to provide a predictably pleasant experience for users.
Limits by endpoint:
/reports/:id/run: 1 call / 30 seconds/reports/run" : 1 call / 30 secondsAll others: 1 call / 5 seconds
Note: the rate limit applies at seat level. This means that 2 different tokens on the same seat will share the same limit.
Authorization & Payload
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 of a 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 of a 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
Reporting Methods
There are two methods available for retrieving the reporting data that best aligns with your specific use-case.
One-time Reports:
Using one-time reports offers flexibility since it allows you to define the report filters, dimensions, and metrics in the API payload.
However, the downside is that one-time reports might take longer to generate compared to other methods.
Below are the steps to generate the report:
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
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 subsequently.
When creating a report from the UI, you have the option to schedule the report so that it runs periodically (every day, every week, etc). If you have a scheduled report, your results will be available immediately via the API.
Follow the steps below to generate non-scheduled reports:
Define your report using the Teads Ad Manager UI
Run the report using the report id you copied from the UI. For more information, refer to this article here.
Get the status of the run using the run id. For more information, refer to this article here.
When the run has finished, download the CSV file via HTTPS.
Follow the steps below to generate scheduled reports:
Define your report using the Teads Ad Manager UI and select the Schedule option
Get the latest file for the report. For more information, refer to this article here.
Download the CSV file via HTTPS
Reporting on multiple seats
Reporting on multiple seats
You can report on multiple seats in a single report by using the ad_owner filter. Depending on the usage of the ad_owner filter, the report will have the following behaviour:
If the
ad_ownerfilter is not set in the request, the report will only contain data associated with the seat where the API key was generated.If the
ad_ownerfilter is set to a list of seat ids, the report will contain data associated with those seats.If the
ad_ownerfilter is set to an empty list, the report will contain data to all seats that the API token has access to.
For detailed documentation about filters, refer to API - Reporting Filters, Dimensions and Metrics.
The seats that a given API key has access to is determined by the permissions associated with the user that generated the API key. The user must at least have the permission to see campaign reporting on all requested seats.
For more information on user management, refer to this article here.
Additional information can also be found below:
About API Quotas
About API Quotas
For more information about API report quotas, refer to this article here.
About 3rd Party Integrations
About 3rd Party Integrations
Teads Reporting API allows any 3rd party to develop integrations with Teads Ad Manager Reporting data.
While we may not have knowledge of all the existing integrations, it is important to note that client support and troubleshooting for such integrations are handled exclusively by the 3rd party involved.
For details on specific integrations with platforms we collaborated with, please refer to the articles provided below:
3rd Party Integrations - Supermetrics (coming soon)