Getting started

The Reporting API is asynchronous. Submit a run, poll until it finishes, then download the CSV or XLSX file.

This page is the canonical reference for the base URL, authentication, and request conventions shared by every endpoint. Operation pages under Operations and the OpenAPI reference link back here instead of repeating this setup.

Base URL

https://ads.teads.tv

All endpoints in this API are relative to this base URL.

Authentication

All calls send the TAM API key in the Authorization header. Send the raw key value, not a Bearer prefix — this API uses a static API key, not an OAuth 2.0 bearer token or JSON Web Token. See the MDX Web Docs authentication guide for background on HTTP authentication schemes in general.

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

Every request in this documentation set uses these same three headers unless noted otherwise.

Keys are scoped to a user and seat and inherit that user's permissions on that seat. The user must be able to see campaign reporting on every seat you request with ad_owner.

A 401 response on any endpoint means the Authorization header is missing or the key is invalid — regenerate or check the key below.

Generate an API key

1. In Teads Ad Manager, open Settings (gear icon in the header).
2. In API Keys, click Generate API Key.
3. Optionally click the edit icon to rename the key.

If a user can access multiple seats, one key can report on all of them, or you can generate a distinct key per seat.

Run a one-time report

A one-time report (also called an ad hoc report) sends filters, dimensions, and metrics directly in the request body instead of referencing a report saved in the TAM UI.

curl --request POST \
  --url https://ads.teads.tv/api/reports/run \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "format": "csv",
    "filters": {
      "date": {
        "start": "2024-01-01T00:00:00.000",
        "end": "2024-01-31T23:59:59.000",
        "timezone": "UTC"
      }
    },
    "dimensions": ["day", "advertiser_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
  }
}

Poll GET /api/reports/status/{id} until status is finished, then download the file from uri. See Get status of a run for the full status lifecycle. Optional callbackUrl on the run body: TAM POSTs { "reportUid": "", "uri": "http://..." } when the run completes.

Use reporting dimension and metric API names (impression, advertiser_name), not TAM UI labels (Impressions, Advertiser Name). See dimensions and metrics.

Every run request — one-time or saved — is subject to the rate limits and rolling 24-hour run quota described in Quotas and limits.

Saved reports

A saved report is a report template defined once in the TAM Reports tab (dimensions, metrics, filters, date range) and referenced afterward by its numeric report id, instead of resending the full definition on every call.

Non-scheduled

1. Define the report in TAM (name, seats, advertisers, campaigns, date range, dimensions, metrics, timezone, CSV or Excel).
2. POST /api/reports/{id}/run
3. Poll GET /api/reports/status/{uid}
4. Download from uri when finished

Scheduled

1. In TAM, toggle Schedule, pick the period (previous day, previous week, past 7 days, previous month, sliding month, month to date, or custom) and frequency (every day, every week, every month, or a delivery day).
2. GET /api/reports/{id}/latest-file
3. Download from url — the file is already generated.

Save stores the template without running it. Save and Run stores it and generates the first file. Recurrent reports keep appearing in report history until you delete them.

To speed up a report, shorten the date range, reduce dimensions and metrics, or schedule it in advance.

Seat-wide reports

Teammates in the same seat can view, run, and duplicate each other's reports. Toggle Include all team member reports on the Reports tab.

• You cannot edit someone else's report; duplicate it first.
• You cannot download a file another user generated; run it yourself, then download.
• Restricted advertiser permissions still hide advertisers you cannot access.

Data destinations

Scheduled TAM reports can land in AWS S3 or Google Cloud Storage. That path also works with this API through the ad_owner filter, so you can consolidate seat data into one report.

Multi-seat (ad_owner)

The seats a key can access follow the generating user's permissions. Roles that can view campaign reporting: Ad Manager Admin, Ad Manager User, Reporting Admin, and Reporting User.

Request rules

• Dates use timestamps such as 2024-01-01T00:00:00.000. Data before 2020 is unavailable. A report period may not exceed one year.
• Geo dimensions are available from 1 April 2024. Precision is based on IP address; confidence decreases from country → region → market area → city → postal code.
• format is csv (default) or xlsx.
• Rate limits and the 24-hour run quota are documented under quotas and limits.