GuidesAPI ReferenceChangelog
GuidesAPI ReferenceChangelog
GuidesAPI ReferenceChangelogLog In
Guides

Async Reports

Suggest Edits

📘

Reporting Asynchronous Workflow: Step 1 of 3

  • First, create a request from one of the async endpoints with the desired attributes
  • This generates a reportId representing the report

Create a Report Request

This endpoint creates a request for Campaign Statistics or Audience Performance report:

https://api.criteo.com/preview/reports/async-statistics

https://api.criteo.com/preview/reports/async-audience-performance

Sample Request

curl -X POST "https://api.criteo.com/preview/reports/async-statistics" \
    -H "Authorization: Bearer myaccesstoken" \
    -H "Content-Type: application/json" \
    -d '{
       "data": {
           "type": "StatisticsReport",
           "attributes": {
                "startDate": "2022-01-01",
                "endDate": "2022-01-02",
                "dimensions": ["CampaignId", "Campaign", "Day"],
                "metrics": ["Clicks", "Displays", "AdvertiserCost"],
                "advertiserIds": ["1111", "2222"],
                "currency": "EUR",
                "timezone": "Europe/Paris",
                "adSetNames": ["myAdSet1", "myAdSet2"],
                "adSetIds": ["789", "456"],
                "adSetStatus": ["Active", "NotRunning"]
            }
        }
    }'

Sample Response

{
    "data": {
        "type": "MarketingSolutionsReportStatus",
        "id": "OWVmNDE3OTMtYTZlZC00YjQ4LThiNjUtYjZkOTE1OGViYjIzfEVVUnxFdXJvcGUvUGFyaXM=",
        "attributes": {
            "status": "pending",
            "message": null
        }
    }
}

📘

Reporting Asynchronous Workflow: Step 2 of 3

  • Next, use the reportId to poll the report status endpoint until one is successfully computed

Get Status of a Specific Report

This endpoint retrieves the status of a specific report. Status can be pending, done, failure, or expired

https://api.criteo.com/preview/reports/{reportId}/status

Sample Request

curl -X GET "https://api.criteo.com/preview/reports/ZWQ1ZDYxY2EtUWNlNy00Nyk0LWFkN1ktY2Q5ZWGyMzA0ZTU0fEzVUnxFdXMvcGZvUGFaaXM=/status" \
    -H "Authorization: Bearer myaccesstoken"

Sample Response

{
  "data": {
    "type": "MarketingSolutionsReportStatus",
    "id": "OWVmNDE3OTMtYTZlZC00YjQ4LThiNjUtYjZkOTE1OGViYjIzfEVVUnxFdXJvcGUvUGFyaXM=",
    "attributes": {
      "status": "Done",
      "message": rows_count=123
    }
  },
  "errors": [],
  "warnings": []
}

📘

Reporting Asynchronous Workflow: Step 3 of 3

  • Finally, download the report using the report output endpoint

Download Output of a Specific Report

This endpoint returns the specific report in the requested format

https://api.criteo.com/preview/reports/{reportId}/output

Sample Request

curl -X GET "https://api.criteo.com/preview/reports/ZWQ1ZDYxY2EtUWNlNy00Nyk0LWFkN1ktY2Q5ZWGyMzA0ZTU0fEzVUnxFdXMvcGZvUGFaaXM=/output" \
    -H "Authorization: Bearer myaccesstoken"

Sample Response

{
  "data": {
    "metaData": {
      "columns": [
        { "name": "CampaignId", "type": "String", "role": "Dimension" },
        { "name": "Campaign", "type": "String", "role": "Property", "relatedTo": "CampaignId" },
        { "name": "Day", "type": "String", "role": "Interval", "timezone": "Europe/Paris"},
        { "name": "Clicks", "type": "Number", "role": "Metric" },
        { "name": "Displays", "type": "Number", "role": "Metric" },
        { "name": "AdvertiserCost", "type": "Money", "role": "Metric", "currency": "EUR" }
      ],
      "rows": 4
    },
    "data": [
      [ 1111, "CampaignName1", "2022-01-01", 876, 1234, 20 ],
      // ....
      [ 2222, "CampaignName2", "2022-01-02", 678, 4321, 22 ]
    ]
  }
}

Insights on Data Latency and Storage

  • It is typical for data latency to take 2-8 hours, but there may be minor adjustments made up until the 120th hour before finalization.

  • Data is processed in batches every hour, and some data from the same day may only be partially available.

  • Reports are stored in cache for a minimum of 1 hour before they expire.

Updated about 2 months ago