Campaign Statistics

Retrieving Statistics for a Specific Advertiser

Our Statistics endpoint allows you to access data related to the performance of your campaigns. You can customize the data by selecting the metrics and dimensions you want to analyze.

To retrieve data, we offer two endpoint options: the synchronous (sync) and asynchronous (async):

• The sync endpoint offers faster response times, but the data accuracy may be slightly lower than the async endpoint.

• The async endpoint provides more accurate data, but response times may vary depending on the complexity of the requested information.

Synchronous Report

You can access the sync statistics report in real-time by using the designated endpoint:

https://api.criteo.com/preview/statistics/report

{
    "advertiserIds": "12345",
    "startDate": "2020-09-10T04:00:00.000Z",
    "endDate": "2020-09-14T04:00:00.000Z",
    "format": "csv",
    "dimensions": ["AdsetId","Day"],
    "metrics": ["Displays","Clicks"],
    "timezone": "PST",
    "currency": "USD"
}

A report is generated via a POST call and the results are returned directly in the response.

AdsetId;Day;Currency;Displays;Clicks
54321;2020/9/10;USD;2534;35
54321;2020/9/11;USD;6234;96
54321;2020/9/12;USD;4357;54
54321;2020/9/13;USD;3245;45
54321;2020/9/14;USD;4584;72

Asynchronous Report

Before retrieving the data asynchronously, you need to submit a report request using the designated endpoint:

https://api.criteo.com/preview/reports/async-statistics

A sample representation of the POST request body is provided below.

{
  "data": {
    "type": "StatisticsReport",
    "attributes": {
      "startDate": "2022-01-01",
      "endDate": "2022-01-02",
      "dimensions": ["CampaignId", "Campaign", "Day"],
      "metrics": ["Clicks", "Displays", "AdvertiserCost"],
      "advertiserIds": ["1111", "2222"],
      "currency": "EUR",
      "timezone": "Europe/Paris",
      "adSetNames": ["myAdSet1", "myAdSet2"],
      "adSetIds": ["789", "456"],
      "adSetStatus": ["Active", "NotRunning"]
    }
  }
}

After submitting a POST call to the designated endpoint, a JSON document will be returned containing the ID and status of the requested report. See the example response below:

{
    "data": {
        "type": "MarketingSolutionsReportStatus",
        "id": "OWVmNDE3OTMtYTZlZC00YjQ4LThiNjUtYjZkOTE1OGViYjIzfEVVUnxFdXJvcGUvUGFyaXM=",
        "attributes": {
            "status": "pending",
            "message": null
        }
    }
}

❗️

Get Output of a Specific Report

After submitting the request, you can follow the Asynchronous Reporting Workflow to obtain the report's output. For detailed instructions on how to perform these steps, please refer to the Async Reports guide.

Report Request Parameters

To make a complete stats request, certain fields are required, but it's important to note that some parameters may only be applicable to one endpoint and cannot be used in the other.

The required fields for a complete stats request are:

🚧

A Note on AdvertiserIds

Advertisers which are not in your portfolio will be skipped. The specified advertisers must have at least one campaign to appear in the report.

If you do not specify any value for advertiserIds, stats for all advertisers in your portfolio will be returned.

Response Codes

The following response codes may be returned by the API:

400: Bad request, invalid syntax or validation error. Review the request to make sure the format is valid.
401: Authentication failed. Ensure the authentication header is formatted properly and your access token hasn't expired.
403: No campaign found. Verify your campaign IDs are correct.
429: Throttling failure. Wait a minute to try again - there is a limit of 200 requests per minute.
500: Unknown error.

Validation Errors

Below is a list of error codes for the Statistics endpoint and a more detailed description of their meaning. General guidance on handling API errors can be found here.

duplicate-dimensions
Duplicate dimension(s) found.


duplicate-metrics
Duplicate metrics(s) found..


insufficient-advertiser-permission
Insufficient advertiser permission.


insufficient-advertisers-permissions
Insufficient advertisers permission.


invalid-country
This feature is currently unavailable in the country of advertiser.


invalid-currency
Invalid currency.


invalid-date-range
The start date can not be after the end date.


invalid-environment
Invalid environment.


invalid-event-type
Invalid Event Type.


invalid-format
Format is not valid. Must be one of 'csv', 'xml', 'excel' or 'json'.


invalid-start-date
The start date is too old.


invalid-timezone
Invalid time zone.


report-generation-failed
A problem occurred while generating the report.


required-field
The required field is missing. Examples:

• A start date and end date are required.
• At least one metric must be provided.
• At least one dimension must be provided.
• Payload is required.
• Currency is required.
• At least one advertiser id must be provided.

 

required-request-body
Request body is required.


unsupported-dimensions
A request is invalid or the server wasn't able to process the request due to a serialization error.


unsupported-dimensions-combination
The requested dimensions combination is not supported.


invalid-metrics
The requested metrics are not supported.

Dimensions

Dimensions allow you to specify the aggregation level suited to your needs.

There are no restrictions on the number of dimensions or the order of dimensions. The full list is below:

The dimensions array of the stats request should contain all requested dimensions.

For example: ['Advertiser','Adset','Day','Hour']

📘

Names vs. IDs

In the dimensions above, Advertiser will return the name of the advertiser, whereas AdvertiserId returns the numerical ID.

Metrics

Naming Convention

Metrics are created with a common structure, such as: SalesAllPc30d

The naming follows the following pattern:
[Measurement][Devices][AttributionModel][LookbackWindow] 

Measurement
What you would like to measure in your report.
Clicks, Displays, AdvertiserCost, etc. (see full metrics list)

Devices
Cross-device sales are sales that occurred on a different device than the one where the click occurred. Specifying All includes cross-device sales.
All

Attribution Model
A sale is attributed when your customer sees or clicks an ad and converts within a specified window of time. It could be post-click, post-view or your custom attribution, if you send us your attribution data for sales.
Pc,Pv, ClientAttribution

🚧

If you are using a newly introduced lookback window (PC1D, PC7D), your request won’t return data prior to January 1st, 2020. The request will deliver a 0 for these metrics.

Lookback Window
The time between a sale and the view or click of an ad.
30D, 7D, 1D, 24H

Full List of Metrics

Metrics refer to measurements such as clicks, revenue, or cost per visit.

All metrics available in Criteo Commerce Growth are available through the Statistics API v2.  

The following is a list of available metrics in Criteo Commerce Growth (bolded) and their corresponding metric names for the metrics array of your request.

📘

A note about percentages

Percentages will be returned as decimal values between 0 and 1. For example, 99.99% will be returned as .9999

Clicks
The number of clicks driven by your ads.
Clicks

Displays
The number of ad impressions served on publishers via Criteo.
Displays

Viewed displays
The number of ads that have been viewed. A display is considered viewed if at least 50% of the ad appears on the screen for at least one second.
ViewableDisplays

Unviewed displays
The number of ads that have not been viewed. A display that doesn't meet the viewed displays' criteria is considered unviewed.
NonViewableDisplays

Untracked displays
This is the number of untracked displays. Some displays cannot be tracked because of the display environment (for instance, native banner)
UntrackableDisplays

Cost
Total money spent on Criteo advertising.
AdvertiserCost

Qualified Visits
The number of users on the target website or app for which at least two events or one sale event occurred within the hour following a click.
QualifiedVisits

Visits
The number of users on the target website or app for which at least one event occurred within the hour following a click.
Visits

Cost per Visit
The amount of money spent per visit to your website or app.
CostPerVisit

Bounce Rate
The proportion of website visitors leaving after only viewing one page.
BounceRate

Potential Displays
The number of display opportunities, or the number of bid requests received.
PotentialDisplays

Win Rate
The number of displays divided by the total number of display opportunities.
OverallCompetitionWin

Sales
The number of transactions or conversions resulting from Criteo ads.
SalesClientAttribution,SalesAllClientAttribution,SalesPc30d,SalesAllPc30d,SalesPv24h,SalesAllPv24h,SalesPc30dPv24h,SalesAllPc30dPv24h,SalesPc1d,SalesAllPc1d,SalesPc7d,SalesAllPc7d

Revenue
The amount of money generated by online sales.
RevenueGeneratedClientAttribution,RevenueGeneratedAllClientAttribution,RevenueGeneratedPc30d,RevenueGeneratedAllPc30d,RevenueGeneratedPv24h,RevenueGeneratedAllPv24h,RevenueGeneratedPc30dPv24h,RevenueGeneratedAllPc30dPv24h,RevenueGeneratedPc1d,RevenueGeneratedAllPc1d,RevenueGeneratedPc7d,RevenueGeneratedAllPc7d

Exposed Users
The number of users who have been served an ad.
ExposedUsers

Audience
Potential users who could be served an ad.
Audience

Reach
Share of potential users who have been served an ad.
Reach

📘

A Note about Audience and Reach with the Category Dimension

The algorithm used for merging audience count across categories is non-commutative (by design).

It is expected that Audience and Reach metrics produce slightly different results when queried with and without the category dimension.

Average Cart
Average revenue generated by a conversion or sale.
AverageCartClientAttribution, AverageCartAllClientAttribution, AverageCartPc30d, AverageCartAllPc30d, AverageCartPv24h, AverageCartAllPv24h, AverageCartPc30dPv24h, AverageCartAllPc30dPv24h, AverageCartPc1d, AverageCartAllPc1d, AverageCartPc7d, AverageCartAllPc7d

CTR (Click Through Rate)
Percentage of users served an ad who clicked.
ClickThroughRate

CVR (Conversion Rate)
Percentage of conversions or sales compared to the clicks that occurred.
ConversionRateClientAttribution,ConversionRateAllClientAttribution,ConversionRatePc30d,ConversionRateAllPc30d,ConversionRatePv24h,ConversionRateAllPv24h,ConversionRatePc30dPv24h,ConversionRateAllPc30dPv24h, ConversionRatePc1d,ConversionRateAllPc1d,ConversionRatePc7d,ConversionRateAllPc7d

COS (Cost of Sale)
Advertising cost per conversion or sale.
ECosClientAttribution,ECosAllClientAttribution,ECosPc30d,ECosAllPc30d,ECosPv24h,ECosAllPv24h,ECosPc30dPv24h,ECosAllPc30dPv24h,ECosPc1d,ECosAllPc1d,ECosPc7d,ECosAllPc7d

CPO (Cost perOrder)
The price you pay for each order. Calculated as total cost divided by the total number of orders.
CostPerOrderClientAttribution,CostPerOrderAllClientAttribution,CostPerOrderPc30d,CostPerOrderAllPc30d,CostPerOrderPv24h,CostPerOrderAllPv24h,CostPerOrderPc30dPv24h,CostPerOrderAllPc30dPv24h,CostPerOrderPc1d,CostPerOrderAllPc1d,CostPerOrderPc7d,CostPerOrderAllPc7d

CPC (Cost per Click)
Cost per click.
Cpc

CPM (Cost per Mille)
Cost per 1000 Impressions.
ECpm

ROAS (Return on Ad Spend)
The ratio between revenue generated and the cost.
RoasClientAttribution,RoasAllClientAttribution,RoasPc30d,RoasAllPc30d,RoasPv24h,RoasAllPv24h,RoasPc30dPv24h,RoasAllPc30dPv24h,RoasPc1d,RoasAllPc1d,RoasPc7d,RoasAllPc7d

Advertiser Value
The revenue generated by each product, considering margin (if provided in your product catalog).
AdvertiserValue,AdvertiserAllValue

COV (Cost of Advertiser Value)
The ratio between the advertiser value generated by sales and the cost of the campaign(s), given as a percentage.
CostOfAdvertiserValue,CostOfAdvertiserValueAll`

Post-Install Sales
The number of your completed events after an app install.
PostInstallSales

App Installs
The number of installations of your app.
AppInstalls

Post-Install CVR (Conversion Rate)
Percentage of post-install sales compared to the clicks that occurred.
PostInstallConversionRate

Post-Install COS (Cost of Sale)
The cost of sale for app install campaigns.
PostInstallCostOfSale

Post-Install Order Value
The amount of money generated by sales after an app install.
PostInstallOrderValue

Cost per Install
The ad cost per app install.
CostPerInstall

Install Rate
The percentage of completed app installs compared to the number of clicks.
InstallRate

Post-Install CPO (Cost per Order)
The cost per order for sales after an app install.
PostInstallCostPerOrder

Post-Install ROAS
The return on ad spend for sales after an app install.
PostInstallRoas

Omnichannel ROAS (Return on Ad Spend)
The ratio between revenue generated online and offline, and the cost.
OmnichannelRoasClientAttribution,OmnichannelRoasPc30d,OmnichannelRoasAllPc30d,OmnichannelRoasPv24h,OmnichannelRoasAllPv24h

Omnichannel Revenue
The revenue generated by online and offline sales.
OmnichannelRevenueClientAttribution,OmnichannelRevenuePc30d,OmnichannelRevenueAllPc30d,OmnichannelRevenuePv24h,OmnichannelRevenueAllPv24h

Omnichannel Sales
The number of online and offline transactions or conversions resulting from Criteo ads.
OmnichannelsalesClientAttribution,OmnichannelSalesPc30d,OmnichannelSalesAllPc30d,OmnichannelSalesPv24h,OmnichannelSalesAllPv24h

Store ROAS
The ratio between the revenue generated offline and the cost.
RoasOfflinePc30d,RoasOfflinePv24h

Store Sales
The number of completed in-store transactions or purchases.
SalesOfflinePc30d,SalesOfflinePv24h

Store Revenue
The amount of revenue generated by in-store sales.
RevenueGeneratedOfflinePc30d,RevenueGeneratedOfflinePv24h

Currencies

Below is a table of all currency codes supported for the currency field of your stats report requests.

Timezones

Below is a table of all timezone values supported for the timezone field of your stats report requests. UTC will be default timezone if not specified.