> ## 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/retail-media/insights/share-of-voice

> Requests a Share of Voice insight report. This is an asynchronous, non-transactional operation:
it does not return the analytic data. It enqueues an export job and returns the created insight
report, whose id is then used to poll the insight status endpoint until the report is ready and to
download the result from the insight output endpoint.



## OpenAPI

````yaml https://api.criteo.com/preview/retailmedia/open-api-specifications.json post /preview/retail-media/insights/share-of-voice
openapi: 3.0.1
info:
  title: Criteo API
  description: Criteo API - RetailMedia
  version: Preview
servers:
  - url: https://api.criteo.com
security:
  - oauth: []
tags:
  - name: Accounts
  - name: Analytics
  - name: Audience
  - name: Balance
  - name: Campaign
  - name: Catalog
  - name: Gateway
  - name: OnSiteRecommendation
  - name: ThirdPartyAccounts
paths:
  /preview/retail-media/insights/share-of-voice:
    post:
      tags:
        - Analytics
      summary: /preview/retail-media/insights/share-of-voice
      description: "Requests a Share of Voice insight report. This is an asynchronous, non-transactional operation:\r\nit does not return the analytic data. It enqueues an export job and returns the created insight\r\nreport, whose id is then used to poll the insight status endpoint until the report is ready and to\r\ndownload the result from the insight output endpoint."
      operationId: GenerateShareOfVoiceInsight
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShareOfVoiceInsightRequest'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncInsightResponse'
      security:
        - oauth:
            - RetailMedia_Analytics_Read
components:
  schemas:
    ShareOfVoiceInsightRequest:
      required:
        - data
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ShareOfVoiceInsightResource'
      additionalProperties: false
      description: >-
        A top-level object that encapsulates a Criteo API request for a single
        value object.
      example:
        data:
          type: ShareOfVoiceInsight
          attributes:
            startDate: '2026-06-01T00:00:00.0000000+00:00'
            endDate: '2026-06-07T00:00:00.0000000+00:00'
            aggregationLevel: category
            dimensions:
              - date
              - accountId
              - accountName
              - retailerId
              - retailerName
              - brandId
              - brandName
              - campaignId
              - campaignName
              - buyType
              - skuId
              - skuName
              - lineItemId
              - lineItemName
              - pageTypeId
              - pageTypeName
              - productGtin
              - productMpn
              - productCategory
              - servedCategory
              - keyword
              - keywordType
              - campaignType
              - creativeType
              - adFormat
              - creativeName
              - environment
              - budgetModel
              - activationPlatform
            metrics:
              - impressions
              - clicks
              - grossClicks
              - spend
              - cpc
              - ctr
              - cpm
              - roas
              - attributedSales
              - attributedUnits
              - assistedUnits
              - assistedSales
              - exposedUsers
              - impressionShare
              - clickShare
              - invalidClicks
            filters:
              campaignType: onsiteSponsoredProducts
              accountIds:
                - '12345'
              retailerIds:
                - '123'
              brandIds:
                - '456'
              servedCategories:
                - Sports & Outdoors/Footwear/Running Shoes
              keywords:
                - running shoes
              keywordTypes:
                - generic
              budgetModels:
                - criteoBudget
              activationPlatforms:
                - commerceMax
            accountId: '12345'
            format: json-compact
    AsyncInsightResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/InsightStatusResponseResource'
        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: >-
        Response returned by the asynchronous insight endpoints, carrying the
        insight report status.
      example:
        data:
          id: 12345678-90ab-cdef-1234-567890abcdef
          type: InsightStatus
          attributes:
            status: Success
            message: rows_count=1234
            createdAt: '2026-07-01T12:00:00.0000000+00:00'
            expiresAt: '2026-07-08T12:00:00.0000000+00:00'
            rowCount: 1234
            md5CheckSum: 0123456789abcdef0123456789abcdef
            fileSizeBytes: 154321
        warnings: []
        errors: []
    ShareOfVoiceInsightResource:
      required:
        - attributes
      type: object
      properties:
        attributes:
          $ref: '#/components/schemas/ShareOfVoiceInsight'
        type:
          type: string
          description: Type of the resource.
          nullable: true
      additionalProperties: false
      description: A value resource exposed by the API.
    InsightStatusResponseResource:
      type: object
      properties:
        attributes:
          $ref: '#/components/schemas/InsightStatusResponse'
        id:
          type: string
          description: Unique id of the entity.
          nullable: true
        type:
          type: string
          description: Type of the resource.
          nullable: true
      additionalProperties: false
      description: A domain entity exposed by the API, identified by a unique id.
      nullable: true
    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.
    ShareOfVoiceInsight:
      required:
        - accountId
        - dimensions
        - endDate
        - metrics
        - startDate
      type: object
      properties:
        accountId:
          type: string
          description: Account ID the insight report is generated for.
        aggregationLevel:
          enum:
            - category
            - keyword
          type: string
          description: >-
            Aggregation level of the report. Allowed values: `category`,
            `keyword`. Defaults to `category`.
          default: category
        dimensions:
          minItems: 1
          type: array
          items:
            enum:
              - date
              - accountId
              - accountName
              - retailerId
              - retailerName
              - brandId
              - brandName
              - campaignId
              - campaignName
              - buyType
              - skuId
              - skuName
              - lineItemId
              - lineItemName
              - pageTypeId
              - pageTypeName
              - productGtin
              - productMpn
              - productCategory
              - servedCategory
              - keyword
              - keywordType
              - campaignType
              - creativeType
              - adFormat
              - creativeName
              - environment
              - budgetModel
              - activationPlatform
            type: string
            description: Dimension by which Share of Voice results can be broken down.
          description: Dimensions to report on.
        endDate:
          type: string
          description: End date of the report, in ISO 8601 format (YYYY-MM-DD).
        filters:
          $ref: '#/components/schemas/ShareOfVoiceFilters'
        format:
          enum:
            - json
            - json-compact
            - json-newline
            - csv
          type: string
          description: >-
            Output format of the report. Allowed values: `json`, `json-compact`,
            `json-newline`, `csv`. Defaults to `json-compact`.
          default: json-compact
        metrics:
          minItems: 1
          type: array
          items:
            enum:
              - impressions
              - clicks
              - grossClicks
              - spend
              - cpc
              - ctr
              - cpm
              - roas
              - attributedSales
              - attributedUnits
              - assistedUnits
              - assistedSales
              - exposedUsers
              - impressionShare
              - clickShare
              - invalidClicks
            type: string
            description: Metric available in a Share of Voice insight.
          description: Metrics to report on.
        startDate:
          type: string
          description: Start date of the report, in ISO 8601 format (YYYY-MM-DD).
      additionalProperties: false
      description: Parameters of a Share of Voice insight.
      example:
        startDate: '2026-06-01'
        endDate: '2026-06-07'
        aggregationLevel: category
        dimensions:
          - date
          - accountId
          - accountName
          - retailerId
          - retailerName
          - brandId
          - brandName
          - campaignId
          - campaignName
          - buyType
          - skuId
          - skuName
          - lineItemId
          - lineItemName
          - pageTypeId
          - pageTypeName
          - productGtin
          - productMpn
          - productCategory
          - servedCategory
          - keyword
          - keywordType
          - campaignType
          - creativeType
          - adFormat
          - creativeName
          - environment
          - budgetModel
          - activationPlatform
        metrics:
          - impressions
          - clicks
          - grossClicks
          - spend
          - cpc
          - ctr
          - cpm
          - roas
          - attributedSales
          - attributedUnits
          - assistedUnits
          - assistedSales
          - exposedUsers
          - impressionShare
          - clickShare
          - invalidClicks
        filters:
          campaignType: onsiteSponsoredProducts
          accountIds:
            - '12345'
          retailerIds:
            - '123'
          brandIds:
            - '456'
          servedCategories:
            - Sports & Outdoors/Footwear/Running Shoes
          keywords:
            - running shoes
          keywordTypes:
            - generic
          budgetModels:
            - criteoBudget
          activationPlatforms:
            - commerceMax
        accountId: '12345'
        format: json-compact
    InsightStatusResponse:
      type: object
      properties:
        createdAt:
          type: string
          description: When the insight report was created.
          nullable: true
        expiresAt:
          type: string
          description: When the insight report expires and can no longer be downloaded.
          nullable: true
        fileSizeBytes:
          type: integer
          description: Size of the generated report file in bytes, when available.
          format: int64
          nullable: true
        md5CheckSum:
          type: string
          description: MD5 checksum of the generated report file, when available.
          nullable: true
        message:
          type: string
          description: Additional information about the report status, when available.
          nullable: true
        rowCount:
          type: integer
          description: Number of rows in the generated report, when available.
          format: int32
          nullable: true
        status:
          enum:
            - Unknown
            - Pending
            - Success
            - Failure
            - Expired
            - Invalidated
          type: string
          description: Current status of the insight report.
          nullable: true
      additionalProperties: false
      description: Status of an asynchronous insight report request.
      nullable: true
      example:
        status: Success
        message: rows_count=1234
        createdAt: '2026-07-01T12:00:00Z'
        expiresAt: '2026-07-08T12:00:00Z'
        rowCount: 1234
        md5CheckSum: 0123456789abcdef0123456789abcdef
        fileSizeBytes: 154321
    ShareOfVoiceFilters:
      type: object
      properties:
        accountIds:
          type: array
          items:
            type: string
          description: Accounts to filter on.
          nullable: true
        activationPlatforms:
          type: array
          items:
            enum:
              - commerceMax
              - privateMarket
            type: string
            description: Platform on which a campaign is activated.
          description: >-
            Activation platforms to filter on. Allowed values: `commerceMax`,
            `privateMarket`.
          nullable: true
        brandIds:
          type: array
          items:
            type: string
          description: Brands to filter on.
          nullable: true
        budgetModels:
          type: array
          items:
            enum:
              - criteoBudget
              - retailerBudget
            type: string
            description: Budget model funding a campaign.
          description: >-
            Budget models to filter on. Allowed values: `criteoBudget`,
            `retailerBudget`.
          nullable: true
        campaignType:
          enum:
            - all
            - onsiteSponsoredProducts
            - onsiteDisplay
          type: string
          description: >-
            Campaign type to filter on. Allowed values: `all`,
            `onsiteSponsoredProducts`, `onsiteDisplay`. Defaults to `all`.
          default: all
        keywords:
          type: array
          items:
            type: string
          description: Keywords to filter on.
          nullable: true
        keywordTypes:
          type: array
          items:
            enum:
              - unknown
              - generic
              - branded
              - conquesting
            type: string
            description: Type of keyword targeted in a campaign.
          description: >-
            Keyword types to filter on. Allowed values: `unknown`, `generic`,
            `branded`, `conquesting`.
          nullable: true
        retailerIds:
          type: array
          items:
            type: string
          description: Retailers to filter on.
          nullable: true
        servedCategories:
          type: array
          items:
            type: string
          description: Retailer-specific category taxonomy values to filter on.
          nullable: true
      additionalProperties: false
      description: Filters for a Share of Voice insight.
  securitySchemes:
    oauth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.criteo.com/oauth2/token
          scopes:
            RetailMedia_Accounts_Read: >-
              Grants Read access to the capabilities from the Accounts domain,
              for RetailMedia applications
            RetailMedia_Analytics_Read: >-
              Grants Read access to the capabilities from the Analytics domain,
              for RetailMedia applications
            RetailMedia_Audience_Manage: >-
              Grants Manage access to the capabilities from the Audience domain,
              for RetailMedia applications
            RetailMedia_Audience_Read: >-
              Grants Read access to the capabilities from the Audience domain,
              for RetailMedia applications
            RetailMedia_Balance_Manage: >-
              Grants Manage access to the capabilities from the Balance domain,
              for RetailMedia applications
            RetailMedia_Balance_Read: >-
              Grants Read access to the capabilities from the Balance domain,
              for RetailMedia applications
            RetailMedia_Campaign_Manage: >-
              Grants Manage access to the capabilities from the Campaign domain,
              for RetailMedia applications
            RetailMedia_Campaign_Read: >-
              Grants Read access to the capabilities from the Campaign domain,
              for RetailMedia applications
            RetailMedia_Catalog_Manage: >-
              Grants Manage access to the capabilities from the Catalog domain,
              for RetailMedia applications
            RetailMedia_Catalog_Read: >-
              Grants Read access to the capabilities from the Catalog domain,
              for RetailMedia applications
            RetailMedia_OnSiteRecommendation_Read: >-
              Grants Read access to the capabilities from the
              OnSiteRecommendation domain, for RetailMedia applications
            RetailMedia_ThirdPartyAccounts_Manage: >-
              Grants Manage access to the capabilities from the
              ThirdPartyAccounts domain, for RetailMedia applications
        authorizationCode:
          authorizationUrl: https://api.criteo.com/oauth2
          tokenUrl: https://api.criteo.com/oauth2/token
          scopes:
            RetailMedia_Accounts_Read: >-
              Grants Read access to the capabilities from the Accounts domain,
              for RetailMedia applications
            RetailMedia_Analytics_Read: >-
              Grants Read access to the capabilities from the Analytics domain,
              for RetailMedia applications
            RetailMedia_Audience_Manage: >-
              Grants Manage access to the capabilities from the Audience domain,
              for RetailMedia applications
            RetailMedia_Audience_Read: >-
              Grants Read access to the capabilities from the Audience domain,
              for RetailMedia applications
            RetailMedia_Balance_Manage: >-
              Grants Manage access to the capabilities from the Balance domain,
              for RetailMedia applications
            RetailMedia_Balance_Read: >-
              Grants Read access to the capabilities from the Balance domain,
              for RetailMedia applications
            RetailMedia_Campaign_Manage: >-
              Grants Manage access to the capabilities from the Campaign domain,
              for RetailMedia applications
            RetailMedia_Campaign_Read: >-
              Grants Read access to the capabilities from the Campaign domain,
              for RetailMedia applications
            RetailMedia_Catalog_Manage: >-
              Grants Manage access to the capabilities from the Catalog domain,
              for RetailMedia applications
            RetailMedia_Catalog_Read: >-
              Grants Read access to the capabilities from the Catalog domain,
              for RetailMedia applications
            RetailMedia_OnSiteRecommendation_Read: >-
              Grants Read access to the capabilities from the
              OnSiteRecommendation domain, for RetailMedia applications
            RetailMedia_ThirdPartyAccounts_Manage: >-
              Grants Manage access to the capabilities from the
              ThirdPartyAccounts domain, for RetailMedia applications

````