Discard
GuidesAPI ReferenceChangelogDiscussions
GuidesAPI ReferenceChangelogDiscussionsLog 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
  • 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

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

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 over time
  • Learn more about our attribution rules

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

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

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: ["CampaignId1","CampaignId2"], (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

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
Did this page help you?