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

• 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).

📘

This endpoint is referenced here.

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.

📘

This endpoint is referenced here.

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.

📘

This endpoint is referenced here.

Data models

Request attributes (RealTimeProductReportJob)

(*) - Required

Dimensions

Metrics

Step 1. Create an Async Report Job

POST

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

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

GET

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

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

GET

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

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

(*) - Required

Example Request

GET

GET https://api.criteo.com/{version}/marketing-solutions/marketplace-performance-outcomes/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