Get Started

Endpoints

Four separate endpoints support requests to create campaign and line item reports and retrieve the report data and status.

Verb	Endpoint	Description
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

id Required

Data Type: string

Description: Campaign or Line Item ID of the desired report

Note: Our reporting endpoints allow for bulk operations Use id when requesting a single Campaign or Line item ID OR use ids when making bulk calls with multiple ids

Accepted Values a single or a group of campaignId or lineItemId e.g id: CampaignId, OR ids: ["CampaignId1","CampaignId2"], (maximum 50 ids per call)

reportType Required

Data Type: string

Description: Type of report requested

Accepted Values summary, pageType, keyword, productCategory, product, attributedTransactions

startDate Required

Data Type: date

Description: Earliest day to report; inclusive

Accepted Values: YYYY-MM-DD

endDate Required

Data Type: date

Description: Latest day to report; inclusive

Accepted Values: YYYY-MM-DD

timeZone Required

Data Type: string

Description: Time zone for the report

Accepted Values: database tz syntax, eg. America/New_York, Europe/Paris, UTC

clickAttributionWindow Required

Data Type: string

Description: 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 one of the accepted values.

Accepted Values: 7D, 14D,30D

viewAttributionWindow Required

Data Type: string

Description: 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 one of the accepted values.

Accepted Values: none, 1D,7D, 14D, 30D

format Optional

Data Type: string

Description: Format of the report data returned

Accepted Values: json-compact (default), json-newline, json, csv

📘
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

Reporting endpoints provide two separate endpoints that allow downloading reports at the campaign or line item level. Each of the following requests can be repeated for each individual report type

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

Sample Request - Campaign Report

curl -X POST "https://api.criteo.com/2022-07/retail-media/reports/campaigns" \
    -H "Authorization: Bearer <MY_ACCESS_TOKEN>" \
    -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"
                }
            }
        }'

import requests
import json

url = "https://api.criteo.com/2022-07/retail-media/reports/campaigns"

payload = json.dumps({
  "data": {
    "type": "RetailMediaReportRequest",
    "attributes": {
      "id": "1285",
      "reportType": "summary",
      "startDate": "2022-06-06",
      "endDate": "2022-07-04",
      "timeZone": "America/New_York"
    }
  }
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer <MY_ACCESS_TOKEN>'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();

MediaType mediaType = MediaType.parse("application/json");

RequestBody body = RequestBody.create(mediaType, "{\n            \"data\": {\n                \"type\": \"RetailMediaReportRequest\",\n                \"attributes\": {\n                    \"id\": \"1285\",\n                    \"reportType\": \"summary\",\n                    \"startDate\": \"2022-06-06\",\n                    \"endDate\": \"2022-07-04\",\n                    \"timeZone\": \"America/New_York\"\n                }\n            }\n        }");

Request request = new Request.Builder()
  .url("https://api.criteo.com/2022-07/retail-media/reports/campaigns")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Bearer <MY_ACCESS_TOKEN>")
  .build();

Response response = client.newCall(request).execute();

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.criteo.com/2022-07/retail-media/reports/campaigns');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer <MY_ACCESS_TOKEN>'
));
$request->setBody('{\n            "data": {\n                "type": "RetailMediaReportRequest",\n                "attributes": {\n                    "id": "1285",\n                    "reportType": "summary",\n                    "startDate": "2022-06-06",\n                    "endDate": "2022-07-04",\n                    "timeZone": "America/New_York"\n                }\n            }\n        }');
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}

https://api.criteo.com/2022-07/retail-media/reports/line-items

Sample Request - Line Item Report

curl -X POST "https://api.criteo.com/2022-07/retail-media/reports/line-items" \
    -H "Authorization: Bearer <MY_ACCESS_TOKEN>" \
    -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"
                }
            }
        }'

import requests
import json

url = "https://api.criteo.com/2022-07/retail-media/reports/line-items"

payload = json.dumps({
  "data": {
    "type": "RetailMediaReportRequest",
    "attributes": {
      "id": "135404148467060736",
      "reportType": "summary",
      "startDate": "2022-04-06",
      "endDate": "2022-06-04",
      "timeZone": "America/New_York"
    }
  }
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer <MY_ACCESS_TOKEN>'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();

MediaType mediaType = MediaType.parse("application/json");

RequestBody body = RequestBody.create(mediaType, "{\n            \"data\": {\n                \"type\": \"RetailMediaReportRequest\",\n                \"attributes\": {\n                    \"id\": \"135404148467060736\",\n                    \"reportType\": \"summary\",\n                    \"startDate\": \"2022-04-06\",\n                    \"endDate\": \"2022-06-04\",\n                    \"timeZone\": \"America/New_York\"\n                }\n            }\n        }");

Request request = new Request.Builder()
  .url("https://api.criteo.com/2022-07/retail-media/reports/line-items")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Bearer <MY_ACCESS_TOKEN>")
  .build();

Response response = client.newCall(request).execute();

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.criteo.com/2022-07/retail-media/reports/line-items');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
  'follow_redirects' => TRUE
));

$request->setHeader(array(
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer <MY_ACCESS_TOKEN>'
));

$request->setBody('{\n            "data": {\n                "type": "RetailMediaReportRequest",\n                "attributes": {\n                    "id": "135404148467060736",\n                    "reportType": "summary",\n                    "startDate": "2022-04-06",\n                    "endDate": "2022-06-04",\n                    "timeZone": "America/New_York"\n                }\n            }\n        }');
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}

catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}

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

https://api.criteo.com/2022-07/retail-media/reports/{reportId}/status

Sample Request

curl -X GET "https://api.criteo.com/2022-07/retail-media/reports/2e733b8c-9983-4237-aab9-17a42f4267cb/status" \
    -H "Authorization: Bearer <MY_ACCESS_TOKEN>"

import requests

url = "https://api.criteo.com/2022-07/retail-media/reports/73fb7859-301f-4371-be91-3e4ad00964aa/status"

payload={}
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer <MY_ACCESS_TOKEN>'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();

MediaType mediaType = MediaType.parse("text/plain");

RequestBody body = RequestBody.create(mediaType, "");

Request request = new Request.Builder()
  .url("https://api.criteo.com/2022-07/retail-media/reports/73fb7859-301f-4371-be91-3e4ad00964aa/status")
  .method("GET", body)
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Bearer <MY_ACCESS_TOKEN>")
  .build();

Response response = client.newCall(request).execute();

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.criteo.com/2022-07/retail-media/reports/73fb7859-301f-4371-be91-3e4ad00964aa/status');
$request->setMethod(HTTP_Request2::METHOD_GET);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Accept' => 'application/json',
  'Authorization' => 'Bearer <MY_ACCESS_TOKEN>'
));
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}

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-07/retail-media/reports/2e733b8c-9983-4237-aab9-17a42f4267cb/status" \
    -H "Authorization: Bearer <MY_ACCESS_TOKEN>"

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-07/retail-media/reports/{reportId}/output

Sample Request

curl -X GET "https://api.criteo.com/2022-07/retail-media/reports/2e733b8c-9983-4237-aab9-17a42f4267cb/output" \
    -H "Authorization: Bearer <MY_ACCESS_TOKEN>"

import requests

url = "https://api.criteo.com/2022-07/retail-media/reports/73fb7859-301f-4371-be91-3e4ad00964aa/output"

payload={}
headers = {
  'Accept': 'application/octet-stream',
  'Authorization': 'Bearer <MY_ACCESS_TOKEN>'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();

MediaType mediaType = MediaType.parse("text/plain");

RequestBody body = RequestBody.create(mediaType, "");

Request request = new Request.Builder()
  .url("https://api.criteo.com/2022-07/retail-media/reports/73fb7859-301f-4371-be91-3e4ad00964aa/output")
  .method("GET", body)
  .addHeader("Accept", "application/octet-stream")
  .addHeader("Authorization", "Bearer <MY_ACCESS_TOKEN>")
  .build();

Response response = client.newCall(request).execute();

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.criteo.com/2022-07/retail-media/reports/73fb7859-301f-4371-be91-3e4ad00964aa/output');
$request->setMethod(HTTP_Request2::METHOD_GET);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Accept' => 'application/octet-stream',
  'Authorization' => 'Bearer <MY_ACCESS_TOKEN>'
));
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}

Sample Response

Campaign Summary Report

// format="json-compact"

// CAMPAING SUMMARY REPORT

{"columns":[ "campaignId", "campaignName", "campaignTypeName", "date", "impressions", "clicks", "attributedOrders", "attributedUnits", "attributedSales", "ctr", "spend", "cpc", "cpo", "roas", "uniqueVisitors", "frequency" ], 

  "data":[ 
            [ "1285", "End of Summer Sale", "Open Auction", "2021-01-31", 0, 0, 1, 1, 76.9400, null, 0.0000, null, 0.0000, null, null, null ] ,
            [ "1285", "End of Summer Sale", "Open Auction", "2021-01-29", 1883, 6, 8, 8, 1749.2600, 0.0032, 3.7000, 0.6167, 0.4625, 472.7730, null, null ] ,
            [ "1285", "End of Summer Sale", "Open Auction", "2021-02-04", 0, 0, 1, 1, 99.4600, null, 0.0000, null, 0.0000, null, null, null ] ,
            [ "1285", "End of Summer Sale", "Open Auction", "2021-01-28", 35087, 107, 25, 25, 4381.2700, 0.0030, 96.3000, 0.9000, 3.8520, 45.4961, null, null ] 
				], 
"rows":4
}

Line Item Summary Report

// format="json-compact"

//LINE ITEM SUMMARY REPORT

{"columns":[ "campaignId", "campaignName", "lineItemId", "lineItemName", "campaignTypeName", "retailerId", "retailerName", "date", "impressions", "clicks", "attributedOrders", "attributedUnits", 
            "attributedSales", "assistedSales", "assistedUnits", "ctr", "spend", "cpc", "cpo", "roas", "uniqueVisitors", "frequency" ], 

"data":[ 
            [ "1285", "End of Summer Sale", "142745910718197760", "Baby Accessories", "Open Auction", 131, "Target", "2021-01-28", 35087, 107, 25, 25, 4381.2700, 0.0000, 0, 0.0030, 96.3000, 0.9000, 3.8520, 45.4961, null, null ] ,
            [ "1285", "End of Summer Sale", "142745910718197760", "Baby Accessories", "Open Auction", 131, "Target", "2021-01-31", 0, 0, 1, 1, 76.9400, 0.0000, 0, null, 0.0000, null, 0.0000, null, null, null ] ,
            [ "1285", "End of Summer Sale", "142745910718197760", "Baby Accessories", "Open Auction", 131, "Target", "2021-02-04", 0, 0, 1, 1, 99.4600, 0.0000, 0, null, 0.0000, null, 0.0000, null, null, null ] ,
            [ "1285", "End of Summer Sale", "142745910718197760", "Baby Accessories", "Open Auction", 131, "Target", "2021-01-29", 1883, 6, 8, 8, 1749.2600, 0.0000, 0, 0.0032, 3.7000, 0.6167, 0.4625, 472.7730, null, null ] 
          ], 
"rows":4
}

Get Started

Endpoints

Report Request Attributes

📘
Reporting Asynchronous Workflow: Step 1 of 3

Create a Report Request

📘
Reporting Asynchronous Workflow: Step 2 of 3

Get Status of a Specific Report

📘
Reporting Asynchronous Workflow: Step 3 of 3

Download Output of a Specific Report

Endpoints

Report Request Attributes

📘Reporting Asynchronous Workflow: Step 1 of 3

Create a Report Request

📘Reporting Asynchronous Workflow: Step 2 of 3

Get Status of a Specific Report

📘Reporting Asynchronous Workflow: Step 3 of 3

Download Output of a Specific Report

📘
Reporting Asynchronous Workflow: Step 1 of 3

📘
Reporting Asynchronous Workflow: Step 2 of 3

📘
Reporting Asynchronous Workflow: Step 3 of 3