MPO Real-Time Asynchronous API

Important Data Usage WarningThis data is generated in real time and is intended only for real-time reporting purposes. It is not subject to standard data cleaning practices (deduplication, quality checks) and must not be used for pricing, bidding, invoicing, or any financial decision-making.

BETA Access
The API is currently in beta and is only available to a limited list of clients onboarded by the Criteo technical team. You can find the reference for the endpoints mentioned in the page in the Preview version of this documentation.

Overview

This API provides real-time reporting for Marketplace Performance Outcomes (MPO) via an asynchronous export workflow designed for large volumes of data.

Data latency: Approximately 10 minutes.
Base URL:

https://api.criteo.com/{version}/marketing-solutions/marketplace-performance-outcomes/stats/

Compatibility: This endpoint supports both multi-seller and single-seller campaign configurations.

The workflow is:

Create an asynchronous report job with your filters.
Poll the job status until it is complete.
Download the generated export file (CSV or JSON).

1. Create a report job

Endpoint: POST /stats/realtime-reports/export Submit a request with your desired filters. The API creates an export job and returns an identifier (UUID) and a status (typically Pending).

2. Poll for Completion

Endpoint: GET /stats/report-jobs/{reportId} Poll the job status until it reaches Done. Do not poll more than once every 5–10 seconds to remain within rate limits.

Status options: Pending, Done, Failure, Expired.
Note: Identical requests may reuse cached results, returning a previously generated ID.

3. Download the report

Endpoint: GET /stats/realtime-reports/{reportId} Once the status is Done, this call returns the raw file bytes.

CSV output: Content-Type: text/csv.
JSON output: Content-Type: application/json.

Data models

Request attributes (`RealTimeProductReportJob`)

(*) - Required

Dimensions

Metrics

Step 1. Create an Async Report Job

This endpoint creates a new asynchronous report job for a real-time product report. The backend triggers production of an export file and may reuse cached results when the same request has already been processed.

Sample Request

{
  "data": {
    "type": "RealTimeProductReportJob",
    "attributes": {
      "fileFormat": "csv",
      "advertiserIds": ["321"],
      "campaignIds": ["12345", "56789"],
      "sellerIds": ["254614150"],
      "dimensions": ["advertiserId", "campaignId", "sellerId"],
      "metrics": ["clicks", "displays", "cost"],
      "startDate": "2026-01-09T08:00:00Z",
      "endDate": "2026-01-09T09:00:00Z",
      "timezone": "UTC"
    }
  }
}

Sample Response

Successful Response

{
  "exportId": "45f7ec55-1008-4372-9144-1da37d8dccc2",
  "status": "Pending",
  "message": null
}

Error Example: unsupported `fileFormat`

If fileFormat is not one of csv or json, the API returns a 400 Bad Request validation error.

{
  "warnings": [],
  "errors": [
    {
      "traceId": "31500d5059bb85b2168e9256f8722fa8",
      "type": "validation",
      "code": "json-serialization-error",
      "title": "JSON error",
      "detail": "data.attributes.fileFormat 'xls' not valid. Must be one of 'Csv','Json'"
    }
  ]
}

Step 2. Poll for completion

This endpoint polls the job status until it reaches Done.
Do not poll more than once every 5–10 seconds to remain within rate limits.

Status options: Pending, Done, Failure, Expired.
Note: Identical requests may reuse cached results, returning a previously generated ID.

Step 3. Download Report Output

This endpoint downloads the file corresponding to a completed export job.

Download availability windowExport files generated by the MPO Real-Time Asynchronous API are only guaranteed to be available for download for a short period after the job reaches status = Done (typically up to 4 hours). If the file has expired, you must create a new export job and download its output within this retention window.

If fileFormat = csv → Content-Type: text/csv
If fileFormat = json → Content-Type: application/json

Path Parameters

(*) - Required

Example Request

Successful response

200 OK only if job status is Done.
Body contains raw file bytes (CSV or JSON).

Output formats

CSV output

The response contains a header row followed by data rows.

"advertiserId","campaignId","clicks","displays","cost"
321,12345,1873,800247,992.21671380425
321,56789,17927,5275096,3460.71409576333
...

JSON output

The response contains a columnar JSON payload with a data array and top-level columns and rows fields.

{
  "columns": [
    "advertiserId",
    "campaignId",
    "clicks",
    "displays",
    "cost"
  ],
  "data": [
    [
      321,
      12345,
      17927,
      5275096,
      3460.71409576333
    ],
    [
      321,
      56789,
      1873,
      800247,
      992.21671380425
    ]
  ],
  "rows": 2
}

Validation rules

The following validation rules are explicitly described via field notes and domain errors.

1) Required fields

advertiserIds is required.
Missing required fields yields invalid-query.

2) File format

fileFormat must be one of csv or json.
Otherwise the API returns json-serialization-error (as shown in the example).

3) Time interval definition

You must use exactly one of:

Relative interval: lookbackWindow (minutes from now).
Absolute interval: startDate (and optionally endDate).

Rules:

lookbackWindow must be within 60–1440.
lookbackWindow cannot be combined with startDate and/or endDate.
startDate is mutually exclusive with lookbackWindow.
startDate must be within the last 24 hours relative to “now”. Requests with an older startDate are rejected.
If startDate is provided and endDate is omitted, endDate defaults to the current time.

4) Time zone

timezone must exist in the IANA Time Zone database.
Invalid time zones yield invalid-query (as part of “invalid query definition”).

5) Dimension combination constraints

Only one of the following dimensions can be used in a single request:
- productId
- hour
- minute

Violations yield invalid-dimensioncombination.

6) Report lifecycle constraints

Downloading output is only valid when status == Done.
If the job does not exist (or is not visible), the API returns export-not-found and maps it to HTTP 403.
If the job exists, but the output has been permanently deleted, the API returns export-alreadyexpired.

7) Caching behavior (identical requests)

Identical requests may reuse cached results, meaning a previous export/report ID may be returned instead of generating a new export.

Introduction

Marketing Solutions Endpoints

MPO Real-Time Asynchronous API

Overview

1. Create a report job

2. Poll for Completion

3. Download the report

Data models

Request attributes (`RealTimeProductReportJob`)

Dimensions

Metrics

Step 1. Create an Async Report Job

Sample Request

Sample Response

Successful Response

Error Example: unsupported `fileFormat`

Step 2. Poll for completion

Step 3. Download Report Output

Path Parameters

Example Request

Successful response

Output formats

CSV output

JSON output

Validation rules

1) Required fields

2) File format

3) Time interval definition

4) Time zone

5) Dimension combination constraints

6) Report lifecycle constraints

7) Caching behavior (identical requests)

Errors & status codes

HTTP status codes

Domain errors / validation errors

What’s next

​Overview

​1. Create a report job

​2. Poll for Completion

​3. Download the report

​Data models

​Request attributes (RealTimeProductReportJob)

​Dimensions

​Metrics

​Step 1. Create an Async Report Job

​Sample Request

​Sample Response

​Successful Response

​Error Example: unsupported fileFormat

​Step 2. Poll for completion

​Step 3. Download Report Output

​Path Parameters

​Example Request

​Successful response

​Output formats

​CSV output

​JSON output

​Validation rules

​1) Required fields

​2) File format

​3) Time interval definition

​4) Time zone

​5) Dimension combination constraints

​6) Report lifecycle constraints

​7) Caching behavior (identical requests)

​Errors & status codes

​HTTP status codes

​Domain errors / validation errors

​What’s next

Overview

1. Create a report job

2. Poll for Completion

3. Download the report

Data models

Request attributes (`RealTimeProductReportJob`)

Dimensions

Metrics

Step 1. Create an Async Report Job

Sample Request

Sample Response

Successful Response

Error Example: unsupported `fileFormat`

Step 2. Poll for completion

Step 3. Download Report Output

Path Parameters

Example Request

Successful response

Output formats

CSV output

JSON output

Validation rules

1) Required fields

2) File format

3) Time interval definition

4) Time zone

5) Dimension combination constraints

6) Report lifecycle constraints

7) Caching behavior (identical requests)

Errors & status codes

HTTP status codes

Domain errors / validation errors

What’s next