> ## Documentation Index
> Fetch the complete documentation index at: https://developers.criteo.com/llms.txt
> Use this file to discover all available pages before exploring further.
# /preview/reports/top-products
> With the topProducts endpoint, you can analyse the performances for each publisher, by top displays, top clicks or top sales.
This endpoint supports data retrieval for up to one year in the past.
## OpenAPI
````yaml https://api.criteo.com/preview/marketingsolutions/open-api-specifications.json post /preview/reports/top-products
openapi: 3.0.1
info:
title: Criteo API
description: Criteo API - MarketingSolutions
version: Preview
servers:
- url: https://api.criteo.com
security:
- oauth: []
tags:
- name: Advertiser
- name: Analytics
- name: Audience
- name: Campaign
- name: Catalog
- name: Creative
- name: Gateway
- name: OnSiteRecommendation
- name: Reco
paths:
/preview/reports/top-products:
post:
tags:
- Analytics
summary: /preview/reports/top-products
description: "With the topProducts endpoint, you can analyse the performances for each publisher, by top displays, top clicks or top sales.\r\n
\r\nThis endpoint supports data retrieval for up to one year in the past."
operationId: GetTopProductsReport
requestBody:
content:
application/json:
schema:
$ref: >-
#/components/schemas/GenerateTopProductsReportRequestAttributesRequest
example:
data:
type: GenerateTopProductsReport
attributes:
timezone: Europe/Paris
startDate: '2024-01-01T00:00:00.0000000+00:00'
endDate: '2024-01-04T00:00:00.0000000+00:00'
advertiserId: '1234'
limit: 200
rankProductsBy: Clicks
dimensions:
- CampaignId
- Campaign
- AdSetId
- AdSet
- ProductId
- Product
- ProductUrl
- Brand
- Category
metrics:
- Clicks
- Ctr
- Visits
- Sales
- Cost
- Revenue
- Displays
currency: EUR
brands:
- Brand1
- Brand2
categoryIds:
- '6666'
- '7777'
campaignIds:
- '9999'
adSetIds:
- '11111'
- '22222'
adSetStatus:
- Active
- NotRunning
application/xml:
schema:
$ref: >-
#/components/schemas/GenerateTopProductsReportRequestAttributesRequest
example: "\r\n \r\n \r\n \r\n 11111\r\n 22222\r\n \r\n \r\n Active\r\n NotRunning\r\n \r\n 1234\r\n \r\n Brand1\r\n Brand2\r\n \r\n \r\n 9999\r\n \r\n \r\n 6666\r\n 7777\r\n \r\n EUR\r\n \r\n CampaignId\r\n Campaign\r\n AdSetId\r\n AdSet\r\n ProductId\r\n Product\r\n ProductUrl\r\n Brand\r\n Category\r\n \r\n 2024-01-04T00:00:00\r\n false\r\n 200\r\n \r\n Clicks\r\n Ctr\r\n Visits\r\n Sales\r\n Cost\r\n Revenue\r\n Displays\r\n \r\n Clicks\r\n 2024-01-01T00:00:00\r\n Europe/Paris\r\n \r\n GenerateTopProductsReport\r\n \r\n"
text/xml:
schema:
$ref: >-
#/components/schemas/GenerateTopProductsReportRequestAttributesRequest
example: "\r\n \r\n \r\n \r\n 11111\r\n 22222\r\n \r\n \r\n Active\r\n NotRunning\r\n \r\n 1234\r\n \r\n Brand1\r\n Brand2\r\n \r\n \r\n 9999\r\n \r\n \r\n 6666\r\n 7777\r\n \r\n EUR\r\n \r\n CampaignId\r\n Campaign\r\n AdSetId\r\n AdSet\r\n ProductId\r\n Product\r\n ProductUrl\r\n Brand\r\n Category\r\n \r\n 2024-01-04T00:00:00\r\n false\r\n 200\r\n \r\n Clicks\r\n Ctr\r\n Visits\r\n Sales\r\n Cost\r\n Revenue\r\n Displays\r\n \r\n Clicks\r\n 2024-01-01T00:00:00\r\n Europe/Paris\r\n \r\n GenerateTopProductsReport\r\n \r\n"
application/*+xml:
schema:
$ref: >-
#/components/schemas/GenerateTopProductsReportRequestAttributesRequest
example: "\r\n \r\n \r\n \r\n 11111\r\n 22222\r\n \r\n \r\n Active\r\n NotRunning\r\n \r\n 1234\r\n \r\n Brand1\r\n Brand2\r\n \r\n \r\n 9999\r\n \r\n \r\n 6666\r\n 7777\r\n \r\n EUR\r\n \r\n CampaignId\r\n Campaign\r\n AdSetId\r\n AdSet\r\n ProductId\r\n Product\r\n ProductUrl\r\n Brand\r\n Category\r\n \r\n 2024-01-04T00:00:00\r\n false\r\n 200\r\n \r\n Clicks\r\n Ctr\r\n Visits\r\n Sales\r\n Cost\r\n Revenue\r\n Displays\r\n \r\n Clicks\r\n 2024-01-01T00:00:00\r\n Europe/Paris\r\n \r\n GenerateTopProductsReport\r\n \r\n"
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/JsonReportRowsListResponse'
application/xml:
schema:
$ref: '#/components/schemas/JsonReportRowsListResponse'
text/xml:
schema:
$ref: '#/components/schemas/JsonReportRowsListResponse'
security:
- oauth:
- MarketingSolutions_Analytics_Read
components:
schemas:
GenerateTopProductsReportRequestAttributesRequest:
type: object
properties:
data:
$ref: >-
#/components/schemas/GenerateTopProductsReportRequestAttributesResource
additionalProperties: false
description: >-
A top-level object that encapsulates a Criteo API request for a single
value object.
JsonReportRowsListResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/JsonReportRowsResource'
nullable: true
errors:
type: array
items:
$ref: '#/components/schemas/CommonProblem'
description: Errors that occured during this call.
nullable: true
readOnly: true
warnings:
type: array
items:
$ref: '#/components/schemas/CommonProblem'
description: Warnings that occured during this call.
nullable: true
readOnly: true
additionalProperties: false
description: >-
A top-level object that encapsulates a Criteo API response for several
value objects.
GenerateTopProductsReportRequestAttributesResource:
type: object
properties:
attributes:
$ref: '#/components/schemas/GenerateTopProductsReportRequestAttributes'
type:
type: string
description: Type of the resource.
nullable: true
additionalProperties: false
description: A value resource exposed by the API.
JsonReportRowsResource:
type: object
properties:
attributes:
$ref: '#/components/schemas/JsonReportRows'
type:
type: string
description: Type of the resource.
nullable: true
additionalProperties: false
description: A value resource exposed by the API.
CommonProblem:
type: object
properties:
code:
type: string
description: A machine-readable error code, expressed as a string value.
nullable: true
detail:
type: string
description: >-
A human-readable explanation specific to this occurrence of the
problem
nullable: true
instance:
type: string
description: A URI that identifies the specific occurrence of the problem.
nullable: true
source:
type: object
additionalProperties:
type: string
description: >-
A machine-readable structure to reference to the exact location(s)
causing the error(s)
nullable: true
stackTrace:
type: string
nullable: true
title:
type: string
description: A short human-readable description of the problem type
nullable: true
traceId:
type: string
description: The request correlation ID this problem comes from.
nullable: true
traceIdentifier:
type: string
description: >-
The request correlation ID this problem comes from. (deprecated, use
traceId instead)
nullable: true
type:
enum:
- unknown
- access-control
- authentication
- authorization
- availability
- deprecation
- quota
- validation
type: string
description: The problem's category.
nullable: true
description: Common problem object.
GenerateTopProductsReportRequestAttributes:
required:
- advertiserId
- currency
- endDate
- rankProductsBy
- startDate
type: object
properties:
adSetIds:
type: array
items:
type: string
description: >-
Optional list of ad set IDs to filter on. The ad sets must already
exist. If empty, all ad sets will be included.
nullable: true
adSetStatus:
type: array
items:
enum:
- Active
- NotRunning
- Dead
type: string
description: >-
Optional list of ad set statuses to filter on. If empty, all ad sets
will be included.
nullable: true
advertiserId:
type: string
description: >-
The advertiser ID to report on. The advertiser must already exist.
At least one advertiser ID should be provided
brands:
type: array
items:
type: string
description: >-
Optional list of brand names to filter on. If empty, all brands will
be included.
nullable: true
campaignIds:
type: array
items:
type: string
description: >-
Optional list of campaign IDs to filter on. The campaigns must
already exist. If empty, all campaigns will be included.
nullable: true
categoryIds:
type: array
items:
type: string
description: >-
Optional list of product catalog category IDs to filter on. If
empty, all categories will be included.
nullable: true
currency:
type: string
description: >-
The currency used for the report. ISO 4217 code (three-letter
capitals).
default: EUR
dimensions:
type: array
items:
enum:
- Campaign
- CampaignId
- AdSet
- AdSetId
- Product
- ProductId
- Category
- CategoryId
- Advertiser
- AdvertiserId
- ProductUrl
- Brand
type: string
description: >-
Optional list of dimensions for the report. If not provided,
defaults to [ProductId, Product, ProductUrl]. When an ID dimension
is requested (e.g., CampaignId), the corresponding name dimension
(e.g., Campaign) is automatically included, and vice versa. This
applies to the following pairs: CampaignId/Campaign, AdSetId/AdSet,
ProductId/Product, CategoryId/Category, AdvertiserId/Advertiser.
nullable: true
endDate:
type: string
description: >-
End date of the report. Date component of ISO 8601 format, any time
or timezone component is ignored.
format: date-time
limit:
maximum: 200
minimum: 1
type: integer
description: >-
Optional maximum number of top products returned. Must be between 1
and 200.
format: int32
default: 200
metrics:
type: array
items:
enum:
- Clicks
- Ctr
- Visits
- Sales
- Cost
- Revenue
- Displays
type: string
description: >-
Optional list of metrics to report. If not provided, defaults to the
metric specified in rankProductsBy.
nullable: true
rankProductsBy:
enum:
- Clicks
- Displays
- Sales
type: string
description: >-
Optional metric used to rank the top products. Allowed values:
'Clicks', 'Displays', 'Sales'.
startDate:
type: string
description: >-
Start date of the report. Date component of ISO 8601 format, any
time or timezone component is ignored. Must be ≤ endDate.
format: date-time
timezone:
type: string
description: >-
Optional timezone used for the report. Timezone Database format
(Tz).
default: UTC
nullable: true
additionalProperties: false
description: This is the message defining the query for TopProducts report
JsonReportRows:
type: object
properties:
rows:
type: array
items:
type: object
additionalProperties:
type: string
nullable: true
additionalProperties: false
description: This is the message defining the json report rows
nullable: true
securitySchemes:
oauth:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://api.criteo.com/oauth2/token
scopes: {}
authorizationCode:
authorizationUrl: https://api.criteo.com/oauth2
tokenUrl: https://api.criteo.com/oauth2/token
scopes: {}
````