Retail Media Insights (Share of Voice)

Introduction

Retail Media Insights exposes performance dashboards available on the Demand Side of Commerce Max.

The Share of Voice by Category API is an asynchronous reporting endpoint reflecting the Share of Voice by Category dashboard available in Retail Media Insights. It allows Demand Side users to retrieve impression and click share metrics at a served category level.

This API is designed for:

Demand Side users accessing through a Commerce Max Network account
Demand Side users accessing through a Commerce Yield Private Market account

The primary purpose of this endpoint is to fetch impression and click share metrics across categories where ads were served on retailer sites.

📘
Asynchronous Reports
This endpoint initiates an asynchronous export. The response returns a report ID that must be used to:

Check report generation status

Download the generated report once ready

Endpoints

Verb	Endpoint	Description
POST	`/retail-media/insights/share-of-voice-by-category`	Initiates a Share of Voice by Category report export
GET	`/retail-media/insights/{reportId}/status`	Retrieves the status of a report
GET	`/retail-media/insights/{reportId}/output`	Downloads the generated report

Dimensions

Dimensions define how the report data is grouped.

Dimension	Type	Description
`date`	date	The date of when events occurred for the requested line-item or campaign report. If there are no results to show for the requested dates, the API will return no results. Note: Dates are reflected based on the API call requested time zone. Dates are also reported at either the campaign level or line-item level.
`accountId`	int	Account ID of the requested report
`accountName`	string	The supply or demand account name
`retailerId`	int	Retailer ID of the retailer of the line item served on
`retailerName`	string	Retailer name of the retailer the line item served on
`brandId`	int	Advertised product brand ID
`brandName`	string	Advertised product brand name. Names are standardized across retailers
`campaignId`	int	Campaign ID of the requested report
`campaignName`	string	Campaign name of the requested report
`buyType`	string	The Buy type
`skuId`	string	The SKU identifier
`skuName`	string	The Product name
`lineItemId`	int	Line item ID of the requested report
`lineItemName`	string	Line item name of the requested report.
`pageTypeId`	int	The Identifier of the page type where the ad was served
`pageTypeName`	string	Type of retailer web page an ad creative rendered on. Current page types include: `home` `search` `category` `productDetail` `merchandising` `deals` `checkout` `confirmation`
`productGtin`	string	The Global Trade Item Number
`productMpn`	string	The Manufacturer Part Number
`productCategory`	string	The Product category
`servedCategory`	string	The Served category
`campaignType`	string	The type of campaign. Available options are `Open Auction` or `Preferred Deals`
`creativeType`	string	The Creative type
`adFormat`	string	The Ad format
`creativeName`	string	The Creative name
`environment`	string	Type of environment an ad creative rendered on, such as `web`, `mobile` and `app`

Metrics

At least one metric must be selected.

Metric	Type	Description
`impressions`	int	Campaign Report Types Measured when an ad creative renders on a page; an ad creative may display products from one or more campaigns; each unique campaign is counted once; used in all report types except for Product and Product Category reports Line-Item Report Types Measured when an ad creative renders on a page; an ad creative may display products from one or more line items; each unique line item is counted once; used in all report types except for Product and Product Category reports Product, Product Category and Served Category Report Types Measured when a promoted product is rendered on the page, whether as a single ad creative or as one of many products in an ad creative; each product is counted once separately More Info: Product & Placement Impression Help Center article
`clicks`	int	Measured when an ad creative is clicked on, which incurs a cost to the advertiser for open auction campaigns
`grossClicks`	int	Clicks including suspected invalid traffic
`invalidClicks`	int	Invalid clicks
`totalSpend`	float	Total spend
`cpc`	float	The average cost you are paying per click. Available for On-site Sponsored Products campaigns only. Value is inclusive of platform fees. Formula: `spend` / `clicks`
`ctr`	float	The percentage of shoppers who clicked an ad rendered on a page. Product and Product Category Report Types Formula: `clicks` / `productImpressions` All other report types Formula: `clicks` / `placementImpressions` Note: there are two types of impressions that can be measured to know the success of your ads: `placementImpressions` and `productImpressions`. Preferred deals have placement impressions, while open auction uses product impressions. More info: Product & Placement Impression Help Center article
`cpm`	float	Calculated as the total cost of impressions served divided by the total number of impressions.
`roas`	float	A measurement of the revenue you will receive for every unit of currency you spend on ads. ROAS can vary based on your attribution settings. This metric is inclusive of platform fees. Formula: `attributedSales` / `spend`
`attributedSales`	float	A sale that was a direct result of your marketing campaign (in accordance with your attribution rules). Also, a measure of the conversions of your campaign. Formula: Sum of all Sales Important: Sales are de-duplicated between off-site and on-site, however the Criteo API will report on on-site campaigns only. A sale can only be attributed to one line item across all campaigns.
`attributedUnits`	int	Units sold attributed to a click or impression. Attributed units are exclusive of.`assistedUnits` meaning assisted units are not counted in the attribution. Example: If a shopper purchases one order of two products, the number of Attributed Units is 2.
`assistedUnits`	int	The number of events that occurred that helped to generate a sale. Assisted units are excluded from `attributedUnits`. This means it's not counted in the attributed units' calculation.
`assistedSales`	float	Sales revenue attributed to a click or impression of all the ads that appeared on a page within the chosen attribution window (specified at the campaign level) but were not determined to be the `attributedSales` (the last ad before the customer purchased). More Info: Demand Side Metrics Help Center article
`exposedUsers`	int	Exposed users
`shareOfVoiceImpressions`	float	Share of impressions
`shareOfVoiceClicks`	float	Share of clicks

Report Formats

`json-compact`

This is a column-based compact JSON format.

{
    "columns":[dimension_1, ..., metric_1, ...],
    "data":[row1, row2, ...],
    "rows":100
}

`json-newline`

This is a newline-delimited JSON format.

{"id":"1234","name":"Fred Flintstone","age":34}
{"id":"2345","name":"Wilma Flintstone","age":32}
{"id":"3456","name":"Barney Rubble","age":33}
{"id":"4567","name":"Betty Rubble","age":31}

`json`

This is standard JSON format.

[
 {"id":"1234","name":"Fred Flintstone","age":34},
 {"id":"2345","name":"Wilma Flintstone","age":32},
 {"id":"3456","name":"Barney Rubble","age":33},
 {"id":"4567","name":"Betty Rubble","age":31}
]

`csv`

This is the standard CSV format.

"col1","col2",...,"colN"
val_11,val_12,...,val_1N
....
val_M1,val_M2,...,val_MN

Share of Voice by Category Report

https://api.criteo.com/{version}/retail-media/insights/share-of-voice-by-category

Attributes

Field	Required	Type	Description
`accountId`	Yes	String	Filter by account ID
`startDate`	Yes	String	Start date (YYYY-MM-DD)
`endDate`	Yes	String	End date (YYYY-MM-DD)
`campaignType`	No	`CampaignFilterType`	all, `onsiteSponsoredProducts`, `onsiteDisplay`
`dimensions`	Yes	Dimension[]	Dimensions to report on
`metrics`	Yes	Metric[]	Metrics to report on
`brandIds`	No	String[]	Filter by brand IDs
`retailerIds`	No	String[]	Filter by retailer IDs
`servedCategories`	No	ServedCategoryFilter[]	Categories grouped by retailer
`format`	No	Format	Output format

📘
Field Definitions

Writeable (Y/N): Indicates if the field can be modified in requests.

Nullable (Y/N): Indicates if the field can accept null/empty values.

Primary Key: A unique, immutable identifier of the entity, generated internally by Criteo. Primary keys are typically ID fields (e.g., retailerId, campaignId, lineItemId) and are usually required in the URL path.

Sample Request

{
  "data": {
    "type": "RetailMediaShareOfVoiceByCategory",
    "attributes": {
      "accountId": "123",
      "dimensions": ["Date", "CampaignName", "RetailerId", "ServedCategory"],
      "metrics": ["Impressions"],
      "startDate": "2025-08-01",
      "endDate": "2025-08-11",
      "format": "json-compact"
    }
  }
}

Sample Response

The request initiated an asynchronous export of the report.

{
  "data": {
    "id": "aa9e0816-2484-4605-b540-f62e1387af61",
    "type": "StatusResponse",
    "attributes": {
      "status": "pending",
      "createdAt": "2025-08-11T09:18:33.275Z"
    }
  }
}

📘
The report can be then be retrieved using:

/retail-media/insights/{reportId}/output

/retail-media/insights/{reportId}/status

Errors & Warnings

This endpoint may return validation or access-control errors.
All errors follow a consistent JSON error object structure.

403: Insufficient Account Permissions

The requester does not have permission to access one or more of the specified advertiser accounts.

📘
This validation is handled by the API gateway.

HTTP Status Code: 403 Forbidden

{
  "errors": [
    {
      "traceIdentifier": "9353e1711d738a7a",
      "type": "access-control",
      "code": "insufficient-account-permissions",
      "instance": "insights/share-of-voice-by-category",
      "title": "Insufficient account permissions",
      "detail": "You do not have the rights to report on these accounts."
    }
  ]
}

400: Missing Required Field

One or more required fields are missing from the request payload.

HTTP Status Code: 400 Bad Request

{
  "errors": [
    {
      "traceIdentifier": "9353e1711d738a7a",
      "type": "validation",
      "code": "required-field",
      "instance": "/insights/share-of-voice-by-category",
      "title": "Missing required field",
      "detail": "Missing fields: <field name(s)>"
    }
  ]
}

400: Invalid Date Range

The provided date range is invalid. The start date must not be later than the end date.

HTTP Status Code: 400 Bad Request

{
  "errors": [
    {
      "traceIdentifier": "9353e1711d738a7a",
      "type": "validation",
      "code": "invalid-date-range",
      "instance": "/insights/share-of-voice-by-category",
      "title": "Invalid date range",
      "detail": "The 'startDate' can not be after 'endDate'."
    }
  ]
}

400: Missing Metrics

No metrics were provided in the request. At least one metric is required to generate a report.

HTTP Status Code: 400 Bad Request

{
  "errors": [
    {
      "traceIdentifier": "9353e1711d738a7a",
      "type": "validation",
      "code": "missing-dimensions",
      "instance": "/insights/share-of-voice-by-category",
      "title": "Missing metrics",
      "detail": "At least one metric must be provided."
    }
  ]
}