Reports - Criteo Docs

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
The 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 in CMax Help Center

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
`summary`string	Daily metrics aggregated for any single campaign or line item
`pageType`string	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.
`keyword`string	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
`productCategory`string	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
`product`string	Daily metrics segmented by the product being advertised in the ad creative
`attributedTransactions`string	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 and assistedUnits which apply only to Line Item reports
Attributed Transactions report only has two metrics: attributedSales and attributedUnits

Metric	Description
`impressions`	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
`impressions`	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
`impressions`	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
`clicks`	Measured when an ad creative is clicked on, which incurs a cost to the advertiser for open auction campaigns
`spend`	For open auctions campaigns, the total cost of clicks for the advertiser; inclusive of platform fees
`attributedSales`	Sales revenue attributed to a click or impression; exclusive of`assistedSales`
`attributedUnits`	Units sold attributed to a click or impression; exclusive of`assistedUnits`
`attributedOrders`	Orders (or transactions) attributed to a click or impression
`ctr`	Click-through-rate (CTR), calculated by dividing`clicks`by`productImpressions`for Product and Product Category report types; for all other report types, the appropriate`placementImpressions`is used instead
`cpc`	Cost-per-click (CPC), calculated by dividing`spend`by`clicks`; inclusive of platform fees
`roas`	Return-on-ad-spend (ROAS), calculated by dividing`attributedSales`by`spend`; inclusive of platform fees
`cpo`	Cost-per-order (CPO), calculated by dividing`spend`by`attributedOrders`; inclusive of platform fees
`assistedSales`	Sales revenue attributed to a click or impression on the path to purchase leading to the sale; exclusive of`attributedSales` Report Types: Line Item reports only
`assistedUnits`	Units sold attributed to a click or impression on the path to purchase leading to the sale;`attributedUnits` Report Types: Line Item reports only
`uniqueVisitors`	Number of unique visitors an impression painted for Report Types: Campaign, Line Item and Summary reports only
`frequency`	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`	Date based on the requested time zone
`campaignId`	Campaign ID of the requested report
`campaignName`	Campaign name of the request report
`campaignTypeName`	Type of campaign configured
`lineItemId`	Line item ID of the requested report Report Types: Line Item reports only
`lineItemName`	Line item name of the requested report Report Types: Line Item reports only
`retailerId`	Retailer ID of the retailer the line item served on Report Types: Line Item reports only
`retailerName`	Retailer name of the retailer the line item served on Report Types: Line Item reports only
`pageTypeName`	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`	Keyword or phrase used to land on the search page where an ad creative rendered Report Types: Keyword reports only
`advProductCategory`	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
`advProductId`	Advertised product ID; this references the same ID used inCatalogs Report Types: Product reports only
`advProductName`	Advertised product name Report Types: Product reports only
`brandId`	Advertised product brand ID Report Types: Product reports only
`brandName`	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.
Learn more about our Attribution Rules in CMax Help Center

Column Name	Column Type	Description
`advDate`	Dimension	Date of advertisement
`advHour`	Dimension	Hour of advertisement
`purchasedDate`	Dimension	Date of the attributed product purchase
`purchasedHour`	Dimension	Hour of the attributed product purchase
`daysDifference`	Dimension	Days between advertisement and purchase
`campaignId`	Dimension	Campaign ID of the requested report
`campaignName`	Dimension	Campaign name of the request report
`lineItemId`	Dimension	Line item ID of the requested report
`lineItemName`	Dimension	Line item name of the requested report
`retailerName`	Dimension	Retailer name of the retailer the line item served on
`pageTypeName`	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.
`keyword`	Dimension	Keyword or phrase used to land on the search page where an ad creative rendered
`advProductId`	Dimension	Advertised product ID; this references the same ID used inCatalogs
`advProductName`	Dimension	Advertised product name
`advProductCategory`	Dimension	Category of product advertised; categories are standardized across brands and retailers, which may differ from retailer-specific categories
`advProductGtin`	Dimension	Advertised product Global Trade Item Number (GTIN), if available; also known as European Article Number (EAN) or Universal Product Code (UPC)
`advProductMpn`	Dimension	Advertised product Manufacturer Part Number (MPN), if available
`purchasedProductId`	Dimension	Purchased product ID; this references the same ID used inCatalogs
`purchasedProductName`	Dimension	Purchased product name
`purchasedProductCategory`	Dimension	Category of product purchased; categories are standardized across brands and retailers, which may differ from retailer-specific categories
`purchasedProductGtin`	Dimension	Purchased product Global Trade Item Number (GTIN), if available; also known as European Article Number (EAN) or Universal Product Code (UPC)
`purchasedProductMpn`	Dimension	Purchased product Manufacturer Part Number (MPN), if available
`advEngagement`	Dimension	Type of ad engagement the purchase was attributed to
`advToPurchasedProductRelationship`	Dimension	Attribution rule used to match the impression or click to a sale
`salesChannel`	Dimension	Sales channel the attributed purchase was made through
`attributionWindow`	Dimension	Click and view attribution window of the requested report
`attributedSales`	Metric	Sales revenue attributed to a click or impression
`attributedUnits`	Metric	Units sold attributed to a click or impression

Endpoints

POST /reports/campaigns Create a Campaign Report Request
POST /reports/line-items Create a Line Item Report Request
GET /reports/{reportId}/status Get Status of a Specific Report
GET /reports/{reportId}/output Download Output of a Specific Report

Report Request Attributes

Attribute	Description	Values	Required
`id`or`ids`string	Campaign or Line Item ID of the desired report Use`id`when requesting a single Campaign or Line item ID; use`ids`otherwise	a single or a group of`campaignId`or`lineItemId` e.g. `id`:`CampaignId`, OR `ids`: ly granularity except for the Att, (maximum 50 ids per call)	Required
`reportType`string	Type of report requested	`summary`,`pageType`,`keyword`,`productCategory`,`product`,`attributedTransactions`	R
`startDate`date	Earliest day to report; inclusive	YYYY-MM-DD	R
`endDate`date	Latest day to report; inclusive	YYYY-MM-DD	R
`timeZone`string	Time zone for the report	database tz syntax, eg.`America/New_York`,`Europe/Paris`,`UTC`	R
`clickAttributionWindow`string	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`viewAttributionWindow`is	`7D`,`14D`,`30D`	R
`viewAttributionWindow`string	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`clickAttributionWindow`; must be specified if`clickAttributionWindow`is	`none`,`1D`,`7D`,`14D`,`30D`	R
`format`string	Format of the report data returned	`json-compact`(default),`json-newline`,`json`,`csv`	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 Sample Request - Campaign Report

curl -X POST "https://api.criteo.com/preview/retail-media/reports/campaigns" \
    -H "Authorization: Bearer <MY_ACCESS_TOKEN>" \
    -H "Content-Type: application/json" \
    -d '{
            "data": {
                "type": "RetailMediaReportRequest",
                "attributes": {
                    "id": "8343086999167541140",
                    "metrics": ["impressions"],
      						  "dimensions": ["date"],
                    "reportType": "summary",
                    "startDate": "2020-04-06",
                    "endDate": "2020-06-04",
                    "timeZone": "America/New_York",
                    "campaignType": "sponsoredProducts",
      						  "salesChannel": "offline"
                }
            }
        }'

Sample Request - Line Item Report

curl -X POST "https://api.criteo.com/preview/retail-media/reports/line-items" \
    -H "Authorization: Bearer <MY_ACCESS_TOKEN>" \
    -H "Content-Type: application/json" \
    -d '{
            "data": {
                "type": "RetailMediaReportRequest",
                "attributes": {
                    "id": "8343086999167541140",
                    "metrics": [
                        "impressions"
                    ],
      						  "dimensions": [
                        "date"
                    ],
                    "reportType": "summary",
                    "startDate": "2020-04-06",
                    "endDate": "2020-06-04",
                    "timeZone": "America/New_York",
                    "campaignType": "sponsoredProducts",
      						  "salesChannel": "offline"
                }
            }
        }'

Sample Response - Both

{
    "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 Sample Request

curl -X GET "https://api.criteo.com/preview/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/preview/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 Sample Request

curl -X GET "https://api.criteo.com/preview/retail-media/reports/2e733b8c-9983-4237-aab9-17a42f4267cb/output" \
    -H "Authorization: Bearer myaccesstoken"

Sample Response

{
    "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
}

​Report Types

​Report Metrics

​Report Dimensions

​Attributed Transactions Report Dimensions & Metrics

​Endpoints

​Report Request Attributes

​Create a Report Request

​Get Status of a Specific Report

​Download Output of a Specific Report

Report Types

Report Metrics

Report Dimensions

Attributed Transactions Report Dimensions & Metrics

Endpoints

Report Request Attributes

Create a Report Request

Get Status of a Specific Report

Download Output of a Specific Report