Getting started

The Reporting API is asynchronous. Submit a report definition, poll its status, and download the result when processing finishes.

Base URL

https://api.teads.tv/v1/analytics

Authentication

All requests require an OAuth 2.0 bearer token (often issued as a JWT; see jwt.io for a primer) and JSON content type. See the MDN authentication guide for background on HTTP authentication schemes in general.

Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

The account associated with the token must have reporting rights. Every request in this documentation set uses these same headers unless noted otherwise; reference pages link back here instead of repeating this section.

Create a report

The date filter, dimensions, and metrics are required. Other filters, email recipients, and format are optional.

curl --request POST \
  --url https://api.teads.tv/v1/analytics/custom \
  --header 'Authorization: Bearer <OAuth bearer token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "filters": {
      "placements": [17270],
      "date": {
        "start": "2020-01-01T00:00:00+01:00",
        "end": "2020-01-01T23:59:00+01:00",
        "timezone": "Europe/Paris"
      }
    },
    "dimensions": ["day", "placement"],
    "metrics": [
      "start",
      "complete",
      "click",
      "impression",
      "firstQuartile",
      "midpoint",
      "thirdQuartile",
      "teads_billing"
    ],
    "emails": ["reports@example.com"],
    "format": "xlsx"
  }'

Example response:

{
  "id": "abcdefgh-cff2-4753-a08b-ee4587de4e9d",
  "start": "2020-12-14T16:35:05.269Z",
  "lastStatusUpdate": "2020-12-14T16:35:05.269Z",
  "status": "queued",
  "valid": true,
  "reportProgress": {
    "stepMax": 4
  }
}

Poll and download

Poll GET /custom/{id} until status is finished. The finished response contains a download url. A report can also enter error or killed.

Use GET /running/list to inspect all queued and processing reports. If the concurrent-report limit blocks new work, wait for a report to finish or cancel one with PUT /custom/{id}/kill.

Request rules

• Dates are ISO 8601 timestamps. Data before 2020 is unavailable.
• A report period may not exceed one year.
• A report using the uv flag for more than 100 days must use the day dimension.
• IDs in filters are numeric resource IDs, except status filters, which use database status values.
• format filter values are strings such as inread; output format is csv, jsonv1, or xlsx.

See filters and formats for the full request model.