Data reference - Adriel Knowledge Base

Introduction

Taboola is a global native advertising platform that distributes sponsored content and video ads across publisher sites. The connector pulls campaign architecture and performance from the Taboola Backstage API for the accounts selected during connection setup, and auto-detects whether each account is a standard content-discovery account or a video account so it can expose the right metric set. As a marketing connector, metrics, breakdowns, and currencies are standardized so widgets can aggregate across sources without additional configuration. To connect this data source, see How to connect Taboola to Adriel.

Data refresh strategy

Architecture data

Architecture covers accounts, campaigns, and items (sponsored ads). It refreshes twice daily at 4:00 PM UTC and 5:00 AM UTC.

Reports data

Reports include daily performance for accounts, campaigns, and items. Real-time. Standard accounts are queried live from Taboola when a dashboard loads, so the latest values are available on demand. Video accounts are served from a daily cache to keep video reporting performant, so their numbers are current as of the most recent sync. Refresh schedule. Background syncs run at 0 minutes past the hour, every 6 hours (UTC), syncing the last 30 days for the campaign and ad-set breakdowns.

Architecture levels

Account → Campaign → Item (ad)

Date range limits

To keep query sizes manageable, date breakdowns are capped by granularity:

Breakdown	Max range
Daily	93 days
Weekly	1 year
Monthly	2 years

Data requested beyond these windows may be truncated.

Metrics

How to read the columns Data type uses this vocabulary: Number, Currency, Percentage, Ratio, Duration, Date, Text, URL, Array, Boolean. API Key in code style like impressions is the literal Taboola Backstage field name. Italic text describes how a value is produced when it doesn’t map cleanly to a single API field.

Reach & impressions

Metric	Description	Data type	API Key
Impressions	Total times ads were displayed, regardless of user interaction.	Number	`impressions`
Reach	Unique users who saw the ad at least once.	Number	Taboola report field
Video impressions	Number of times video creatives started displaying.	Number	`impressions`

Click performance

Metric	Description	Data type	API Key
Clicks (all)	Total clicks, including link, social, and other interactions.	Number	`clicks`
Link clicks	Number of times users clicked on the ad.	Number	`clicks`
CTR	Click-through rate, calculated by Adriel from aggregated clicks and impressions.	Percentage	`ctr`
CPC	Cost per click, calculated by Adriel from aggregated spend and clicks.	Currency	`cpc`

Cost & spend

Currency values are reported in each Taboola account’s configured currency. If the account currency differs from the Adriel workspace currency, costs are converted to the workspace currency using the current day’s exchange rate.

Metric	Description	Data type	API Key
Ad spend	Total amount spent on ads during the reporting period.	Currency	`spent`
CPM	Cost per thousand impressions, calculated by Adriel from aggregated spend and impressions.	Currency	`cpm`
CPR	Cost per result — spend divided by the desired outcomes.	Currency	Adriel-computed

Engagement

Metric	Description	Data type	API Key
Engagement	Any user interaction with the ad: clicks, reactions, shares, and similar.	Number	Taboola report field
Post engagement	Total engagements on the post-style ad.	Number	Taboola report field
Post reactions	Reactions on the post.	Number	Taboola report field
Post comments	Comments on the post.	Number	Taboola report field
Post shares	Shares of the post.	Number	Taboola report field
Post saves	Saves of the post.	Number	Taboola report field

Video performance

Video metrics populate for video accounts, which the connector detects and reports from a daily cache.

Metric	Description	Data type	API Key
Video Play	Any play of the video, regardless of duration.	Number	Taboola video metric
Views	Aggregated count of all qualified video views.	Number	Taboola video metric
2s Video Plays	Views where the video played for at least two seconds.	Number	Taboola video metric
3s Video Plays	Views of at least three continuous seconds.	Number	Taboola video metric
6s Video Plays	Views of at least six continuous seconds.	Number	Taboola video metric
15s Video Plays	Views lasting at least fifteen continuous seconds.	Number	Taboola video metric
30s Video Plays	Views lasting 30 seconds, or the entire video if shorter.	Number	Taboola video metric
Thru Plays	Video viewed to ≥97% or 15 seconds, whichever comes first.	Number	Taboola video metric
Video Played To 25% (Views)	Plays reaching 25% of video length.	Number	Taboola video metric
Video Played To 50% (Views)	Plays reaching 50% of video length.	Number	Taboola video metric
Video Played To 75% (Views)	Plays reaching 75% of video length.	Number	Taboola video metric
Video Played To 100% (Views)	Plays reaching 100% of video length.	Number	Taboola video metric

Conversion performance

Metric	Description	Data type	API Key
Conversions	Attributed actions matching the defined conversion events. Defaults to “Purchase” when no specific event is set.	Number	Taboola report field
Conversion value	Monetary value of attributed conversions.	Currency	`conversions_value`
Revenue	Monetary value of attributed conversions. Defaults to “Purchase” when no specific event is set.	Currency	Taboola report field
All Conversions (Google)	Count of every conversion action recorded for the element.	Number	Taboola report field
Results	Count of the campaign’s desired outcomes.	Number	Taboola report field
Result rate	Results as a rate over the qualifying interactions.	Percentage	`cvr`

Dynamic conversions

Any conversion events tracked in the ad account are imported automatically. Each imported event appears on the dashboard only while the underlying event is active in the account, and for every imported event a set of derived KPIs is generated.

Metric	Description	Data type	API Key
Taboola: [conversion_name]	Number of conversions tracked for the given event.	Number	Taboola report field (per event)
Taboola: [conversion_name]: Conversion value	Conversion value for the given event.	Currency	Taboola report field (per event)
Taboola: [conversion_name]: CVR	Conversion rate for the given event.	Percentage	Adriel-computed (conversions ÷ clicks)
Taboola: [conversion_name]: CPA	Cost per action for the given event.	Currency	Adriel-computed (spend ÷ conversions)
Taboola: [conversion_name]: ROAS	Return on ad spend for the given event.	Ratio	Adriel-computed (conversion value ÷ spend)

Budget & schedule

Currency values follow each account’s configured currency, converted to the workspace currency at the current day’s rate where they differ.

Metric	Description	Data type	API Key
Budget	Budget set on the campaign or ad set (daily or lifetime).	Currency	`daily_cap`
Daily budget	Daily budget set on the campaign or ad set.	Currency	`daily_cap`
Lifetime Budget	Total budget allocated for the campaign’s entire lifetime.	Currency	Taboola report field
Bid Cap	Bid cap set on the ad set or campaign.	Text	Taboola report field
Bid strategy	Bid strategy set on the ad set or campaign.	Text	`cpc`
Starts	Campaign or ad set start date.	Date	`start_date`
Ends	Campaign or ad set end date.	Date	`end_date`

UTM tracking

UTM values are parsed by Adriel from each ad’s configuration or landing URL, not returned by Taboola.

Metric	Description	Data type	API Key
UTM Source	Parsed `utm_source` parameter.	Text	Adriel-parsed
UTM Medium	Parsed `utm_medium` parameter.	Text	Adriel-parsed
UTM Campaign	Parsed `utm_campaign` parameter.	Text	Adriel-parsed
UTM Content	Parsed `utm_content` parameter.	Text	Adriel-parsed
UTM Term	Parsed `utm_term` parameter.	Text	Adriel-parsed

Campaign structure metadata

Metric	Description	Data type	API Key
Ad account name	Name of the account.	Text	`name`
Campaign name	Campaign name.	Text	`name`
Ad set name	Ad set name.	Text	`name`
Ad name	Item (ad) name.	Text	`title`, `custom_data.creative_name`
Keyword Name	Keyword name (search campaigns only).	Text	Taboola report field
Channel	Channel (platform) where the ad is published.	Text	Taboola report field
Objective	Campaign objective.	Text	`marketing_objective`
Status	Campaign, ad set, or item status.	Text	`status`
Creative Type	Format of the item (ad).	Text	Taboola report field
Creative URL	Destination URL of the item (ad).	URL	`url`

Breakdowns

Account & campaign structure

Breakdown	Description	API Key
Ad account	Group by Taboola account.	`name`
Campaign	Group by campaign.	`name`
Ad set	Group by ad set.	`name`
Ad	Group by sponsored item.	`title`, `custom_data.creative_name`
Campaign name	Group by campaign name.	`name`
Ad set name	Group by ad set name.	`name`
Ad name	Group by item (ad) name.	`title`, `custom_data.creative_name`

Publisher, audience & geography

Breakdown	Description	API Key
Site	Group by publisher site.	`site_breakdown`
Country	Split reports by impression location (two-letter country code).	`country_breakdown`
Device target	Group by device platform.	`platform_breakdown`
Audience	Group by user segment.	`user_segment_breakdown`

Status & objective

Breakdown	Description	API Key
Objective	Group campaigns by their objective.	`marketing_objective`
Status	Group by campaign, ad set, or item status.	`status`

Creative analysis

Adriel post-processes ad creatives to generate these breakdowns.

Breakdown	Description
Creative image	Auto-clusters identical or visually similar creative images to group their performance.
Color Clustering	Groups creative images by dominant visual color.
Emoji Analysis	Groups ads by the emojis present in the ad copy.
Ad copy	Groups ads that share the same ad copy.

Time & date grouping

Taboola returns daily records; Adriel aggregates them into these views for reporting.

Breakdown	Description
Auto Time Breakdown	Automatically picks the best granularity for the date range.
Daily breakdown	Split reports by day. Limited to a maximum of 93 days.
Weekly breakdown (Start: Mon)	Split reports by week, starting Monday. Limited to a maximum of 1 year.
Weekly breakdown (Start: Sun)	Split reports by week, starting Sunday. Limited to a maximum of 1 year.
Week date breakdown	Group results by the day of the week the impression occurred. Limited to a maximum of 93 days.
Week Number Breakdown (W#)	Split by week number in the year.
Monthly breakdown	Split reports by calendar month.
Quarterly breakdown	Split reports by calendar quarter.
Yearly breakdown	Split reports by calendar year.

For weekly, monthly, quarterly, and yearly breakdowns, if the date range does not align with the start and end of the period, the full period is still displayed, while the Total row continues to reflect the selected date range.

Overview

These groupings are standardized by Adriel for cross-connector rollup.

Breakdown	Description
No Grouping	Do not break down; return one aggregated row.
Channel	Group by the channel (platform) where the ad ran.
Platform	Group results by the platform on which the ads were broadcast.

Limitations

Two account modes, auto-detected. Each Taboola account is standard (content discovery) or video at the platform level. The connector detects the mode and exposes the appropriate metric set. A data source cannot switch modes; mode changes require reconfiguration in Taboola.
Video accounts use a daily cache. Video reporting is served from a daily cache, so figures are accurate as of the latest sync. Standard accounts query Taboola live on every dashboard load.
One App ID, many data sources. A single App ID and App Secret pair can fan out to multiple data sources, one per selected account. Accounts are added or removed by editing the connection.
Currency follows the account. Spend and conversion value are reported in each account’s configured currency, converted to the workspace currency at the current day’s rate where they differ.
Dynamic conversions vary per account. Conversion events are imported automatically and appear only while the underlying event is active in the account, so available conversion metrics differ between accounts.
Deleted elements are not returned. After a campaign, ad set, or item is deleted in Taboola, its data is no longer provided.
Date-range caps. Daily, weekly, and monthly breakdowns are capped as described under Date range limits; data outside those windows may be truncated.

API references

Taboola Backstage API (Backstage API v1.0)

​Introduction

​Data refresh strategy

​Architecture data

​Reports data

​Architecture levels

​Date range limits

​Metrics

​Reach & impressions

​Click performance

​Cost & spend

​Engagement

​Video performance

​Conversion performance

​Dynamic conversions

​Budget & schedule

​UTM tracking

​Campaign structure metadata

​Breakdowns

​Account & campaign structure

​Publisher, audience & geography

​Status & objective

​Creative analysis

​Time & date grouping

​Overview

​Limitations

​API references

​See also

Introduction

Data refresh strategy

Architecture data

Reports data

Architecture levels

Date range limits

Metrics

Reach & impressions

Click performance

Cost & spend

Engagement

Video performance

Conversion performance

Dynamic conversions

Budget & schedule

UTM tracking

Campaign structure metadata

Breakdowns

Account & campaign structure

Publisher, audience & geography

Status & objective

Creative analysis

Time & date grouping

Overview

Limitations

API references

See also