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

Some examples

🚧

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_item dimension

GET /backstage/api/1.0/<<example_advertiser_id>>/reports/realtime-top-campaign-content/dimensions/by_item?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": "CEST",
  "results": [
    {
      "clicks": 20,
      "visible_impressions": 786,
      "spent": 0.6,
      "cpa_actions_num": 103,
      "conversions_value": 0,
      "roas": 0,
      "vctr": 2.5445292620865136,
      "vcpm": 0.76,
      "cpc": 0.03,
      "cpa": 0.006,
      "cpa_conversion_rate": 515,
      "item_id": "4934",
      "item_name": "Ecco i 10 nomi per bambini maschili con il significato",
      "description": "Ecco la classifica dei primi 10 nomi per bambini maschili con il relativo significato.",
      "thumbnail_url": "http://cdn.taboola.com/b4ff94.jpg",
      "url": "https://url/ii",
      "cta": "NONE",
      "performance_status": "STATIC_IMAGE",
      "item_status": "RUNNING",
      "item_type": "ITEM",
      "reject_reason": null,
      "status_reason": null,
      "campaign_id": "483",
      "campaign_name": "camp name",
      "account_numeric_id": "810",
      "account_id": "<<example_advertiser_id>>",
      "account_name": "<<example_advertiser_name>>",
      "learning_state": "LEARNING_COMPLETE"
    },
    {
      "clicks": 16,
      "visible_impressions": 974,
      "spent": 0.48,
      "cpa_actions_num": 90,
      "conversions_value": 0,
      "roas": 0,
      "vctr": 1.642710472279261,
      "vcpm": 0.49,
      "cpc": 0.03,
      "cpa": 0.005,
      "cpa_conversion_rate": 562.5,
      "item_id": "4929",
      "item_name": "Ecco significato",
      "description": "Ecco la classifica  significato.",
      "thumbnail_url": "http://cdn.taboola.com/92d8.jpg",
      "url": "https://url",
      "cta": "NONE",
      "performance_status": "STATIC_IMAGE",
      "item_status": "RUNNING",
      "item_type": "ITEM",
      "reject_reason": null,
      "status_reason": null,
      "campaign_id": "483",
      "campaign_name": "Camp name",
      "account_numeric_id": "810",
      "account_id": "<<example_advertiser_id>>",
      "account_name": "<<example_advertiser_name>>",
      "learning_state": "LEARNING_COMPLETE"
    }
  ],
  "recordCount": 2,
  "metadata": {
    "total": 2,
    "count": 2,
    "static_fields": [
      {
        "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"
      },
      {
        "id": "item_id",
        "format": null,
        "data_type": "STRING"
      },
      {
        "id": "item_name",
        "format": null,
        "data_type": "STRING"
      },
      {
        "id": "description",
        "format": null,
        "data_type": "STRING"
      },
      {
        "id": "thumbnail_url",
        "format": null,
        "data_type": "STRING"
      },
      {
        "id": "url",
        "format": null,
        "data_type": "STRING"
      },
      {
        "id": "cta",
        "format": null,
        "data_type": "STRING"
      },
      {
        "id": "performance_status",
        "format": null,
        "data_type": "STRING"
      },
      {
        "id": "item_status",
        "format": null,
        "data_type": "STRING"
      },
      {
        "id": "item_type",
        "format": null,
        "data_type": "STRING"
      },
      {
        "id": "reject_reason",
        "format": null,
        "data_type": "STRING"
      },
      {
        "id": "status_reason",
        "format": null,
        "data_type": "STRING"
      },
      {
        "id": "campaign_id",
        "format": null,
        "data_type": "STRING"
      },
      {
        "id": "campaign_name",
        "format": null,
        "data_type": "STRING"
      },
      {
        "id": "account_numeric_id",
        "format": null,
        "data_type": "STRING"
      },
      {
        "id": "account_id",
        "format": null,
        "data_type": "STRING"
      },
      {
        "id": "account_name",
        "format": null,
        "data_type": "STRING"
      },
      {
        "id": "learning_state",
        "format": null,
        "data_type": "STRING"
      }
    ]
  }
}

🚧

Request

  • The itemfilter is not supported.

📘

Response

  • Response includes item columns.
  • Response is limited to top 1,000 rows.

For ease of reading, the sample response has been shortened.

Example 2 - by_item_by_smallest_time_bucket dimension

GET /backstage/api/1.0/<<example_advertiser_id>>/reports/realtime-campaign-summary/dimensions/by_item_by_smallest_time_bucket?start_date=2023-03-28T00:00:00&end_date=2023-03-28T23:59:59&item=123456
 HTTP/1.1
Host: backstage.taboola.com
Authorization: Bearer {access-token}

{
  "timezone": "CEST",
  "results": [
    {
      "date": "2023-04-25 11:25:00.0",
      "clicks": 7,
      "visible_impressions": 215,
      "spent": 0.21,
      "cpa_actions_num": 61,
      "conversions_value": 0,
      "roas": 0,
      "vctr": 3.255813953488372,
      "vcpm": 0.98,
      "cpc": 0.03,
      "cpa": 0.003,
      "cpa_conversion_rate": 871.4285714285713,
      "item_id": "123456",
      "item_name": "Ecco",
      "thumbnail_url": "http://cdn.taboola.com/2192d8.jpg",
      "description": "Ecco la classifica",
      "cta": "NONE"
    },
    {
      "date": "2023-04-25 11:20:00.0",
      "clicks": 3,
      "visible_impressions": 210,
      "spent": 0.09,
      "cpa_actions_num": 34,
      "conversions_value": 0,
      "roas": 0,
      "vctr": 1.4285714285714286,
      "vcpm": 0.43,
      "cpc": 0.03,
      "cpa": 0.003,
      "cpa_conversion_rate": 1133.3333333333335,
      "item_id": "123456",
      "item_name": "Ecco",
      "thumbnail_url": "http://cdn.taboola.com/2192d8.jpg",
      "description": "Ecco la classifica",
      "cta": "NONE"
    },
    {
      "date": "2023-04-25 11:15:00.0",
      "clicks": 5,
      "visible_impressions": 202,
      "spent": 0.15,
      "cpa_actions_num": 15,
      "conversions_value": 0,
      "roas": 0,
      "vctr": 2.4752475247524752,
      "vcpm": 0.74,
      "cpc": 0.03,
      "cpa": 0.01,
      "cpa_conversion_rate": 300,
      "item_id": "123456",
      "item_name": "Ecco",
      "thumbnail_url": "http://cdn.taboola.com/2192d8.jpg",
      "description": "Ecco la classifica",
      "cta": "NONE"
    },
    {
      "date": "2023-04-25 11:10:00.0",
      "clicks": 3,
      "visible_impressions": 124,
      "spent": 0.09,
      "cpa_actions_num": 16,
      "conversions_value": 0,
      "roas": 0,
      "vctr": 2.4193548387096775,
      "vcpm": 0.73,
      "cpc": 0.03,
      "cpa": 0.006,
      "cpa_conversion_rate": 533.3333333333333,
      "item_id": "123456",
      "item_name": "Ecco",
      "thumbnail_url": "http://cdn.taboola.com/2192d8.jpg",
      "description": "Ecco la classifica",
      "cta": "NONE"
    }
  ],
  "recordCount": 4,
  "metadata": {
    "total": 4,
    "count": 4,
    "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"
      },
      {
        "id": "item_id",
        "format": null,
        "data_type": "STRING"
      },
      {
        "id": "item_name",
        "format": null,
        "data_type": "STRING"
      },
      {
        "id": "thumbnail_url",
        "format": null,
        "data_type": "STRING"
      },
      {
        "id": "description",
        "format": null,
        "data_type": "STRING"
      },
      {
        "id": "cta",
        "format": null,
        "data_type": "STRING"
      }
    ]
  }
}

🚧

Request

  • The itemfilter is required.

📘

Response

  • Response does not include item columns.
  • Response is not limited.

For ease of reading, the sample response has been shortened.

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"
}