Reporting API

This article provides guidance on using Teads Ad Manager's Reporting API.

Updated over a week ago

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

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:

  1. Open "Settings" screen by clicking on the gear icon located in the header.

  2. Click the "Generate API Key" button in the "API Keys" section.

  3. Optional - Click edit icon to change the API Key name.

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 seconds

  • All 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

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:


Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: application/json

"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

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:

  1. Create your report by sending the filters, dimensions and metrics that you want (Run One-Time Report)

  2. Get the status of the run using the run id (Get Status of Run)

  3. 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:

  1. Define your report using the Teads Ad Manager UI

  2. Run the report using the report id you copied from the UI. For more information, refer to this article here.

  3. Get the status of the run using the run id. For more information, refer to this article here.

  4. When the run has finished, download the CSV file via HTTPS.

    Follow the steps below to generate scheduled reports:

  1. Define your report using the Teads Ad Manager UI and select the Schedule option

  2. Get the latest file for the report. For more information, refer to this article here.

  3. Download the CSV file via HTTPS

Additional information can also be found below:

About API Quotas

For more information about API report quotas, refer to this article here.

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:

Did this answer your question?