> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adriel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data reference

> Metrics, breakdowns, refresh cadence, and limits for the Teads data source in Adriel.

## Introduction

Teads Ad Manager is an outstream video and native advertising platform. The connector pulls campaign performance from the Teads Ads API, including video engagement (impressions, video views, quartile completions), spend, viewability, attention, and conversion metrics.

Reports are retrieved through an asynchronous create-and-poll flow, normalized from CSV, and written into a daily cache. Dashboards read from this cache, not from the live API, so widget queries are bounded by the cached window rather than the live reporting API.

As a marketing connector, metrics, breakdowns, and currencies are standardized so widgets can aggregate across sources without additional configuration.

To connect this data source, see [How to connect Teads to Adriel](/data-sources/o-z/teads/how-to-connect).

## Data refresh strategy

### Architecture data

The ad account and the campaigns, ad sets, and ads available under it are refreshed alongside the report cache. New campaigns appear after the next scheduled refresh.

### Reports data

This is a daily-cache connector.

* **Initial fetch.** After connection, the last **90 days** of daily data are retrieved.
* **Refresh schedule.** At **8:00 AM UTC** every day, the latest **14 days** of data are refreshed in place. The rolling 14-day window covers late-arriving conversions and any restatements Teads issues within that period without a manual reconnection.

## Architecture levels

Ad account → Campaign → Ad set → Ad

## Metrics

<Note>
  **How to read the columns**
  **Data type** uses this vocabulary: Number, Currency, Percentage, Ratio, Duration, Date, Text, URL, Array, Boolean.
  **API Key** in code style like `impression` is the literal Teads API field name. *Italic text* describes how a value is produced when it doesn't map cleanly to a single API field.
</Note>

### Spend & cost

<Note>
  Currency values are reported in each ad account's configured currency. Spend is reported through turnover-based metrics; budget-delivered variants are not available (see Limitations).
</Note>

| Metric                  | Description                                                                                        | Data type | API Key                                  |
| ----------------------- | -------------------------------------------------------------------------------------------------- | --------- | ---------------------------------------- |
| Turnover                | Budget invoiced by Teads. Includes the Ad Manager fee; excludes Added Value budget and Agency fee. | Currency  | `turnover_value`                         |
| Advertising turnover    | Pure advertising cost. Excludes Added Value budget, Ad Manager fee, and Agency fee.                | Currency  | `turnover_advertising_value`             |
| Fee turnover            | Ad Manager fee cost only.                                                                          | Currency  | `turnover_fee_value`                     |
| Average cost per result | Average price per result based on invoiced spend.                                                  | Currency  | `turnover_average_cost_per_result_value` |
| Average CPM             | Average cost per thousand impressions based on invoiced spend.                                     | Currency  | `turnover_average_cpm_value`             |
| Average CPC             | Average cost per click based on invoiced spend.                                                    | Currency  | `turnover_average_cpc_value`             |

### Delivery & clicks

| Metric             | Description                                    | Data type  | API Key                      |
| ------------------ | ---------------------------------------------- | ---------- | ---------------------------- |
| Results delivered  | Number of results delivered (billable volume). | Number     | `advertiser_billable_volume` |
| Impressions        | Ad impressions.                                | Number     | `impression`                 |
| Clicks             | Ad clicks.                                     | Number     | `click`                      |
| Click-through rate | Clicks as a share of impressions.              | Percentage | `click-rate`                 |

### Video completion funnel

| Metric                              | Description                                            | Data type  | API Key                                      |
| ----------------------------------- | ------------------------------------------------------ | ---------- | -------------------------------------------- |
| Video starts                        | Video plays that started.                              | Number     | `video_start`                                |
| Video plays at 25%                  | Plays reaching the first quartile.                     | Number     | `video_firstQuartile`                        |
| Video plays at 50%                  | Plays reaching the midpoint.                           | Number     | `video_midpoint`                             |
| Video plays at 75%                  | Plays reaching the third quartile.                     | Number     | `video_thirdQuartile`                        |
| Video completions                   | Plays reaching 100%.                                   | Number     | `video_complete`                             |
| Video completion rate               | Completions as a share of starts.                      | Percentage | `video_complete-rate`                        |
| Video progress per second (1–29s)   | Video plays still playing at each second from 1 to 29. | Number     | `video_progress-1` … `video_progress-29`     |
| Progress per second (1–29s)         | General progress views at each second from 1 to 29.    | Number     | `progress-1` … `progress-29`                 |
| Display progress per second (1–29s) | Display progress at each second from 1 to 29.          | Number     | `display_progress-1` … `display_progress-29` |

### Viewability (MOAT)

| Metric                              | Description                                                          | Data type  | API Key                                 |
| ----------------------------------- | -------------------------------------------------------------------- | ---------- | --------------------------------------- |
| Analyzed impressions                | Impressions analyzed, unfiltered for invalid traffic.                | Number     | `moat_analyzed_impression`              |
| Analyzed impressions (IVT-filtered) | Impressions analyzed, filtered for invalid traffic.                  | Number     | `moat_analyzed_impression_filtered`     |
| In-view measurable impressions      | Impressions that could be measured for viewability.                  | Number     | `moat_inview_measurable_impression`     |
| Viewable impressions                | Valid and viewable impressions.                                      | Number     | `moat_inview_viewable_impression`       |
| Viewable rate                       | Valid and viewable impressions as a share of measurable impressions. | Percentage | `moat_viewable_rate`                    |
| Total in-view time                  | Total time ads were in view, in milliseconds.                        | Duration   | `moat_total_inview_time`                |
| Average in-view time                | Average time ads were in view, in milliseconds.                      | Duration   | `moat_average_inview_time`              |
| Total ad length                     | Total measured ad duration, in milliseconds.                         | Duration   | `moat_total_ad_length`                  |
| Complete in-view impressions        | Impressions viewable through video completion.                       | Number     | `moat_video_complete_inview_impression` |
| Average ad length                   | Average measured ad duration, in milliseconds.                       | Duration   | `moat_video_average_ad_length`          |
| 1-second in-view impressions        | Impressions in view for at least one second.                         | Number     | `moat_1s_inview_impression`             |

### Attention (Lumen)

| Metric                          | Description                                                                                           | Data type  | API Key                                |
| ------------------------------- | ----------------------------------------------------------------------------------------------------- | ---------- | -------------------------------------- |
| Attention per 1,000 impressions | Aggregate "eyes on" visual attention per 1,000 impressions, estimated by Lumen models.                | Number     | `lumen_attention_per_1000_impressions` |
| Average dwell time              | Average time, in seconds, that viewed ads were looked at, estimated by Lumen models.                  | Duration   | `lumen_average_dwell_time`             |
| Average view rate               | Share of impressions receiving at least one eye fixation (minimum 100 ms), estimated by Lumen models. | Percentage | `lumen_average_view_rate`              |

### Reach & conversions

<Note>
  Unique impressions are estimated and only compatible with specific breakdown and metric combinations; some groupings will not return a value.
</Note>

| Metric                 | Description                                   | Data type | API Key                 |
| ---------------------- | --------------------------------------------- | --------- | ----------------------- |
| Unique impressions     | Estimated unique Teads IDs exposed to the ad. | Number    | `uv_impression`         |
| Post-view conversions  | Conversions attributed after an ad view.      | Number    | `post_view_conversion`  |
| Post-click conversions | Conversions attributed after an ad click.     | Number    | `post_click_conversion` |

## Breakdowns

<Note>
  Every column present in the cached data can be used as a breakdown; there is no fixed allowlist. The groupings below are the standard ones exposed for Teads.
</Note>

### Standard hierarchy

| Breakdown  | Description                        | API Key     |
| ---------- | ---------------------------------- | ----------- |
| Ad account | Group by Teads advertiser account. | `adAccount` |
| Campaign   | Group by campaign.                 | `campaign`  |
| Ad set     | Group by ad set (line item).       | `adSet`     |
| Ad         | Group by creative.                 | `ad`        |

### Time & date grouping

<Note>
  Teads returns daily records; Adriel aggregates them into these views for reporting.
</Note>

| Breakdown | Description                      |
| --------- | -------------------------------- |
| Daily     | Split reports by day.            |
| Weekly    | Split reports by week.           |
| Monthly   | Split reports by calendar month. |

## Limitations

* **Daily cache, not live.** Dashboards read from the daily cache rather than the live Teads API, so widget queries are bounded by the cached window. Report data is written into the cache through an asynchronous create-and-poll flow and normalized from CSV.
* **Generic table compatibility.** Teads data appears as a generic table and does not natively combine with other connector types unless they share identical breakdowns. Cross-connector analysis requires blend data configuration.
* **Spend is turnover-based only.** All budget-delivered spend variants (for example `budget_delivered_value` and its averages) are excluded from the API request due to API incompatibility; only the six turnover-based spend metrics are available.
* **Unique-reach compatibility.** Unique impressions (`uv_impression`) is only compatible with specific breakdown and metric combinations.
* **Restatements outside the refresh window.** Only the trailing 14 days are re-fetched on each refresh; corrections Teads issues to data older than that window are not picked up automatically.
* **API key rotation.** Authentication is a single static API key. Rotating the key on the Teads side requires re-entering it in the connector settings.

## API references

* Teads Ads API — reports are created and polled asynchronously against the host `ads.teads.tv`, then normalized from CSV. Requests authenticate with a single API key sent as the value of the `Authorization` header.

## See also

* [How to connect Teads to Adriel](/data-sources/o-z/teads/how-to-connect) (paired how-to)
* [The Trade Desk data reference](/data-sources/o-z/the-trade-desk/data-reference) — for another async-poll programmatic video connector