> ## 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 Criteo data source in Adriel.

## Introduction

Criteo is a global commerce-media platform best known for retargeting and performance display advertising across the open web. The connector pulls campaign- and ad-set-level performance from Criteo's Stats API, with architecture data (ad accounts, campaigns, ad sets, ads) merged from Criteo's live architecture endpoints and report-derived fallback data so deleted entities still appear in historical reporting.

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 Criteo to Adriel](/data-sources/a-f/criteo/how-to-connect).

## Data refresh strategy

### Architecture data

Architecture covers ad accounts, campaigns, ad sets, and ads. It refreshes twice daily at **4:00 PM UTC** and **5:00 AM UTC**. Architecture data is pulled live from Criteo's API, then supplemented with report-derived entities so deleted or otherwise missing campaigns and ad sets still appear alongside their historical metrics.

### Reports data

Reports include daily performance metrics for ad accounts, campaigns, ad sets, and ads.

**Real-time.** Report data is fetched from Criteo's Stats API on demand when a dashboard loads, so the latest values are always visible. On top of that, scheduled background syncs keep historical data consistent across multiple time windows.

**Refresh schedule.** Reports refresh on three overlapping schedules:

* **5:00 PM UTC daily** — syncs the last **9 days** for ad account, campaign, ad set, and ad
* **11:40 PM and 6:40 AM UTC daily** — syncs the last **3 days** for ad account, campaign, ad set, and ad
* **7:30 AM UTC on the 1st and 15th of each month** — syncs the last **30 days** for ad account, campaign, ad set, and ad

## Architecture levels

Ad account → Campaign → Ad set → Ad

## Date range limits

| Breakdown | Max range |
| --------- | --------- |
| Daily     | 93 days   |
| Weekly    | 1 year    |
| Monthly   | 2 years   |

A single report query is capped at **365 days**; wider ranges are split automatically. Criteo also rejects any query whose start date is more than **2 years** in the past.

## 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 `impressions` is the literal Criteo API field name. *Italic text* describes how a value is produced when it doesn't map cleanly to a single API field.
</Note>

### Reach & impressions

| Metric      | Description                                                         | Data type | API Key                                        |
| ----------- | ------------------------------------------------------------------- | --------- | ---------------------------------------------- |
| Impressions | Total times the ads were displayed, regardless of user interaction. | Number    | *Criteo standard metric*                       |
| Reach       | Unique users who saw the ad at least once.                          | Number    | *Criteo standard metric*                       |
| CPM         | Cost per thousand impressions.                                      | Currency  | *Adriel-computed (spend / impressions × 1000)* |

### Click performance

| Metric       | Description                                | Data type  | API Key                                  |
| ------------ | ------------------------------------------ | ---------- | ---------------------------------------- |
| Clicks (all) | Total clicks across all interaction types. | Number     | *Criteo standard metric*                 |
| Link clicks  | Clicks on the ad's link.                   | Number     | *Criteo standard metric*                 |
| CTR          | Click-through rate.                        | Percentage | *Adriel-computed (clicks / impressions)* |
| CPC          | Cost per click.                            | Currency   | *Adriel-computed (spend / clicks)*       |

### Cost & spend

<Note>
  Spend and revenue are reported in the currency configured on the Criteo advertiser account. When an ad account's currency differs from the workspace currency, values are converted using the current day's exchange rate.
</Note>

| Metric   | Description                                            | Data type | API Key                  |
| -------- | ------------------------------------------------------ | --------- | ------------------------ |
| Ad spend | Total amount spent on ads during the reporting period. | Currency  | *Criteo standard metric* |

### Conversion performance

| Metric           | Description                                                | Data type  | API Key                                  |
| ---------------- | ---------------------------------------------------------- | ---------- | ---------------------------------------- |
| Conversions      | Attributed actions matching the defined conversion events. | Number     | *Criteo standard metric*                 |
| Conversion value | Monetary value of attributed conversions.                  | Currency   | *Criteo standard metric*                 |
| Revenue          | Monetary value of attributed conversions.                  | Currency   | *Criteo standard metric*                 |
| ROAS             | Return on ad spend.                                        | Ratio      | *Adriel-computed (revenue / spend)*      |
| CPA              | Cost per acquisition.                                      | Currency   | *Adriel-computed (spend / conversions)*  |
| Conversion rate  | Conversions as a percentage of clicks.                     | Percentage | *Adriel-computed (conversions / clicks)* |

### Video performance

| Metric                                 | Description                                                        | Data type | API Key                  |
| -------------------------------------- | ------------------------------------------------------------------ | --------- | ------------------------ |
| Video impressions                      | Times a video creative started displaying.                         | Number    | *Criteo standard metric* |
| Video plays                            | Any play of the video, regardless of duration.                     | Number    | *Criteo standard metric* |
| Video played to 25% / 50% / 75% / 100% | Plays reaching each completion threshold.                          | Number    | *Criteo standard metric* |
| ThruPlays                              | Video viewed to at least 97% or 15 seconds, whichever comes first. | Number    | *Criteo standard metric* |
| Views                                  | Aggregated count of all qualified video views.                     | Number    | *Criteo standard metric* |

### Budget & schedule

| Metric          | Description                                                | Data type | API Key                  |
| --------------- | ---------------------------------------------------------- | --------- | ------------------------ |
| Budget          | Budget set on the campaign or ad set.                      | Currency  | *Criteo standard metric* |
| Daily budget    | Daily budget set on the campaign or ad set.                | Currency  | *Criteo standard metric* |
| Lifetime budget | Total budget allocated for the campaign's entire lifetime. | Currency  | *Criteo standard metric* |
| Bid strategy    | Bid strategy set on the ad set or campaign.                | Text      | *Criteo standard metric* |
| Bid cap         | Bid cap set on the ad set or campaign.                     | Currency  | *Criteo standard metric* |
| Starts          | Campaign / ad set start date.                              | Date      | *Criteo standard metric* |
| Ends            | Campaign / ad set end date.                                | Date      | *Criteo standard metric* |

### UTM tracking

<Note>
  **UTM values are parsed by Adriel, not returned by Criteo.** Adriel reads the UTM query parameters from each ad's landing URL and exposes them as both metrics (for rollup) and breakdowns (for grouping).
</Note>

| Metric       | Description                      | API Key                          |
| ------------ | -------------------------------- | -------------------------------- |
| UTM Source   | Parsed `utm_source` parameter.   | *Adriel-parsed from landing URL* |
| UTM Medium   | Parsed `utm_medium` parameter.   | *Adriel-parsed*                  |
| UTM Campaign | Parsed `utm_campaign` parameter. | *Adriel-parsed*                  |
| UTM Content  | Parsed `utm_content` parameter.  | *Adriel-parsed*                  |
| UTM Term     | Parsed `utm_term` parameter.     | *Adriel-parsed*                  |

### Campaign structure metadata

| Metric          | Description                                     | Data type | API Key                  |
| --------------- | ----------------------------------------------- | --------- | ------------------------ |
| Ad account name | Name of the advertiser account.                 | Text      | *Criteo standard metric* |
| Campaign name   | Campaign name.                                  | Text      | *Criteo standard metric* |
| Ad set name     | Ad set name.                                    | Text      | *Criteo standard metric* |
| Ad name         | Ad name.                                        | Text      | *Criteo standard metric* |
| Objective       | Campaign objective.                             | Text      | *Criteo standard metric* |
| Status          | Delivery status of the campaign, ad set, or ad. | Text      | *Criteo standard metric* |
| Creative type   | Creative format of the ad.                      | Text      | *Criteo standard metric* |
| Creative URL    | Creative asset URL.                             | URL       | *Criteo standard metric* |
| Channel         | Channel where the ad is published.              | Text      | *Criteo standard metric* |
| Keyword name    | Keyword name (search campaigns only).           | Text      | *Criteo standard metric* |

## Breakdowns

### Standard hierarchy

| Breakdown  | Description                         | API Key     |
| ---------- | ----------------------------------- | ----------- |
| Ad account | Group by Criteo advertiser account. | `adAccount` |
| Campaign   | Group by Criteo campaign.           | `campaign`  |
| Ad set     | Group by Criteo ad set.             | `adSet`     |
| Ad         | Group by Criteo ad.                 | `ad`        |

### Audience & device

| Breakdown | Description                                | API Key   |
| --------- | ------------------------------------------ | --------- |
| Device    | Group by device (mobile, desktop, tablet). | `device`  |
| Country   | Group by country code.                     | `country` |

### Time & date grouping

<Note>
  Criteo's API returns daily records; Adriel groups them into these views for reporting. All time-grouping breakdowns are Adriel-side aggregations of the same underlying daily data.
</Note>

| Breakdown                  | Description                                                  |
| -------------------------- | ------------------------------------------------------------ |
| Auto Time Breakdown        | Automatically picks the best granularity for the date range. |
| Daily                      | Split reports by day.                                        |
| Weekly (Start: Mon)        | Split reports by ISO week, starting Monday.                  |
| Weekly (Start: Sun)        | Split reports by week, starting Sunday.                      |
| Week Date Breakdown        | Split by the start-date of each week.                        |
| Week Number Breakdown (W#) | Split by week number in the year.                            |
| Monthly                    | Split reports by calendar month.                             |
| Quarterly                  | Split reports by calendar quarter.                           |
| Yearly                     | Split reports by calendar year.                              |
| No Grouping                | Do not break down; return one aggregated row.                |

### Creative analysis

<Note>
  Adriel post-processes ad creatives to generate these breakdowns.
</Note>

| Breakdown        | Description                                              |
| ---------------- | -------------------------------------------------------- |
| Ad Copy          | Groups ads by the words in the ad copy (auto-tokenized). |
| Color Clustering | Groups creative images by dominant visual color.         |
| Emoji Analysis   | Groups ads by emojis present in the ad copy.             |
| Creative Image   | Auto-clusters visually similar creative images.          |

### UTM tracking

<Note>
  Criteo doesn't return UTM values; Adriel parses them from each ad's landing URL and exposes them as breakdowns for grouping.
</Note>

| Breakdown    | Description                     |
| ------------ | ------------------------------- |
| UTM Source   | Group by parsed `utm_source`.   |
| UTM Medium   | Group by parsed `utm_medium`.   |
| UTM Campaign | Group by parsed `utm_campaign`. |
| UTM Content  | Group by parsed `utm_content`.  |
| UTM Term     | Group by parsed `utm_term`.     |

### Overview & status

<Note>
  Adriel derives these grouping labels from campaign metadata so results can be organized without a platform-side breakdown field.
</Note>

| Breakdown | Description                                              |
| --------- | -------------------------------------------------------- |
| Channel   | Constant grouping label used for cross-connector rollup. |
| Platform  | Groups results by the platform where ads are broadcast.  |
| Objective | Group by campaign objective.                             |
| Status    | Group by campaign / ad set / ad delivery status.         |

## Limitations

* **Rotating refresh tokens** — every Criteo token refresh issues a new refresh token, which the connector persists automatically. If a refresh response omits the new value, the connection becomes unrecoverable until it is reconnected. This is the single most important operational behavior to monitor.
* **Reach summed across days may overcount** — Reach is a daily count of unique users. When viewed over a date range longer than one day, the total can overstate true unique reach because the same user may be counted on multiple days.
* **Deleted entities are retained** — historical data for deleted campaigns, ad sets, and ads is preserved through the report-derived architecture fallback rather than excluded.
* **Historical start-date cap** — Criteo rejects report queries whose start date is more than 2 years in the past, and a single query cannot span more than 365 days.

## API references

* [Criteo Marketing Solutions API](https://developers.criteo.com/marketing-solutions/docs)
* [Criteo Stats (analytics) endpoints](https://developers.criteo.com/marketing-solutions/docs/analytics)
* [Criteo OAuth 2.0 authorization](https://developers.criteo.com/marketing-solutions/docs/authentication)

## See also

* [How to connect Criteo to Adriel](/data-sources/a-f/criteo/how-to-connect) (paired how-to)
* [Criteo Retail Media data reference](/data-sources/a-f/criteo-retail-media/data-reference) — for sponsored products on retailer sites