Skip to main content
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: The following request returns data based on the selected attributes similarly to the other reporting endpoints. Example of body for the POST call:
Example POST body
{
  "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:
JSON
{
  "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 theTime 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 formatYYYY-01-01.

Date

month

Month in datetime formatYYYY-MM-01.

Date

week

Week in datetime formatYYYY-MM-DD.

Date

day

Day in datetime formatYYYY-MM-DD.

Date

hour

Hour in formatHH.

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