Campaign Summary Report

get

https://backstage.taboola.com/backstage/api/1.0/{account_id}/reports/campaign-summary/dimensions/{dimension}

Returns performance metrics for your campaigns.

Usage:

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

Guidelines:

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

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

📍
Data freshness & accuracy
Data is updated throughout the day with a slight delay of a few hours. Please note that figures may shift retroactively as new data arrives: clicks can update for up to 48 hours, and conversions for up to 30 days.

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

Path Params

account_id

string

required

An alphabetic ID. See Get Account Details.

dimension

string

required

The report dimension (aka view) e.g. day, week, month, etc.
For a list of possible values, see: Dimensions Cheat Sheet

Query Params

start_date

string

required

Defaults to 2021-01-01

yyyy-mm-dd
Required for all dimensions.
Hourly reporting supports timestamps - see: Dimensions Cheat Sheet

end_date

string

required

Defaults to 2021-01-02

yyyy-mm-dd
Required for all dimensions.
Hourly reporting supports timestamps - see: Dimensions Cheat Sheet

campaign

string

The campaign_id (A numeric string).
Supported dimension: by_campaign

platform

string

Possible values:
DESK
PHON
TBLT
Unsupported dimensions:
site_breakdown, country_breakdown, region_breakdown, dma_breakdown, platform_breakdown

country

string

2-letter country code, as defined by ISO-3166 (not case-sensitive).
Use the Dictionary to fetch a list of allowed values.
Unsupported dimensions:
site_breakdown, country_breakdown, region_breakdown, dma_breakdown, platform_breakdown

site

string

The site_name of a specific publisher.
Unsupported dimensions:
site_breakdown, country_breakdown, region_breakdown, dma_breakdown, platform_breakdown, user_segment_breakdown

partner_name

string

Name of the data partner.
Supported by a single dimension: user_segment_breakdown.

include_multi_conversions

boolean

If set to true, the report will include Custom Conversion Columns.
Unsupported dimensions: by_hour_of_day.