DSP Real-Time Performance API

📘
For more information about our DSP endpoints in Stable, please visit this page. The Real-Time Performance API endpoint is currently available only in preview.

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 billable metrics: billableImpressions, billableClicks, spend.

Endpoints Overview

Verb	Endpoint	Description
POST	`/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 5 IDs. Choose one of: `accountIds`, `campaignIds`, or `lineItemIds`
`campaignIds`	array of strings	Filter by campaign IDs. Max 50 IDs. Choose one of: `accountIds`, `campaignIds`, or `lineItemIds`
`lineItemIds`	array of strings	Filter by line item IDs. Max 50 IDs. Choose one of: `accountIds`, `campaignIds`, or `lineItemIds`
`dimensions`*	array of strings	Grouping dimensions. Must contain at least one value.
`metrics`*	array of strings	Requested metrics. Must contain at least one value.
`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:

billableImpressions,
billableClicks,
spend.

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.

Real-Time Performance Endpoint

This endpoint retrieves real-time Retail Media performance metrics.

https://api.criteo.com/{version}/reports/sync/real-time-performance

Sample Request

curl -L -X POST 'https://api.criteo.com/{version}/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": ["billableImpressions", "billableClicks", "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": ["billableImpressions", "billableClicks", "spend"]
    }
  }
})

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

conn.request("POST", "/{version}/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\":{\"type\":\"ReportDataResponse\",\"attributes\":{\"startDate\":\"2026-03-01\",\"timezone\":\"America/New_York\",\"campaignIds\":[\"561627568743333888\"],\"dimensions\":[\"date\",\"hour\",\"campaignId\",\"campaignName\"],\"metrics\":[\"billableImpressions\",\"billableClicks\",\"spend\"]}}}");

Request request = new Request.Builder()
  .url("https://api.criteo.com/{version}/reports/sync/real-time-performance")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Bearer <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}/reports/sync/real-time-performance');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setHeader(array(
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer <TOKEN>'
));
$request->setBody('{"data":{"type":"ReportDataResponse","attributes":{"startDate":"2026-03-01","timezone":"America/New_York","campaignIds":["561627568743333888"],"dimensions":["date","hour","campaignId","campaignName"],"metrics":["billableImpressions","billableClicks","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": "billableImpressions",
        "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

Error Examples

Validation Error (Invalid Timezone)

{
  "warnings": [],
  "errors": [
    {
      "traceId": "0b396e92adef8703a22dd5a5898e05b7",
      "traceIdentifier": "0b396e92adef8703a22dd5a5898e05b7",
      "type": "validation",
      "code": "invalid",
      "instance": "/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": "/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": "/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": "/reports/sync/real-time-performance",
      "title": "At least one metric must be specified"
    }
  ]
}

Missing Dimensions

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

Look back Window Exceeded

{
  "errors": [
    {
      "type": "validation",
      "code": "invalid",
      "instance": "/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": "/reports/sync/real-time-performance",
      "title": "Deserialization error"
    }
  ]
}

Forbidden

{
  "errors": [
    {
      "type": "Authorization",
      "code": "forbidden",
      "instance": "/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."
    }
  ]
}