GuidesAPI ReferenceChangelog
GuidesAPI ReferenceChangelogLog In



The Criteo API can provide log-level, publisher-oriented information on your ad impressions and clicks in the form of daily reports.

These reports include publisher domains where ads are displayed, timestamps of displayed ads, the price you are paying for each click, and contextual information such as user environment and device.
You can retrieve this information at any time through the Criteo API in the form of reports that can integrate back into your systems. Reports are available for up to 30 days, starting from yesterday.

Below is an example using a basic cURL request:

curl -X POST "{advertiser-id}/report" 
  -H "accept: text/plain"
  -H "Content-Type: application/json-patch+json"
  -H "Authorization: Bearer XXXXX " 
  -d "{ \"startDate\": \"2021-02-03\", \"endDate\": \"2021-02-04\"}"

The call above will return an array of objects containing links to download the reports. The reports will be split out by advertiser and day. No result will be returned if the query pre-dates a 30-day period (starting from yesterday).

Due to the high volume of impression date, this query only supports daily files.

  "data": [
      "type": "TransparencyReport",
      "attributes": {
        "advertiserId": "XXXXX",
        "tokenValidUntil": "2021-02-04T22:42:44.3437476Z",
        "files": [
            "fileName": "2021-02-03_v1.csv.gz",
            "url": "
            "fileName": "2021-02-04_v1.csv.gz",
            "url": "

In the array returned, the report address will be located in the 'stats' section under the 'url' parameter. You will need to retrieve the report from this location to see the data.

There are many ways to retrieve this report but in this example, we will be using curl.

curl -o "saved_report.csv.gz" "#link from the url param#"

Once the report is downloaded, you will need to un-compress it and open it. The downloaded report will not contain column headers; please refer to the documentation below.

Data specification

Column in CSVMetricTypeDescription
ADayStringDay of impression or click event
BHourIntegerHour of impression or click event
CTimestampIntegerTimestamp of impression or click event
DEvent typeStringImpression or click event specification
EAdSet IDIntegerCriteo-assigned numerical AdSet identifier
FAdSet nameStringName of AdSet as seen in Commerce Growth
GAd formatStringFormat of display (i.e. 'mozaic' is a dynamic banner)
HBanner IDIntegerCriteo-assigned numerical banner identifier
ICategory IDIntegerIdentifier of product category in the catalog
JCategory nameStringName of product category in the catalog
KReferrerStringPublisher domain on which ad was served
LEnvironmentStringBrowsing medium (web or app)
MDevice familyStringDevice specification of user agent
NOS familyStringOperating system specification of user agent
OApp IDStringIdentifier of app
PApp nameStringSpecification of app
QViewabilityStringIndicates if display was viewable for at least 50% of a continuous second

-1 = impression was untracked; no insight into if it was viewed
0 = impression was tracked, but not viewable
1 = impression was tracked, and was viewable
RDisplay cost currencyStringCurrency of the impression display cost
SDisplay costDoubleImpression display cost in local currency
TDisplay cost (USD)DoubleImpression display cost in USD currency
UClick cost currencyStringCurrency of the click cost
VClick costDoubleCost per click in local currency
WClick cost (USD)DoubleCost per click in USD currency

When reading over the report, there are a few things to note. They are listed below in a table for easy reference.

How do I differentiate my AdSets from one another?If you have multiple AdSets under a given advertiser, they will be identified uniquely in the reports by the AdSet ID field. You can also reference the AdSet field.
Why does the referrer field contain "null" or "unknown"?Due to legal and technical limitations, we might not receive the exact publishers' domain information (also known as blind traffic). These instances are tracked as “null” under the “referrer” field in the Log-level reports. This is a general behavior in the industry and it is common to have around 10% of traffic that falls under this definition.
Why am I seeing a lot of and inApp displays will report as or depending on the operating system the user has. = iOS = Android
Why am I seeing users from different countries included in these reports?User targeting is derived from continental data base location. Every AdSet has an account ID that is linked to a specific data base. Unless there is a country-specific geofilter applied on the AdSet, it technically can target any user in that geographical region.

For example, an AdSet linked to one of our Americas data centers could target a user in any North or South American country unless it has a country-specific geofilter applied.
Why am I seeing values of 0 in the category_ID field? And "unknown" in the category_name field?If your Criteo product catalog does not have category IDs mapped to specific product IDs, this will display a value of 0. Likewise, this is why "unknown" appears in the category_name field.
Why do have sometimes cost related to clicks, and some other times cost related to display?If the AdSet is using an adaptive optimizer or a target budget mechanism, it will show a click cost of 0 because we are billing displays, not clicks. If you’re using a standard click-billed AdSet, you will see a click cost unless smoothing is activated.

Example of parsing

The CSV file is produced with no quotes, Newline as a line terminator, backslash as an escape character, and comma as a separator. Please see below an example of parsing.

import csv
csv.register_dialect('crto', delimiter=',' ,quoting=csv.QUOTE_NONE,escapechar='\\',lineterminator = '\n')
with open('test_om.csv', newline='') as csvfile:
       spamreader = csv.reader(csvfile, dialect='crto')
       for row in spamreader:
             print('rowcount ', len(row))
             print(', '.join(row))

If you notice any issues don't hesitate to reach out through the Discussion section or your dedicated account representative.