GuidesAPI ReferenceChangelogDiscussions
GuidesAPI ReferenceChangelogLog In
  • 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

📘

New Metrics

  • We intend to introduce new metrics periodically; these new columns will always be appended at the end of table outputs

Report Types

TypeDescription
summary stringDaily metrics aggregated for any single campaign or line item
pageType stringDaily 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 stringDaily 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 stringDaily 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 stringDaily metrics segmented by the product being advertised in the ad creative
attributedTransactions stringHourly 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

MetricDescription
impressionsMeasured 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
impressionsMeasured 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
impressionsMeasured 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
clicksMeasured when an ad creative is clicked on, which incurs a cost to the advertiser for open auction campaigns
spendFor open auctions campaigns, the total cost of clicks for the advertiser; inclusive of platform fees
attributedSalesSales revenue attributed to a click or impression; exclusive of assistedSales
attributedUnitsUnits sold attributed to a click or impression; exclusive of assistedUnits
attributedOrdersOrders (or transactions) attributed to a click or impression
ctrClick-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
cpcCost-per-click (CPC), calculated by dividing spend by clicks; inclusive of platform fees
roasReturn-on-ad-spend (ROAS), calculated by dividing attributedSales by spend; inclusive of platform fees
cpoCost-per-order (CPO), calculated by dividing spend by attributedOrders; inclusive of platform fees
assistedSalesSales 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
assistedUnitsUnits sold attributed to a click or impression on the path to purchase leading to the sale; attributedUnits

Report Types : Line Item reports only
uniqueVisitorsNumber of unique visitors an impression painted for

Report Types : Campaign, Line Item and Summary reports only
frequencyAn 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

DimensionDescription
dateDate based on the requested time zone
campaignIdCampaign ID of the requested report
campaignNameCampaign name of the request report
campaignTypeNameType of campaign configured
lineItemIdLine item ID of the requested report

Report Types : Line Item reports only
lineItemNameLine item name of the requested report

Report Types : Line Item reports only
retailerIdRetailer ID of the retailer the line item served on

Report Types : Line Item reports only
retailerNameRetailer name of the retailer the line item served on

Report Types : Line Item reports only
pageTypeNameType 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
keywordKeyword or phrase used to land on the search page where an ad creative rendered


Report Types : Keyword reports only
advProductCategoryCategory of product advertised; categories are standardized across brands and retailers, which may differ from retailer-specific categories

Report Types : Product & Product Category reports only
advProductIdAdvertised product ID; this references the same ID used in Catalogs

Report Types : Product reports only
advProductNameAdvertised product name

Report Types : Product reports only
brandIdAdvertised product brand ID

Report Types : Product reports only
brandNameAdvertised 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

Column NameColumn TypeDescription
advDateDimensionDate of advertisement
advHourDimensionHour of advertisement
purchasedDateDimensionDate of the attributed product purchase
purchasedHourDimensionHour of the attributed product purchase
daysDifferenceDimensionDays between advertisement and purchase
campaignIdDimensionCampaign ID of the requested report
campaignNameDimensionCampaign name of the request report
lineItemIdDimensionLine item ID of the requested report
lineItemNameDimensionLine item name of the requested report
retailerNameDimensionRetailer name of the retailer the line item served on
pageTypeNameDimensionType of retailer web page an ad creative rendered on, such as home page, browse pages, search pages, product detail pages, checkout pages etc.
keywordDimensionKeyword or phrase used to land on the search page where an ad creative rendered
advProductIdDimensionAdvertised product ID; this references the same ID used in Catalogs
advProductNameDimensionAdvertised product name
advProductCategoryDimensionCategory of product advertised; categories are standardized across brands and retailers, which may differ from retailer-specific categories
advProductGtinDimensionAdvertised product Global Trade Item Number (GTIN), if available; also known as European Article Number (EAN) or Universal Product Code (UPC)
advProductMpnDimensionAdvertised product Manufacturer Part Number (MPN), if available
purchasedProductIdDimensionPurchased product ID; this references the same ID used in Catalogs
purchasedProductNameDimensionPurchased product name
purchasedProductCategoryDimensionCategory of product purchased; categories are standardized across brands and retailers, which may differ from retailer-specific categories
purchasedProductGtinDimensionPurchased product Global Trade Item Number (GTIN), if available; also known as European Article Number (EAN) or Universal Product Code (UPC)
purchasedProductMpnDimensionPurchased product Manufacturer Part Number (MPN), if available
advEngagementDimensionType of ad engagement the purchase was attributed to
advToPurchasedProductRelationshipDimensionAttribution rule used to match the impression or click to a sale
salesChannelDimensionSales channel the attributed purchase was made through
attributionWindowDimensionClick and view attribution window of the requested report
attributedSalesMetricSales revenue attributed to a click or impression
attributedUnitsMetricUnits 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

AttributeDescriptionValuesRequired
id or ids stringCampaign 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: ["CampaignId1","CampaignId2"], (maximum 50 ids per call)
Required
reportType stringType of report requestedsummary, pageType, keyword, productCategory, product, attributedTransactionsR
startDate dateEarliest day to report; inclusiveYYYY-MM-DDR
endDate dateLatest day to report; inclusiveYYYY-MM-DDR
timeZone stringTime zone for the reportdatabase tz syntax, eg. America/New_York, Europe/Paris, UTCR
clickAttributionWindow stringThe 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 is7D, 14D, 30DR
viewAttributionWindow stringThe 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 isnone, 1D, 7D, 14D, 30DR
format stringFormat of the report data returnedjson-compact (default), json-newline, json, csvOptional

📘

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
}

What’s Next