MPO Real-Time Asynchronous API

⚠️

Important Data Usage Warning

This 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.

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:

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

1. Create a report job

Endpoint: POST /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 /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 /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)

Dimensions

Metrics

1. Create Async report job

 /realtime-reports/export

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.

Request body

{
  "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"
    }
  }
}

Successful response

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

Example error – 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'"
    }
  ]
}

2. Poll for completion

Endpoint: GET /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 Report Output

GET /realtime-reports/{'{<reportId>}'}

Downloads the file corresponding to a completed export job.

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

Path parameters

Example request

GET /realtime-reports/45f7ec55-1008-4372-9144-1da37d8dccc2

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.
• If startDate is provided and endDate is omitted, endDate defaults to the current time.

Violations return invalid-lookbackwindow and/or invalid-time-interval.

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.

Errors & status codes

HTTP status codes

Domain errors / validation errors