Data reference

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 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

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.

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

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.

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

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).

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

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.

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

Adriel post-processes ad creatives to generate these breakdowns.

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

Criteo doesn’t return UTM values; Adriel parses them from each ad’s landing URL and exposes them as breakdowns for grouping.

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

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

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.

Introduction

Data refresh strategy

Architecture data

Reports data

Architecture levels

Date range limits

Metrics

Reach & impressions

Click performance

Cost & spend

Conversion performance

Video performance

Budget & schedule

UTM tracking

Campaign structure metadata

Breakdowns

Standard hierarchy

Audience & device

Time & date grouping

Creative analysis

UTM tracking

Overview & status

Limitations

API references

See also

​Introduction

​Data refresh strategy

​Architecture data

​Reports data

​Architecture levels

​Date range limits

​Metrics

​Reach & impressions

​Click performance

​Cost & spend

​Conversion performance

​Video performance

​Budget & schedule

​UTM tracking

​Campaign structure metadata

​Breakdowns

​Standard hierarchy

​Audience & device

​Time & date grouping

​Creative analysis

​UTM tracking

​Overview & status

​Limitations

​API references

​See also

Introduction

Data refresh strategy

Architecture data

Reports data

Architecture levels

Date range limits

Metrics

Reach & impressions

Click performance

Cost & spend

Conversion performance

Video performance

Budget & schedule

UTM tracking

Campaign structure metadata

Breakdowns

Standard hierarchy

Audience & device

Time & date grouping

Creative analysis

UTM tracking

Overview & status

Limitations

API references

See also