Skip to main content
The Statistics API measures and reports on campaigns using the metrics and dimensions you specify. Use the playground above to build and send a request; the sections below document the request parameters, dimensions, metrics, supported currencies, and timezones.

​
Example request

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

​
Creating a Report Request

A complete stats request requires the following fields:  
A Note on AdvertiserIdsAdvertisers 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. IDsIn 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 percentagesPercentages 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 DimensionThe 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.