The following examples demonstrate the basic usage of the API.
Make sure to read the specific guidelines for each dimension and filter - see Dimensions Cheat Sheet and Filters.
Example 1 -by_hour dimension
by_hour dimensionGET /backstage/api/1.0/<<example_advertiser_id>>/reports/realtime-campaign-summary/dimensions/by_hour?start_date=2023-03-28T00:00:00&end_date=2023-03-28T23:59:59 HTTP/1.1
Host: backstage.taboola.com
Authorization: Bearer {access-token}{
"timezone": "EDT",
"results": [
{
"date": "2023-03-28 02:00:00.0",
"clicks": 0,
"visible_impressions": 5,
"spent": 0,
"cpa_actions_num": 0,
"conversions_value": 0,
"roas": 0,
"vctr": 0,
"vcpm": 0,
"cpc": 0,
"cpa": 0,
"cpa_conversion_rate": 0
},
{
"date": "2023-03-28 01:00:00.0",
"clicks": 0,
"visible_impressions": 18,
"spent": 0,
"cpa_actions_num": 0,
"conversions_value": 0,
"roas": 0,
"vctr": 0,
"vcpm": 0,
"cpc": 0,
"cpa": 0,
"cpa_conversion_rate": 0
},
{
"date": "2023-03-28 00:00:00.0",
"clicks": 0,
"visible_impressions": 8,
"spent": 0,
"cpa_actions_num": 0,
"conversions_value": 0,
"roas": 0,
"vctr": 0,
"vcpm": 0,
"cpc": 0,
"cpa": 0,
"cpa_conversion_rate": 0
}
],
"recordCount": 3,
"metadata": {
"total": 3,
"count": 3,
"static_fields": [
{
"id": "date",
"format": null,
"data_type": "DATE"
},
{
"id": "clicks",
"format": null,
"data_type": "NUMERIC"
},
{
"id": "visible_impressions",
"format": null,
"data_type": "NUMERIC"
},
{
"id": "spent",
"format": null,
"data_type": "MONEY"
},
{
"id": "cpa_actions_num",
"format": null,
"data_type": "NUMERIC"
},
{
"id": "conversions_value",
"format": ".2f",
"data_type": "MONEY"
},
{
"id": "roas",
"format": ".2f",
"data_type": "PERCENT"
},
{
"id": "vctr",
"format": null,
"data_type": "PERCENT"
},
{
"id": "vcpm",
"format": null,
"data_type": "MONEY"
},
{
"id": "cpc",
"format": ".3f",
"data_type": "MONEY"
},
{
"id": "cpa",
"format": ".3f",
"data_type": "MONEY"
},
{
"id": "cpa_conversion_rate",
"format": null,
"data_type": "PERCENT"
}
]
}
}Example 2 - by_smallest_time_bucket dimension
by_smallest_time_bucket dimensionGET /backstage/api/1.0/<<example_advertiser_id>>/reports/realtime-campaign-summary/dimensions/by_smallest_time_bucket?start_date=2023-03-28T00:00:00&end_date=2023-03-28T23:59:59
HTTP/1.1
Host: backstage.taboola.com
Authorization: Bearer {access-token}{
"timezone": "EDT",
"results": [
{
"date": "2023-03-28 02:10:00.0",
"clicks": 0,
"visible_impressions": 2,
"spent": 0,
"cpa_actions_num": 0,
"conversions_value": 0,
"roas": 0,
"vctr": 0,
"vcpm": 0,
"cpc": 0,
"cpa": 0,
"cpa_conversion_rate": 0
},
{
"date": "2023-03-28 02:05:00.0",
"clicks": 0,
"visible_impressions": 2,
"spent": 0,
"cpa_actions_num": 0,
"conversions_value": 0,
"roas": 0,
"vctr": 0,
"vcpm": 0,
"cpc": 0,
"cpa": 0,
"cpa_conversion_rate": 0
},
{
"date": "2023-03-28 02:00:00.0",
"clicks": 0,
"visible_impressions": 3,
"spent": 0,
"cpa_actions_num": 0,
"conversions_value": 0,
"roas": 0,
"vctr": 0,
"vcpm": 0,
"cpc": 0,
"cpa": 0,
"cpa_conversion_rate": 0
}
],
"recordCount": 3,
"metadata": {
"total": 3,
"count": 3,
"static_fields": [
{
"id": "date",
"format": null,
"data_type": "DATE"
},
{
"id": "clicks",
"format": null,
"data_type": "NUMERIC"
},
{
"id": "visible_impressions",
"format": null,
"data_type": "NUMERIC"
},
{
"id": "spent",
"format": null,
"data_type": "MONEY"
},
{
"id": "cpa_actions_num",
"format": null,
"data_type": "NUMERIC"
},
{
"id": "conversions_value",
"format": ".2f",
"data_type": "MONEY"
},
{
"id": "roas",
"format": ".2f",
"data_type": "PERCENT"
},
{
"id": "vctr",
"format": null,
"data_type": "PERCENT"
},
{
"id": "vcpm",
"format": null,
"data_type": "MONEY"
},
{
"id": "cpc",
"format": ".3f",
"data_type": "MONEY"
},
{
"id": "cpa",
"format": ".3f",
"data_type": "MONEY"
},
{
"id": "cpa_conversion_rate",
"format": null,
"data_type": "PERCENT"
}
]
}
}Example 3 - by_campaign dimension
by_campaign dimensionGET /backstage/api/1.0/<<example_advertiser_id>>/reports/realtime-campaign-summary/dimensions/by_campaign?start_date=2023-03-28T00:00:00&end_date=2023-03-28T23:59:59 HTTP/1.1
Host: backstage.taboola.com
Authorization: Bearer {access-token}{
"timezone": "EDT",
"results": [
{
"clicks": 38,
"visible_impressions": 1150,
"spent": 1.14,
"cpa_actions_num": 67,
"conversions_value": 0,
"roas": 0,
"vctr": 3.3,
"vcpm": 0.99,
"cpc": 0.03,
"cpa": 0.017,
"cpa_conversion_rate": 176.3,
"campaign_id": "483",
"campaign_name": "My Test Campaign"
},
{
"clicks": 22,
"visible_impressions": 720,
"spent": 0.66,
"cpa_actions_num": 43,
"conversions_value": 0,
"roas": 0,
"vctr": 3.06,
"vcpm": 0.92,
"cpc": 0.03,
"cpa": 0.015,
"cpa_conversion_rate": 195.5,
"campaign_id": "487",
"campaign_name": "Another Campaign"
}
],
"recordCount": 2,
"metadata": {
"total": 2,
"count": 2
}
}Example 4 - by_campaign_by_smallest_time_bucket dimension
by_campaign_by_smallest_time_bucket dimensionGET /backstage/api/1.0/<<example_advertiser_id>>/reports/realtime-campaign-summary/dimensions/by_campaign_by_smallest_time_bucket?start_date=2023-03-28T00:00:00&end_date=2023-03-28T01:00:00&campaign=483 HTTP/1.1
Host: backstage.taboola.com
Authorization: Bearer {access-token}{
"timezone": "EDT",
"results": [
{
"date": "2023-03-28 00:55:00.0",
"clicks": 2,
"visible_impressions": 78,
"spent": 0.06,
"cpa_actions_num": 4,
"conversions_value": 0,
"roas": 0,
"vctr": 2.56,
"vcpm": 0.77,
"cpc": 0.03,
"cpa": 0.015,
"cpa_conversion_rate": 200,
"campaign_id": "483",
"campaign_name": "My Test Campaign"
},
{
"date": "2023-03-28 00:50:00.0",
"clicks": 3,
"visible_impressions": 95,
"spent": 0.09,
"cpa_actions_num": 5,
"conversions_value": 0,
"roas": 0,
"vctr": 3.16,
"vcpm": 0.95,
"cpc": 0.03,
"cpa": 0.018,
"cpa_conversion_rate": 166.7,
"campaign_id": "483",
"campaign_name": "My Test Campaign"
}
],
"recordCount": 2,
"metadata": {
"total": 2,
"count": 2
}
}Example 5 - by_site dimension
by_site dimensionGET /backstage/api/1.0/<<example_advertiser_id>>/reports/realtime-campaign-summary/dimensions/by_site?start_date=2023-03-28T00:00:00&end_date=2023-03-28T23:59:59 HTTP/1.1
Host: backstage.taboola.com
Authorization: Bearer {access-token}{
"timezone": "EDT",
"results": [
{
"clicks": 45,
"visible_impressions": 1320,
"spent": 1.35,
"cpa_actions_num": 82,
"conversions_value": 0,
"roas": 0,
"vctr": 3.41,
"vcpm": 1.02,
"cpc": 0.03,
"cpa": 0.016,
"cpa_conversion_rate": 182.2,
"site_id": "1001234",
"site_name": "example-publisher.com"
},
{
"clicks": 15,
"visible_impressions": 550,
"spent": 0.45,
"cpa_actions_num": 28,
"conversions_value": 0,
"roas": 0,
"vctr": 2.73,
"vcpm": 0.82,
"cpc": 0.03,
"cpa": 0.016,
"cpa_conversion_rate": 186.7,
"site_id": "1005678",
"site_name": "another-site.com"
}
],
"recordCount": 2,
"metadata": {
"total": 2,
"count": 2
}
}Example 6 - by_site_by_smallest_time_bucket dimension
by_site_by_smallest_time_bucket dimensionGET /backstage/api/1.0/<<example_advertiser_id>>/reports/realtime-campaign-summary/dimensions/by_site_by_smallest_time_bucket?start_date=2023-03-28T00:00:00&end_date=2023-03-28T01:00:00&site_id=1001234 HTTP/1.1
Host: backstage.taboola.com
Authorization: Bearer {access-token}{
"timezone": "EDT",
"results": [
{
"date": "2023-03-28 00:55:00.0",
"clicks": 3,
"visible_impressions": 89,
"spent": 0.09,
"cpa_actions_num": 6,
"conversions_value": 0,
"roas": 0,
"vctr": 3.37,
"vcpm": 1.01,
"cpc": 0.03,
"cpa": 0.015,
"cpa_conversion_rate": 200,
"site_id": "1001234",
"site_name": "example-publisher.com"
},
{
"date": "2023-03-28 00:50:00.0",
"clicks": 2,
"visible_impressions": 67,
"spent": 0.06,
"cpa_actions_num": 4,
"conversions_value": 0,
"roas": 0,
"vctr": 2.99,
"vcpm": 0.9,
"cpc": 0.03,
"cpa": 0.015,
"cpa_conversion_rate": 200,
"site_id": "1001234",
"site_name": "example-publisher.com"
}
],
"recordCount": 2,
"metadata": {
"total": 2,
"count": 2
}
}Example 7 - by_country dimension
by_country dimensionGET /backstage/api/1.0/<<example_advertiser_id>>/reports/realtime-campaign-summary/dimensions/by_country?start_date=2023-03-28T00:00:00&end_date=2023-03-28T23:59:59 HTTP/1.1
Host: backstage.taboola.com
Authorization: Bearer {access-token}{
"timezone": "EDT",
"results": [
{
"clicks": 42,
"visible_impressions": 1250,
"spent": 1.26,
"cpa_actions_num": 78,
"conversions_value": 0,
"roas": 0,
"vctr": 3.36,
"vcpm": 1.01,
"cpc": 0.03,
"cpa": 0.016,
"cpa_conversion_rate": 185.7,
"country": "us",
"country_name": "United States"
},
{
"clicks": 18,
"visible_impressions": 620,
"spent": 0.54,
"cpa_actions_num": 32,
"conversions_value": 0,
"roas": 0,
"vctr": 2.9,
"vcpm": 0.87,
"cpc": 0.03,
"cpa": 0.017,
"cpa_conversion_rate": 177.8,
"country": "ca",
"country_name": "Canada"
}
],
"recordCount": 2,
"metadata": {
"total": 2,
"count": 2
}
}Example 8 - by_country_by_smallest_time_bucket dimension
by_country_by_smallest_time_bucket dimensionGET /backstage/api/1.0/<<example_advertiser_id>>/reports/realtime-campaign-summary/dimensions/by_country_by_smallest_time_bucket?start_date=2023-03-28T00:00:00&end_date=2023-03-28T01:00:00&country=us HTTP/1.1
Host: backstage.taboola.com
Authorization: Bearer {access-token}{
"timezone": "EDT",
"results": [
{
"date": "2023-03-28 00:55:00.0",
"clicks": 3,
"visible_impressions": 89,
"spent": 0.09,
"cpa_actions_num": 5,
"conversions_value": 0,
"roas": 0,
"vctr": 3.37,
"vcpm": 1.01,
"cpc": 0.03,
"cpa": 0.018,
"cpa_conversion_rate": 166.7,
"country": "us",
"country_name": "United States"
},
{
"date": "2023-03-28 00:50:00.0",
"clicks": 2,
"visible_impressions": 67,
"spent": 0.06,
"cpa_actions_num": 4,
"conversions_value": 0,
"roas": 0,
"vctr": 2.99,
"vcpm": 0.9,
"cpc": 0.03,
"cpa": 0.015,
"cpa_conversion_rate": 200,
"country": "us",
"country_name": "United States"
}
],
"recordCount": 2,
"metadata": {
"total": 2,
"count": 2
}
}Example 9 - by_platform dimension
by_platform dimensionGET /backstage/api/1.0/<<example_advertiser_id>>/reports/realtime-campaign-summary/dimensions/by_platform?start_date=2023-03-28T00:00:00&end_date=2023-03-28T23:59:59 HTTP/1.1
Host: backstage.taboola.com
Authorization: Bearer {access-token}{
"timezone": "EDT",
"results": [
{
"clicks": 58,
"visible_impressions": 1680,
"spent": 1.74,
"cpa_actions_num": 95,
"conversions_value": 0,
"roas": 0,
"vctr": 3.45,
"vcpm": 1.04,
"cpc": 0.03,
"cpa": 0.018,
"cpa_conversion_rate": 163.8,
"platform": "DESK",
"platform_name": "Desktop"
},
{
"clicks": 24,
"visible_impressions": 820,
"spent": 0.72,
"cpa_actions_num": 42,
"conversions_value": 0,
"roas": 0,
"vctr": 2.93,
"vcpm": 0.88,
"cpc": 0.03,
"cpa": 0.017,
"cpa_conversion_rate": 175,
"platform": "PHON",
"platform_name": "Phone"
},
{
"clicks": 8,
"visible_impressions": 290,
"spent": 0.24,
"cpa_actions_num": 14,
"conversions_value": 0,
"roas": 0,
"vctr": 2.76,
"vcpm": 0.83,
"cpc": 0.03,
"cpa": 0.017,
"cpa_conversion_rate": 175,
"platform": "TBLT",
"platform_name": "Tablet"
}
],
"recordCount": 3,
"metadata": {
"total": 3,
"count": 3
}
}Example 10 - by_platform_by_smallest_time_bucket dimension
by_platform_by_smallest_time_bucket dimensionGET /backstage/api/1.0/<<example_advertiser_id>>/reports/realtime-campaign-summary/dimensions/by_platform_by_smallest_time_bucket?start_date=2023-03-28T00:00:00&end_date=2023-03-28T01:00:00&platform=DESK HTTP/1.1
Host: backstage.taboola.com
Authorization: Bearer {access-token}{
"timezone": "EDT",
"results": [
{
"date": "2023-03-28 00:55:00.0",
"clicks": 4,
"visible_impressions": 112,
"spent": 0.12,
"cpa_actions_num": 7,
"conversions_value": 0,
"roas": 0,
"vctr": 3.57,
"vcpm": 1.07,
"cpc": 0.03,
"cpa": 0.017,
"cpa_conversion_rate": 175,
"platform": "DESK",
"platform_name": "Desktop"
},
{
"date": "2023-03-28 00:50:00.0",
"clicks": 3,
"visible_impressions": 95,
"spent": 0.09,
"cpa_actions_num": 5,
"conversions_value": 0,
"roas": 0,
"vctr": 3.16,
"vcpm": 0.95,
"cpc": 0.03,
"cpa": 0.018,
"cpa_conversion_rate": 166.7,
"platform": "DESK",
"platform_name": "Desktop"
}
],
"recordCount": 2,
"metadata": {
"total": 2,
"count": 2
}
}Sample error responses
{
"http_status": 400,
"message": "Requested interval [24 hours] exceeds the max interval for this context [1 hours]",
"message_code": "api.action.bad_request.null"
}