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

• 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

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

Report Dimensions

• Available dimensions vary by report type

• The Attributed Transactions report is documented separately below

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

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

📘

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
}