Real Time Statistics

The purpose of this endpoint is to provide realtime data for CMS via an API.
This provided data is the same as in the Real Time dashboard in CGrowth.

Making a call

Real Time Statistics report is available at the following endpoint:

https://api.criteo.com/preview/reports/realtime

The following request returns data based on the selected attributes similarly to the other reporting endpoints.

Example of body for the POST call:

{
  "data": {
    "type": "string",
    "attributes": {
      "advertiserIds": [
        1234
      ],
      "adsetIds": [
        2345 
      ], 
      "campaignIds": [
        3456
      ],
      "dimensions": [
        "advertiser", "advertiserId", "adset", "adsetId", "campaign", "campaignId", "hour", "day", "week", "month", "year"
      ],
      "metrics": [
        "clicks", "displays", "cost"
      ],
      "lookbackWindow": 12,
      "currency": "EUR",
      "timezone": "UTC"
    }
  }
}

The POST call will generate a report in the format of a JSON document. This is a response example:

{
  "data": [
    {
      "type": "RealtimeStatisticsReport",
      "attributes": {
        "rows": [
          {
            "advertiser": "Advertiser1",
            "advertiserId": "1234",
            "adset": "AdsetName",
            "adsetId": "2345",
            "campaign": "CampaignName",
            "campaignId": "3456",
            "hour": "12",
            "day": "2025-03-31",
            "week": "2025-03-31",
            "month": "2025-03-01",
            "year": "2025-01-01",
            "clicks": "22222",
            "displays": "11111",
            "cost": "33.333"
          },
          {
            "advertiser": "Advertiser1",
            "advertiserId": "1234",
            "adset": "AdsetName",
            "adsetId": "2345",
            "campaign": "CampaignName",
            "campaignId": "3456",
            "hour": "11",
            "day": "2025-03-31",
            "week": "2025-03-31",
            "month": "2025-03-01",
            "year": "2025-01-01",
            "clicks": "44444",
            "displays": "55555",
            "cost": "66.666"
          },
        ]
      }
    }
  ],
  "warnings": [],
  "errors": []
}

Report Request attributes

Below is all possible attributes you may use for the request:

Field	Required	Type	Default Value	Description
`advertiserIds`	Yes	`string[]`		Id(s) of the account(s).
`campaignIds`	Optional	`string[]`	`[]`	Id(s) of the campaigns to filter.
`adsetIds`	Optional	`string[]`	`[]`	Id(s) of the adset(s) to filter.
`lookbackWindow`	Optional	`integer`	`12`	Number of hours going back the query should apply to (from 12 to 24).
`timezone`	Optional	`string`	`UTC`	Timezone used for dates. Must exist in the Time Zone DB.
`currency`	Optional	`string`	`EUR`	Currency in which the results are shown.
`dimensions`	Optional	`Dimension[]`	`["AdvertiserId", "Advertiser", "CampaignId", "Campaign", "AdsetId", "Adset", "Day", "Hour]`	Dimensions of the report.
`metrics`	Optional	`Metric[]`	`["Clicks", "Cost", "Displays"]`	Metrics of the report.

Response Codes

The following response codes may be returned by the API:

400: Bad request, invalid syntax or validation error. Review the request to make sure the format is valid.
401: Authentication failed. Ensure the authentication header is formatted properly and your access token hasn't expired.
403: No campaign found. Verify your campaign IDs are correct.
429: Throttling failure. Wait a minute to try again - there is a limit of 200 requests per minute.
500: Unknown error.

Validation Errors

Below is a list of error codes for the Real Time Statistics endpoint and a more detailed description of their meaning. General guidance on handling API errors can be found here.

insufficient-account-permissions

You do not have the rights to generate a report on these accounts.

invalid

There are different types of errors, depending on title:

The <field> field is required: Missing required field.
Time zone <timezone> is not valid. See criteo developer portal for supported time zones.

Dimensions

Dimensions allow you to specify the aggregation level suited to your needs.

There are no restrictions on the number of dimensions or the order of dimensions. The full list is below:

Value	Description	Type
`advertiserId`	ID of the advertiser.	`String`
`advertiser`	Name of the advertiser.	`String`
`campaignId`	ID of the campaign.	`String`
`campaign`	Name of the campaign.	`String`
`adsetId`	ID of the adset.	`String`
`adset`	Name of the adset.	`String`
`year`	Year in datetime format `YYYY-01-01`.	`Date`
`month`	Month in datetime format `YYYY-MM-01`.	`Date`
`week`	Week in datetime format `YYYY-MM-DD`.	`Date`
`day`	Day in datetime format `YYYY-MM-DD`.	`Date`
`hour`	Hour in format `HH`.	`Date`

Metrics

Value	Description	Type
`clicks`	Number of clicks the campaign has generated.	`Integer`
`cost`	Total cost of the campaign for the client.	`Double`
`displays`	Number of times the campaign has been displayed.	`Integer`