API ReferenceCommunity DiscussionAnnouncementsSubscribe
API ReferenceAnnouncementsCommunity Discussion
API ReferenceCommunity DiscussionAnnouncementsSubscribeLog In
API Reference

Campaign Summary Report

get https://backstage.taboola.com/backstage/api/1.0//reports/campaign-summary/dimensions/

Returns performance metrics for your campaigns.

Usage:

  1. Provide a dimension (as a path param).
  2. Provide relevant filters (as query params).

Guidelines:

  1. Your chosen dimension determines which filters you can use. See the topics that follow.
  2. platform, country, site and partner_name are mutually exclusive filters - you can apply 1 only.

📘

Supported Filters

Your chosen dimension determines which filters (query params) you can use. See the Dimensions Overview that follows.
Unsupported filters (query params) are typically ignored.

Sample query with successful response

The query below uses the day dimension and these filters: start_date (required), end_date (required), campaign (optional), site (optional).

GET {url}/backstage/api/1.0/demo-account/reports/campaign-summary/dimensions/day?start_date=2019-12-01&end_date=2019-12-31&campaign=1234&site=Demo%20-%20Site

{
   "last-used-rawdata-update-time": "2019-12-17 09:00:00.0",
   "last-used-rawdata-update-time-gmt-millisec": 1576591200000,
   "timezone": "EST",
   "results": [
      {
         "date": "2019-10-26 00:00:00.0",
         "date_end_period": "2019-10-26 00:00:00.0",
         "clicks": 0,
         "impressions": 154,
         "visible_impressions": 47,
         "spent": 0,
         "conversions_value": 0,
         "roas": 0,
         "ctr": 0,
         "vctr": 0,
         "cpm": 0,
         "vcpm": 0,
         "cpc": 0,
         "campaigns_num": 1,
         "cpa": 0,
         "cpa_clicks": 0,
         "cpa_views": 0,
         "cpa_actions_num": 0,
         "cpa_actions_num_from_clicks": 0,
         "cpa_actions_num_from_views": 0,
         "cpa_conversion_rate": 0,
         "cpa_conversion_rate_clicks": 0,
         "cpa_conversion_rate_views": 0,
         "currency": "USD"
      }
      // additional rows (objects) omitted below...
   ],
   "recordCount": 9,
   "metadata": {
      "total": 9,
      "count": 9,
      "static_fields": [
         {
            "id": "date",
            "format": null,
            "data_type": "DATE"
         },
         {
            "id": "date_end_period",
            "format": null,
            "data_type": "STRING"
         },
         {
            "id": "clicks",
            "format": null,
            "data_type": "NUMERIC"
         }
        // additional field definitions (objects) omitted below...
      ]
   }
}

📘

Response Body

The response body is a valid, JSON object, with a results property containing the report.

Error responses

(Refer to the callouts below.)

{
   "http_status": 400,
   "message": "params and dimension requested are not applicable to the [campaign-summary] report."
}

{
   "http_status": 400,
   "message": "Filter 'partner_name' has invalid value",
   "offending_field": "partner_name"
}

{
    "http_status": 400,
    "message": "No dimension with Id [imaginary_breakdown] under report Id [campaign-summary] was found"
}

{
   "http_status": 403,
   "message": "Requested action is forbidden"
}

{
   "http_status": 400,
   "message": "Invalid format: \"2019-10=25\" is malformed at \"=25\"",
   "offending_field": "start_date"
}

🚧

Exclusive Filters

platform, country, site (and partner_name) are exclusive filters - you can apply _1 of them only _in a given request. Combining more than 1 will result in Error 400.

📘

partner_name

partner_name is only applicable if you have multiple accounts.

🚧

day/week/month

When using the day, week or month dimensions, the site filter must be combined with the campaign filter. (Using the site filter on its own returns Error 500.)

Language