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

## Introduction

Criteo Retail Media is Criteo's commerce-media offering for sponsored product ads that run on retailers' own websites and apps. It is a separate data source from standard Criteo (open-web retargeting and display): it reports on retail campaigns down to the individual promoted product (SKU) and the keywords that trigger them, with retail-specific outcomes such as attributed and assisted sales, orders, and units.

The connector pulls reporting at four levels — campaign, line item (ad set), promoted product (ad), and keyword — along with the architecture that organizes them. 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 Retail Media to Adriel](/data-sources/a-f/criteo-retail-media/how-to-connect).

## Data refresh strategy

### Architecture data

Architecture covers the ad account, campaigns, line items (ad sets), promoted products (ads), and keywords. It refreshes twice daily at **4:00 PM UTC** and **5:00 AM UTC**. Stale entities are removed on each refresh, so the structure stays aligned with what exists in Criteo Retail Media.

### Reports data

Reports include daily performance for campaigns, line items, promoted products, and keywords.

**Cache only.** This connector serves report data from cached daily performances rather than fetching live from Criteo on each dashboard load. When a dashboard opens, values are aggregated from the most recent snapshot. Metrics based on uniqueness (such as unique visitors) can be overvalued when viewed over a date range longer than one day.

**Cache fill and refresh.** When the data source is first created, the cache is backfilled for **730 days** across the ad account, campaign, line item, promoted product, and keyword levels. After that, report data refreshes on the following schedule:

* **Every 3 hours, at 0 minutes past the hour (UTC)** — syncs the last **30 days** for campaign, line item, promoted product, and keyword

Data is considered reliable within the cache sync period. Data outside this range may be incomplete, missing, or not fully accurate due to legacy caching behavior.

## Architecture levels

Ad account → Campaign → Line item (ad set) → Promoted product (ad) → Keyword

Ad account is used for navigation only and is not a reporting level. A report requested at the ad-account level is served at the campaign level instead.

## Date range limits

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

These caps keep query sizes manageable. Data outside a breakdown's window may be truncated.

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

### Delivery

| Metric      | Description                                                              | Data type | API Key       |
| ----------- | ------------------------------------------------------------------------ | --------- | ------------- |
| Impressions | Total times the sponsored ads were displayed, regardless of interaction. | Number    | `impressions` |
| Clicks      | Total clicks on the sponsored ads.                                       | Number    | `clicks`      |

### Cost

<Note>
  Spend is reported in the currency configured on the Criteo Retail Media account. When that 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 the sponsored ads during the reporting period. | Currency  | `spend` |

### Retail conversions

<Note>
  Attributed outcomes are credited to ads that led directly to a purchase; assisted outcomes credit ads that contributed to a purchase without being the final touch. Both use the attribution window configured on the retailer's Criteo account.
</Note>

| Metric            | Description                                                  | Data type | API Key            |
| ----------------- | ------------------------------------------------------------ | --------- | ------------------ |
| Attributed sales  | Sales value attributed to the sponsored ads.                 | Currency  | `attributedSales`  |
| Attributed units  | Product units sold that are attributed to the sponsored ads. | Number    | `attributedUnits`  |
| Attributed orders | Orders attributed to the sponsored ads.                      | Number    | `attributedOrders` |
| Assisted sales    | Sales value where the sponsored ads assisted the purchase.   | Currency  | `assistedSales`    |
| Assisted units    | Product units from assisted conversions.                     | Number    | `assistedUnits`    |

### Reach and frequency

<Note>
  Unique visitors and frequency are available at the campaign and line-item levels only; they are not returned at the promoted-product or keyword levels.
</Note>

| Metric          | Description                                             | Data type | API Key          |
| --------------- | ------------------------------------------------------- | --------- | ---------------- |
| Unique visitors | Distinct users who saw the sponsored ads at least once. | Number    | `uniqueVisitors` |
| Frequency       | Average number of impressions per unique visitor.       | Ratio     | `frequency`      |

### Campaign structure metadata

| Metric                | Description                                                      | Data type | API Key                  |
| --------------------- | ---------------------------------------------------------------- | --------- | ------------------------ |
| Ad account name       | Name of the Criteo Retail Media account.                         | Text      | *Architecture attribute* |
| Campaign name         | Campaign name.                                                   | Text      | *Architecture attribute* |
| Line item name        | Line item (ad set) name.                                         | Text      | *Architecture attribute* |
| Promoted product name | Promoted product name.                                           | Text      | *Architecture attribute* |
| Keyword name          | Keyword text.                                                    | Text      | *Architecture attribute* |
| Status                | Delivery status of the campaign, line item, or promoted product. | Text      | *Architecture attribute* |
| Budget                | Budget set on the campaign or line item.                         | Currency  | *Architecture attribute* |

## Breakdowns

### Reporting levels

| Breakdown             | Description                            | API Key                          |
| --------------------- | -------------------------------------- | -------------------------------- |
| Campaign              | Group by Criteo Retail Media campaign. | `campaignId`                     |
| Line item (ad set)    | Group by line item.                    | `lineItemId`                     |
| Promoted product (ad) | Group by promoted product (SKU).       | `advProductId`, `advProductName` |
| Keyword               | Group by keyword (sponsored search).   | `keyword`                        |

### Time and date grouping

<Note>
  Criteo Retail Media returns daily records; Adriel groups them into these views for reporting, so 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.                      |
| 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.                |

### Overview and 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.            |
| Status    | Group by campaign, line item, or promoted product delivery status. |

## Limitations

* **Cache-only reporting** — report data is served from cached daily snapshots rather than fetched live, so figures reflect the most recent sync. The last 30 days refresh every 3 hours; the cache is backfilled to 730 days at creation. Data outside the sync window may be incomplete or not fully accurate.
* **Uniqueness metrics can overcount** — Unique visitors and Frequency are daily counts. When viewed over a range longer than one day, totals can overstate true unique reach because the same user may be counted on multiple days.
* **Metric availability by level** — Unique visitors and Frequency are returned only at the campaign and line-item levels, not at the promoted-product or keyword levels.
* **No derived rate metrics** — standard rate metrics such as CTR, CPC, CPM, CPO, and ROAS are not provided by this connector; they are not requested from the Criteo Retail Media API.
* **Ad account is navigation only** — the ad account is not a reporting level, so ad-account report queries are served at the campaign level.
* **Date look-back caps** — daily breakdowns are limited to 93 days, weekly to 1 year, and monthly to 2 years.

## API references

* [Criteo Retail Media developer portal](https://developers.criteo.com/retail-media/docs)
* [Criteo Retail Media reporting endpoints](https://developers.criteo.com/retail-media/docs/analytics-reports)
* [Criteo OAuth 2.0 (client credentials)](https://developers.criteo.com/retail-media/docs/authentication)

## See also

* [How to connect Criteo Retail Media to Adriel](/data-sources/a-f/criteo-retail-media/how-to-connect) (paired how-to)
* [Criteo data reference](/data-sources/a-f/criteo/data-reference) — for open-web retargeting and display, the separate standard Criteo connector