Reports
- Reports are requested & retrieved through asynchronous endpoints
- All reports are at the daily granularity except for the Attributed Transactions report, which is hourly
- Currently, reports are only available for any single campaign or any single line item
- Report date window has a max of 100 days; data is retained for up to 3 years
- Report attribution windows and timezone are fully configurable
- Data latency is typically 2-8 hours, but may have minor adjustments through the 120th hour before finalization
- Data is batched per hour and same day data may be partially available
- Reports are cached for at least 1 hour before expiration
- Exact expiration is indicated by the
expiresAt
field in the /status response - Learn more about our attribution rules
New Metrics
- We intend to introduce new metrics periodically; these new columns will always be appended at the end of table outputs
Report Types
Type | Description |
---|---|
| Daily metrics aggregated for any single campaign or line item |
| Daily metrics segmented by the type of retailer web page an ad creative rendered on, such as home page, browse pages, search pages, product detail pages, checkout pages etc. |
| Daily metrics segmented by the keyword or phrase used to land on the search page where an ad creative rendered; non-search pages are not associated with keywords |
| Daily metrics segmented by the category of product advertised in the ad creative; categories are standardized across brands and retailers, which may differ from retailer-specific categories |
| Daily metrics segmented by the product being advertised in the ad creative |
| Hourly logs of each transaction attributable to an impression or a click; includes advanced dimensions such as the specific attribution rule used to match the impression or click to a sale |
Report Metrics
- Most metrics are available for every report type, with some exceptions to
assistedSales
andassistedUnits
which apply only to Line Item reports, - Attributed Transactions report only has two metrics:
attributedSales
andattributedUnits
Metric | Description |
---|---|
| Measured when an ad creative renders on a page; an ad creative may display products from one or more campaigns; each unique campaign is counted once; used in all report types except for Product and Product Category reports Report Types : Campaign reports only |
| Measured when an ad creative renders on a page; an ad creative may display products from one or more line items; each unique line item is counted once; used in all report types except for Product and Product Category reports Report Types : Line Item reports only |
| Measured when a promoted product is rendered on the page, whether as a single ad creative or as one of many products in an ad creative; each product is counted once separately Report Types : Product and Product Category reports only |
| Measured when an ad creative is clicked on, which incurs a cost to the advertiser for open auction campaigns |
| For open auctions campaigns, the total cost of clicks for the advertiser; inclusive of platform fees |
| Sales revenue attributed to a click or impression; exclusive of |
| Units sold attributed to a click or impression; exclusive of |
| Orders (or transactions) attributed to a click or impression |
| Click-through-rate (CTR), calculated by dividing |
| Cost-per-click (CPC), calculated by dividing |
| Return-on-ad-spend (ROAS), calculated by dividing |
| Cost-per-order (CPO), calculated by dividing |
| Sales revenue attributed to a click or impression on the path to purchase leading to the sale; exclusive of Report Types : Line Item reports only |
| Units sold attributed to a click or impression on the path to purchase leading to the sale; Report Types : Line Item reports only |
| Number of unique visitors an impression painted for Report Types : Campaign, Line Item and Summary reports only |
| An average representing how often an impression has painted for the same user Report Types : Campaign, Line Item and Summary reports only |
Report Dimensions
- Available dimensions vary by report type
- The Attributed Transactions report is documented separately below
Dimension | Description |
---|---|
| Date based on the requested time zone |
| Campaign ID of the requested report |
| Campaign name of the request report |
| Type of campaign configured |
| Line item ID of the requested report Report Types : Line Item reports only |
| Line item name of the requested report Report Types : Line Item reports only |
| Retailer ID of the retailer the line item served on Report Types : Line Item reports only |
| Retailer name of the retailer the line item served on Report Types : Line Item reports only |
| Type of retailer web page an ad creative rendered on, such as home page, browse pages, search pages, product detail pages, checkout pages etc. Report Types : Page Type reports only |
| Keyword or phrase used to land on the search page where an ad creative rendered Report Types : Keyword reports only |
| Category of product advertised; categories are standardized across brands and retailers, which may differ from retailer-specific categories Report Types : Product & Product Category reports only |
| Advertised product ID; this references the same ID used in Catalogs Report Types : Product reports only |
| Advertised product name Report Types : Product reports only |
| Advertised product brand ID Report Types : Product reports only |
| Advertised product brand name; names are standardized across retailers Report Types : Product reports only |
Attributed Transactions Report Dimensions & Metrics
- Note this report contains historical data, so you can always determine how each sale was attributed according to the data and rules enforced at the time
- Keep this in mind when comparing data against other reports - properties such as
advProductCategory
could drift as product categories may evolve over time - Learn more about our attribution rules
Column Name | Column Type | Description |
---|---|---|
| Dimension | Date of advertisement |
| Dimension | Hour of advertisement |
| Dimension | Date of the attributed product purchase |
| Dimension | Hour of the attributed product purchase |
| Dimension | Days between advertisement and purchase |
| Dimension | Campaign ID of the requested report |
| Dimension | Campaign name of the request report |
| Dimension | Line item ID of the requested report |
| Dimension | Line item name of the requested report |
| Dimension | Retailer name of the retailer the line item served on |
| Dimension | Type of retailer web page an ad creative rendered on, such as home page, browse pages, search pages, product detail pages, checkout pages etc. |
| Dimension | Keyword or phrase used to land on the search page where an ad creative rendered |
| Dimension | Advertised product ID; this references the same ID used in Catalogs |
| Dimension | Advertised product name |
| Dimension | Category of product advertised; categories are standardized across brands and retailers, which may differ from retailer-specific categories |
| Dimension | Advertised product Global Trade Item Number (GTIN), if available; also known as European Article Number (EAN) or Universal Product Code (UPC) |
| Dimension | Advertised product Manufacturer Part Number (MPN), if available |
| Dimension | Purchased product ID; this references the same ID used in Catalogs |
| Dimension | Purchased product name |
| Dimension | Category of product purchased; categories are standardized across brands and retailers, which may differ from retailer-specific categories |
| Dimension | Purchased product Global Trade Item Number (GTIN), if available; also known as European Article Number (EAN) or Universal Product Code (UPC) |
| Dimension | Purchased product Manufacturer Part Number (MPN), if available |
| Dimension | Type of ad engagement the purchase was attributed to |
| Dimension | Attribution rule used to match the impression or click to a sale |
| Dimension | Sales channel the attributed purchase was made through |
| Dimension | Click and view attribution window of the requested report |
| Metric | Sales revenue attributed to a click or impression |
| Metric | Units sold attributed to a click or impression |
Endpoints
POST /reports/campaigns
Create a Campaign Report RequestPOST /reports/line-items
Create a Line Item Report RequestGET /reports/{reportId}/status
Get Status of a Specific ReportGET /reports/{reportId}/output
Download Output of a Specific Report
Report Request Attributes
Attribute | Description | Values | Required |
---|---|---|---|
| Campaign or Line Item ID of the desired report Use | a single or a group of e.g. | Required |
| Type of report requested |
| R |
| Earliest day to report; inclusive | YYYY-MM-DD | R |
| Latest day to report; inclusive | YYYY-MM-DD | R |
| Time zone for the report | database tz syntax, eg. | R |
| The post-click attribution window, defined as the maximum number of days considered between a click and a conversion for attribution; conversions are attributed to the date of conversion, not the date of click; defaults to campaign settings if omitted; must be specified if |
| R |
| The post-view attribution window, defined as the maximum number of days considered between an impression and a conversion for attribution; conversions are attributed to the date of conversion, not the date of impression; defaults to campaign settings if omitted; must be less than or equal to |
| R |
| Format of the report data returned |
| Optional |
Reporting Asynchronous Workflow: Step 1 of 3
- First, create a request for the campaign or line item report with the desired attributes
- This generates a
reportId
representing the report
Create a Report Request
This endpoint creates a request for a campaign or line item report

https://api.criteo.com/2022-04/retail-media/reports/campaigns

https://api.criteo.com/2022-04/retail-media/reports/line-items
Sample Request
curl -X POST "https://api.criteo.com/2022-04/retail-media/reports/campaigns" \
-H "Authorization: Bearer myaccesstoken" \
-H "Content-Type: application/json" \
-d '{
"data": {
"type": "RetailMediaReportRequest",
"attributes": {
"id": "8343086999167541140",
"reportType": "summary",
"startDate": "2020-04-06",
"endDate": "2020-06-04",
"timeZone": "America/New_York"
}
}
}'
Sample Response
{
"data": {
"type": "RetailMediaReportStatus",
"id": "2e733b8c-9983-4237-aab9-17a42f4267cb",
"attributes": {
"status": "pending",
"rowCount": null,
"fileSizeBytes": null,
"md5Checksum": null,
"createdAt": null,
"expiresAt": null,
"message": null
}
}
}
Reporting Asynchronous Workflow: Step 2 of 3
- Next, use the
reportId
to poll the report status endpoint until one is successfully computed
Get Status of a Specific Report
This endpoint retrieves the status of a specific report. Status can be pending
, success
, failure
, or expired

https://api.criteo.com/2022-04/retail-media/reports/{reportId}/status
Sample Request
curl -X GET "https://api.criteo.com/2022-04/retail-media/reports/2e733b8c-9983-4237-aab9-17a42f4267cb/status" \
-H "Authorization: Bearer myaccesstoken"
Sample Response
{
"data": {
"type": "RetailMediaReportStatus",
"id": "2e733b8c-9983-4237-aab9-17a42f4267cb",
"attributes": {
"status": "success",
"rowCount": null,
"fileSizeBytes": null,
"md5Checksum": null,
"createdAt": null,
"expiresAt": null,
"message": null
}
}
}
Sample Request
curl -X GET "https://api.criteo.com/2022-04/retail-media/reports/2e733b8c-9983-4237-aab9-17a42f4267cb/status" \
-H "Authorization: Bearer myaccesstoken"
Sample Response
{
"data": {
"type": "RetailMediaReportStatus",
"id": "2e733b8c-9983-4237-aab9-17a42f4267cb",
"attributes": {
"status": "success",
"rowCount": 60,
"fileSizeBytes": 28967,
"md5Checksum": "2c15b77740028435ca476823df7fb4f8",
"createdAt": "2020-07-18T04:27:59.658Z",
"expiresAt": "2020-07-25T04:27:59.658Z",
"message": null
}
}
}
Reporting Asynchronous Workflow: Step 3 of 3
- Finally, download the report using the report output endpoint
- Report outputs are cached for at least 1 hour before expiration
- Exact expiration is indicated by the
expiresAt
field in the /status response
Download Output of a Specific Report
This endpoint returns the specific report in the requested format

https://api.criteo.com/2022-04/retail-media/reports/{reportId}/output
Sample Request
curl -X GET "https://api.criteo.com/2022-04/retail-media/reports/2e733b8c-9983-4237-aab9-17a42f4267cb/output" \
-H "Authorization: Bearer myaccesstoken"
Sample Response
// format="json-compact"
{
"columns": ["campaignId", "campaignName", "campaignType", "date", "impressions", "clicks", "ctr", "spend", "cpc", "attributedSales", "attributedUnits", "roas", "orders", "cpo"],
"data": [
["8343086999167541140", "Campaign 123", "auction", "2020-04-06", 832400, 10066, 0.01209227439, 17816.82, 1.77, 315891.44, 6162, 17.7299562997, 5877, 3.0316181725],
["8343086999167541140", "Campaign 123", "auction", "2020-04-07", 903520, 10129, 0.0112105985, 17827.04, 1.76, 244618.1, 4550, 13.7217451691, 4236, 4.2084608121],
// ...
["8343086999167541140", "Campaign 123", "auction", "2020-06-03", 320477, 4733, 0.0147686105, 8472.07, 1.79, 217790, 5671, 25.7068225357, 5242, 1.6161903853],
["8343086999167541140", "Campaign 123", "auction", "2020-06-04", 402933, 4908, 0.0121806851, 8638.08, 1.76, 195345.03, 5112, 22.6144038953, 4815, 1.7939937695]
],
"rows": 60
}
Updated 16 days ago