> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adriel.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Data reference
> Metrics, breakdowns, refresh cadence, and limits for the Taboola data source in Adriel.
## 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-sources/o-z/taboola/how-to-connect).
## 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](#date-range-limits); data outside those windows may be truncated.
## API references
* [Taboola Backstage API](https://developer.taboola.com/backstage-api/reference) (Backstage API v1.0)
## See also
* [How to connect Taboola to Adriel](/data-sources/o-z/taboola/how-to-connect) (paired how-to)
* [Outbrain Ads data reference](/data-sources/o-z/outbrain-ads/data-reference) — the other major native advertising platform