> ## 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.
# /2027-01/marketing-solutions/statistics-adlevel/report
> Generates a synchronous ad-level report (currently OpenAI campaigns only, with Open Web planned) returned directly in the response as JSON or CSV — no job creation, polling, or separate download step.
Breakdown dimensions and metrics must both be explicitly requested — nothing is added to the response just because a dimension was requested. Requesting AdGroupName, ProductId, or AdId as a breakdown requires the query to already be scoped to specific ad set(s), either via a non-empty adsetIds filter or by also including AdsetId in dimensions. Some metrics also require their own matching breakdown dimension to be requested — see the endpoint description for the full compatibility table. Results are capped at 100,000 rows; beyond that the response is truncated and a row-limit-exceeded warning is included.
## OpenAPI
````yaml https://api.criteo.com/2027-01/marketingsolutions/open-api-specifications.json post /2027-01/marketing-solutions/statistics-adlevel/report
openapi: 3.0.1
info:
title: Criteo API
description: Criteo API - MarketingSolutions
version: 2027-01
servers:
- url: https://api.criteo.com
security:
- oauth: []
tags:
- name: Advertiser
- name: Analytics
- name: Audience
- name: Campaign
- name: Creative
- name: Gateway
- name: Reco
paths:
/2027-01/marketing-solutions/statistics-adlevel/report:
post:
tags:
- Analytics
summary: /2027-01/marketing-solutions/statistics-adlevel/report
description: "Generates a synchronous ad-level report (currently OpenAI campaigns only, with Open Web planned) returned directly in the response as JSON or CSV — no job creation, polling, or separate download step.\r\n
\r\nBreakdown dimensions and metrics must both be explicitly requested — nothing is added to the response just because a dimension was requested. Requesting AdGroupName, ProductId, or AdId as a breakdown requires the query to already be scoped to specific ad set(s), either via a non-empty adsetIds filter or by also including AdsetId in dimensions. Some metrics also require their own matching breakdown dimension to be requested — see the endpoint description for the full compatibility table. Results are capped at 100,000 rows; beyond that the response is truncated and a row-limit-exceeded warning is included."
operationId: GetAdLevelReport
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdLevelReportRequestAttributesRequest'
example:
data:
type: AdLevelReportQuery
attributes:
startDate: '2026-06-01T00:00:00.0000000+00:00'
endDate: '2026-06-30T00:00:00.0000000+00:00'
advertiserIds:
- '123456'
adsetIds:
- '987654'
dimensions:
- AdsetId
- AdsetName
- AdGroupName
metrics:
- Impressions
- Clicks
- Ctr
- Spend
timezone: UTC
format: json
responses:
'200':
description: Success
content:
application/json:
schema:
type: string
format: binary
text/csv:
schema:
type: string
format: binary
security:
- oauth:
- MarketingSolutions_Analytics_Read
components:
schemas:
AdLevelReportRequestAttributesRequest:
type: object
properties:
data:
$ref: '#/components/schemas/AdLevelReportRequestAttributesResource'
additionalProperties: false
description: >-
A top-level object that encapsulates a Criteo API request for a single
value object.
AdLevelReportRequestAttributesResource:
type: object
properties:
attributes:
$ref: '#/components/schemas/AdLevelReportRequestAttributes'
type:
type: string
description: Must be the literal value 'AdLevelReportQuery'.
nullable: true
additionalProperties: false
description: A value resource exposed by the API.
AdLevelReportRequestAttributes:
required:
- advertiserIds
- dimensions
- metrics
- startDate
- endDate
type: object
properties:
adsetIds:
type: array
items:
type: string
description: >-
Optional filter on ad set IDs. Also satisfies the ad-set-scope
requirement for the AdGroupName, ProductId, and AdId breakdown
dimensions: if any of those are requested, either adsetIds must be
non-empty or AdsetId must also be included in dimensions.
nullable: true
advertiserIds:
maxItems: 5
minItems: 1
type: array
items:
type: string
description: >-
List of advertiser IDs to report on. Between 1 and 5 advertiser IDs
can be provided.
dimensions:
minItems: 1
type: array
items:
enum:
- AdvertiserId
- AdvertiserName
- AdsetId
- AdsetName
- MediaChannel
- Platform
- AdGroupName
- ProductId
- AdId
type: string
description: >-
List of breakdown dimensions for the report. At least one dimension
must be provided; nothing is added to the response unless explicitly
requested here.
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
format:
enum:
- csv
- excel
- xml
- json
type: string
description: >-
Optional file format of the generated report. Only csv and json are
currently supported by this endpoint — excel and xml requests are
rejected with a 400 error.
default: json
metrics:
minItems: 1
type: array
items:
enum:
- Impressions
- Clicks
- Spend
- Ctr
- Cpc
- Cpm
- AdGroupContextHint
- AdGroupDescription
- ProductName
- AdTitle
- AdCopy
type: string
description: >-
List of metrics to return. At least one metric must be provided.
AdGroupContextHint and AdGroupDescription require AdGroupName in
dimensions; ProductName requires ProductId; AdTitle and AdCopy
require AdId.
startDate:
type: string
description: >-
Start date of the report. Date component of ISO 8601 format, any
time or timezone component is ignored. Must be less than or equal to
endDate.
format: date-time
timezone:
type: string
description: >-
Optional timezone used for the report. Timezone Database (Tz)
format.
default: UTC
nullable: true
additionalProperties: false
description: Query parameters for the Ad-Level Report.
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: {}
````