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,
a maximum 7-day look back window,
Onsite campaign coverage only,
A focused set of metrics: impressions, clicks, spend,
a default rate limit of 10 calls per minute.

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.

Endpoints Overview

Verb	Endpoint	Description
POST	`/retail-media/reports/sync/real-time-performance`	Retrieves real-time Retail Media performance metrics

Attributes

Attribute	Data 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.
`endDate`	date	End date (YYYY-MM-DD) for the reporting window. Optional
`retailerIds`	array of strings	Single retailer ID filter. Optional
`accountIds`	array of strings	Filter by account IDs. Max 50 IDs. Chooseoneof:`accountIds`,`campaignIds`, or`lineItemIds`
`campaignIds`	array of strings	Filter by campaign IDs. Max 50 IDs. Chooseoneof:`accountIds`,`campaignIds`, or`lineItemIds`
`lineItemIds`	array of strings	Filter by line item IDs. Max 50 IDs. Chooseoneof:`accountIds`,`campaignIds`, or`lineItemIds`
`dimensions`*	array of strings	Grouping dimensions. Must contain at leastonevalue.
`metrics`*	array of strings	Requested metrics. Must contain at leastonevalue.
`timezone`	string	Time zone identifier. Defaults to UTC if not provided.

(*) - Required

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.

Supported Dimensions

Values in the dimensions array must be selected from:

accountId,
campaignId,
lineItemId,
retailerId,
accountName,
campaignName,
lineItemName,
retailerName,
date,
hour.

Supported Metrics

Values in the metrics array must be selected from:

impressions,
clicks,
spend.

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.

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.
Rate limit: By default, this endpoint is limited to 10 calls per minute. This is stricter than the standard rate limits that apply to other endpoints, including the other reporting endpoints (40 calls per minute). Requests above this limit are rejected with a 429 Too Many Requests.

Real-Time Performance Endpoint

This endpoint retrieves real-time Retail Media performance metrics.

Sample 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();
?>

Sample Response

{
  "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": []
}

Responses

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

​Endpoints Overview

​Attributes

​Supported Dimensions

​Supported Metrics

​Behavioral Notes

​Real-Time Performance Endpoint

​Sample Request

​Sample Response

​Responses

​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

Endpoints Overview

Attributes

Supported Dimensions

Supported Metrics

Behavioral Notes

Real-Time Performance Endpoint

Sample Request

Sample Response

Responses

Error Examples

Validation Error (Invalid Timezone)

Missing Entity Filters

Entity Filter Limit Exceeded

Missing Metrics

Missing Dimensions

Look back Window Exceeded

Deserialization Error

Forbidden