Real-Time Performance Report

Introduction

The Retail Media Real-Time Performance API is a synchronous reporting endpoint that exposes near real-time campaign performance data from the Retail Media reporting platform. This API is designed for:

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

Typical use-cases for this endpoint include, for example:

Real-time monitoring during major retail events (for example, Black Friday, Prime Day, etc.),
Live optimization dashboards for trading teams,
Alerting systems reacting to sudden performance changes (spend drops/spikes, click anomalies, etc.).

This endpoint provides:

about 15 minute latency from impression/click to availability in the API,
Onsite campaign coverage only,
A focused set of metrics: impressions, clicks, spend,

Metric rename from Preview: billableImpressions and billableClicks have been renamed to impressions and clicks in the stable API. These metrics now count total volume (billable + non-billable). If you were using this endpoint in Preview, update your field mappings before migrating to stable.

Request

POST /2026-07/retail-media/reports/sync/real-time-performance

Rate limits

This endpoint is limited to 10 calls per minute, below both the reporting and the default limit. The limit applies at application level for Client Credentials and per account for Authorization Code. See Rate Limits for the full policy and how to handle 429 responses.

Required fields

startDate, dimensions, and metrics are required. dimensions and metrics must each contain at least one value.

Field	Type	Description
`startDate`	date	Start date (YYYY-MM-DD) for the reporting window. Must be no more than 7 days in the past in the requested timezone.
`dimensions`	array of strings	Grouping dimensions. Must contain at least one value.
`metrics`	array of strings	Requested metrics. Must contain at least one value.

Optional fields

Field	Type	Description
`endDate`	date	End date (YYYY-MM-DD) for the reporting window. Optional. If omitted, returns data from `startDate` up to the current hour.
`retailerIds`	array of strings	Single retailer ID filter.
`accountIds`	array of strings	Filter by account IDs. Max 50 IDs. Use only one of `accountIds`, `campaignIds`, or `lineItemIds`.
`campaignIds`	array of strings	Filter by campaign IDs. Max 50 IDs. Use only one of `accountIds`, `campaignIds`, or `lineItemIds`.
`lineItemIds`	array of strings	Filter by line item IDs. Max 50 IDs. Use only one of `accountIds`, `campaignIds`, or `lineItemIds`.
`timezone`	string	Time zone identifier. Defaults to UTC if not provided.

At least one of dimensions and at least one of metrics must be provided.For entity filters: only one of accountIds or campaignIds or lineItemIds must be provided. This prevents unbounded queries on the full dataset.

Behavioral Notes

Optional end date parameter: The endpoint accepts an optional endDate parameter. If omitted, it will return data from startDate up to the current hour in the requested timezone.
Look back limit: The look back window is limited to 7 days relative to “now” in the requested timezone.
Requests with startDate older than this limit are rejected with a 400 Bad Request.
Time zone handling: All date/hour-based dimensions (date, hour) are computed in the requested timezone.
If timezone is omitted, UTC is used.

Example request

curl -L -X POST 'https://api.criteo.com/{version}/retail-media/reports/sync/real-time-performance' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
  -d '{
  "data": {
    "attributes": {
      "startDate": "2026-03-01",
      "timezone": "America/New_York",
      "campaignIds": ["561627568743333888"],
      "dimensions": ["date", "hour", "campaignId", "campaignName"],
      "metrics": ["impressions", "clicks", "spend"]
    }
  }
}'

import http.client
import json

conn = http.client.HTTPSConnection("api.criteo.com")

payload = json.dumps({
  "data": {
    "attributes": {
      "startDate": "2026-03-01",
      "timezone": "America/New_York",
      "campaignIds": ["561627568743333888"],
      "dimensions": ["date", "hour", "campaignId", "campaignName"],
      "metrics": ["impressions", "clicks", "spend"]
    }
  }
})

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer <MY_ACCESS_TOKEN>'
}

conn.request("POST", "/{version}/retail-media/reports/sync/real-time-performance", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("application/json");

RequestBody body = RequestBody.create(mediaType, "{\"data\":{\"attributes\":{\"startDate\":\"2026-03-01\",\"timezone\":\"America/New_York\",\"campaignIds\":[\"561627568743333888\"],\"dimensions\":[\"date\",\"hour\",\"campaignId\",\"campaignName\"],\"metrics\":[\"impressions\",\"clicks\",\"spend\"]}}}");

Request request = new Request.Builder()
  .url("https://api.criteo.com/{version}/retail-media/reports/sync/real-time-performance")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Bearer <MY_ACCESS_TOKEN>")
  .build();

Response response = client.newCall(request).execute();

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.criteo.com/{version}/retail-media/reports/sync/real-time-performance');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setHeader(array(
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer <MY_ACCESS_TOKEN>'
));
$request->setBody('{"data":{"attributes":{"startDate":"2026-03-01","timezone":"America/New_York","campaignIds":["561627568743333888"],"dimensions":["date","hour","campaignId","campaignName"],"metrics":["impressions","clicks","spend"]}}}');
$response = $request->send();
echo $response->getBody();
?>

Response

A successful request returns 200 OK with the report data directly in the response. There is no report ID to poll and no output to download.

{
  "meta": {
    "dataCompleteThrough": {
      "dateTime": "2026-03-01 15:45:00",
      "timezone": "America/New_York"
    },
    "columns": [
      {
        "name": "date",
        "type": "Date",
        "role": "Dimension",
        "timezone": "America/New_York"
      },
      {
        "name": "hour",
        "type": "Number",
        "role": "Dimension",
        "timezone": "America/New_York"
      },
      {
        "name": "impressions",
        "type": "Number",
        "role": "Metric"
      }
    ],
    "rows": 50
  },
  "data": {
    "type": "ReportDataResponse",
    "attributes": [
      ["2026-03-01", 13, 536],
      ["2026-03-01", 14, 563],
      ["2026-03-01", 15, 641]
    ]
  },
  "warnings": [],
  "errors": []
}

Dimensions

Values in the dimensions array must be selected from the following.

Dimension	Description
`accountId`	Account ID.
`accountName`	Account name.
`campaignId`	Campaign ID.
`campaignName`	Campaign name.
`lineItemId`	Line item ID.
`lineItemName`	Line item name.
`retailerId`	Retailer ID where the line item served.
`retailerName`	Retailer name where the line item served.
`date`	Date events occurred (`YYYY-MM-DD`).
`hour`	Hour events occurred (0-23), in the requested timezone.

Metrics

Values in the metrics array must be selected from the following.

Metric	Description
`impressions`	Counted once per ad creative render on a page.
`clicks`	Counted when an ad creative is clicked.
`spend`	Total media spend. Includes platform fees for Criteo-billed; media only for retailer-billed.

billableImpressions and billableClicks are still accepted for backward compatibility with existing preview integrations, but are redundant with impressions/clicks and should not be used in new integrations.

Response Codes

Response	Title	Detail	Troubleshooting
🟢`200`	Success	Data returned successfully	Call executed with success
🔴`400`	Validation Error	Invalid request (timezone, filters, dimensions, metrics, look back, etc.)	Review request parameters
🔴`400`	Missing Entity Filters	No`accountIds`,`campaignIds`, or`lineItemIds`provided	Provide exactly one entity filter
🔴`400`	Entity Filter Limit Exceeded	Too many IDs provided	Respect max limits
🔴`400`	Missing Metrics	metrics is missing or empty	Provide at least one metric
🔴`400`	Missing Dimensions	dimensions is missing or empty	Provide at least one dimension
🔴`400`	Look back Window Exceeded	`startDate`too old	Ensure ≤ 7 days
🔴`400`	Invalid Timezone	Unsupported timezone	Use valid timezone
🔴`400`	Deserialization Error	Invalid format or type	Fix payload format
🔴`403`	Forbidden	Unauthorized access to resources	Check permissions
🔴`429`	Too Many Requests	Rate limit exceeded (default 10 calls per minute for this endpoint)	Wait before retrying and reduce call frequency

Error Examples

Validation Error (Invalid Timezone)

{
  "warnings": [],
  "errors": [
    {
      "traceId": "0b396e92adef8703a22dd5a5898e05b7",
      "traceIdentifier": "0b396e92adef8703a22dd5a5898e05b7",
      "type": "validation",
      "code": "invalid",
      "instance": "/retail-media/reports/sync/real-time-performance",
      "title": "Time zone America/Paris is not valid. See criteo developer portal for supported time zones",
      "source": {
        "Data.Attributes.Timezone": "Data.Attributes.Timezone"
      }
    }
  ]
}

Missing Entity Filters

{
  "errors": [
    {
      "type": "validation",
      "code": "invalid",
      "instance": "/retail-media/reports/sync/real-time-performance",
      "title": "Exactly one of accountIds, campaignIds, or lineItemIds must be provided"
    }
  ]
}

Entity Filter Limit Exceeded

{
  "errors": [
    {
      "type": "validation",
      "code": "invalid",
      "instance": "/retail-media/reports/sync/real-time-performance",
      "title": "You must provide at most 50 ids in 'CampaignIds', 73 were provided."
    }
  ]
}

Missing Metrics

{
  "errors": [
    {
      "type": "validation",
      "code": "invalid",
      "instance": "/retail-media/reports/sync/real-time-performance",
      "title": "At least one metric must be specified"
    }
  ]
}

Missing Dimensions

{
  "errors": [
    {
      "type": "validation",
      "code": "invalid",
      "instance": "/retail-media/reports/sync/real-time-performance",
      "title": "At least one dimension must be specified"
    }
  ]
}

Look back Window Exceeded

{
  "errors": [
    {
      "type": "validation",
      "code": "invalid",
      "instance": "/retail-media/reports/sync/real-time-performance",
      "title": "startDate cannot be more than 7 days in the past"
    }
  ]
}

Deserialization Error

{
  "errors": [
    {
      "type": "validation",
      "code": "deserialization-error",
      "instance": "/retail-media/reports/sync/real-time-performance",
      "title": "Deserialization error"
    }
  ]
}

Forbidden

{
  "errors": [
    {
      "type": "Authorization",
      "code": "forbidden",
      "instance": "/retail-media/reports/sync/real-time-performance",
      "title": "You are not authorized to access some of the requested resources.",
      "detail": "Please make sure you have the necessary permissions."
    }
  ]
}

​Introduction

​Request

​Rate limits

​Required fields

​Optional fields

​Behavioral Notes

​Example request

​Response

​Dimensions

​Metrics

​Response Codes

​Error Examples

​Validation Error (Invalid Timezone)

​Missing Entity Filters

​Entity Filter Limit Exceeded

​Missing Metrics

​Missing Dimensions

​Look back Window Exceeded

​Deserialization Error

​Forbidden

Introduction

Request

Rate limits

Required fields

Optional fields

Behavioral Notes

Example request

Response

Dimensions

Metrics

Response Codes

Error Examples

Validation Error (Invalid Timezone)

Missing Entity Filters

Entity Filter Limit Exceeded

Missing Metrics

Missing Dimensions

Look back Window Exceeded

Deserialization Error

Forbidden