> ## 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 Meta Ads data source in Adriel.
## Introduction
Meta Ads (formerly Facebook Ads) is Meta's paid advertising platform, covering Facebook, Instagram, Messenger, and the Audience Network. It supports a wide range of campaign objectives — awareness, traffic, engagement, leads, app promotion, sales — across CPC, CPM, CPA, and oCPM payment models. Advertisers run paid social campaigns through Meta Ads Manager, and the connector imports the resulting structure and performance data via the Meta Marketing API (Graph API v25.0).
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 Meta Ads to Adriel](/data-sources/g-n/meta-ads/how-to-connect).
## Data refresh strategy
### Architecture data
Architecture covers ad accounts, campaigns, ad sets, and ads. It refreshes **every 4 hours, on the hour (UTC)**. Only campaigns created within the last **30 months** are imported.
### Reports data
Reports include daily performance metrics for ad accounts, campaigns, ad sets, and ads.
**Real-time.** Report data is fetched from Meta on demand when a dashboard loads, so the latest values are always visible. On top of that, scheduled cache refreshes keep historical data consistent across multiple time windows.
**Refresh schedule.** Reports refresh on three overlapping schedules:
* **5:00 PM UTC daily** — syncs the last **9 days** for ad account, campaign, ad set, and ad
* **11:40 PM and 6:40 AM UTC daily** — syncs the last **3 days** for ad account, campaign, ad set, and ad
* **7:30 AM UTC on the 1st and 15th of each month** — syncs the last **30 days** for ad account, campaign, ad set, and ad
## Architecture levels
Ad account → Campaign → Ad set → Ad
## Date range limits
| Breakdown | Max range |
| --------- | --------- |
| Daily | 93 days |
| Weekly | 1 year |
| Monthly | 2 years |
## Attribution windows
Meta Ads conversion metrics are reported across multiple attribution windows. The connector requests four windows by default: 7-day click, 1-day click, 7-day view, and 1-day view. When the workspace flag for extended Meta attribution is enabled, 28-day click and 28-day view windows are added; contact Adriel to enable it.
Each attribution window produces a separate metric variant. For example, `purchase` exists as `Purchase (Click, 1d)`, `Purchase (Click, 7d)`, `Purchase (View, 1d)`, and so on.
## Metrics
**How to read the columns**
**Data type** uses Adriel's vocabulary — Number, Currency, Percentage, Ratio, Duration, Date, Text, URL, Array, Boolean. **API Key** in code style like `impressions` is the literal Meta Graph API field; where the same raw field name is shared across objects (Meta returns `name` for the ad account, ad, ad set, and campaign), it's shown qualified as `object.field` (for example `account.name`) so each row stays unique; *italic* marks a value Adriel computes or derives. Some raw fields back several metrics — notably `actions` (one array Meta filters by action type) and `creative` (the ad's creative object) — so the same key can appear on multiple rows; that's the shared source field, not a duplicated entry. Currency values are reported in each ad account's configured Meta currency.
### Basic
| Metric | Description | Data type | API Key |
| ---------------- | --------------------------------------------------------------------------- | --------- | ------------------------------------ |
| Conversion Value | The total monetary value assigned to attributed conversions. | Currency | *Adriel rollup of conversion values* |
| Creative Type | The format of the ad creative, such as an image or video. | Text | `creative` |
| Lifetime Budget | The total lifetime budget configured for the selected campaigns or ad sets. | Currency | `lifetime_budget` |
| Result Indicator | The metric Meta uses to represent the result for the campaign objective. | Text | *Resolved from campaign objective* |
| Results | The number of results for the campaign's configured objective. | Number | `results` |
### Campaign Attributes
| Metric | Description | Data type | API Key |
| --------------- | ----------------------------------------------------------------------------------------- | --------- | ---------------------------- |
| Ad Account Name | The name of the Meta ad account. | Text | `account.name` |
| Ad Name | The name of the Meta ad. | Text | `ad.name` |
| Ad Set Name | The name of the Meta ad set. | Text | `adset.name` |
| Ad Spend | The estimated amount spent on the selected Meta ads during the reporting period. | Currency | `spend` |
| Bid Strategy | The bidding strategies selected for the campaigns or ad sets. | Text | `bid_strategy` |
| Campaign Name | The name of the Meta campaign. | Text | `campaign.name` |
| Daily Budget | The total daily budget configured for the selected campaigns or ad sets. | Currency | `daily_budget` |
| Ends | The scheduled end date of the campaign or ad set, when one is set. | Date | `stop_time`, `end_time` |
| Landing URL | The destination URLs that people can reach from the ads. | URL | `creative` |
| Objective | The business objectives selected for the campaigns. | Text | `objective` |
| Starts | The scheduled start date of the campaign or ad set. | Date | `start_time` |
| Status | The current delivery status of the campaign, ad set, or ad. | Text | `status`, `effective_status` |
| UTM Campaign | The UTM campaign values used to identify the promoted campaigns in destination analytics. | Text | `creative` |
| UTM Content | The UTM content values used to distinguish ads or creative variants. | Text | `creative` |
| UTM Medium | The UTM medium values used to identify the marketing channel that delivered traffic. | Text | `creative` |
| UTM Source | The UTM source values used to identify where traffic originated. | Text | `creative` |
| UTM Term | The UTM term values used to identify paid keywords or other targeting labels. | Text | `creative` |
**UTM values are parsed by Adriel, not returned by Meta.** Adriel reads the UTM query parameters from each ad's landing URL and exposes them as both metrics (for rollup) and breakdowns (for grouping).
### Campaign Structure
| Metric | Description | Data type | API Key |
| ------------- | --------------------------------------------------------------------------------------------------------------- | --------- | ------------- |
| Ad Account ID | The Meta identifier of the ad account. | Text | `account_id` |
| Ad ID | The Meta identifier of the ad. | Text | `ad_id` |
| Ad Set ID | The Meta identifier of the ad set. | Text | `adset_id` |
| Campaign ID | The Meta identifier of the campaign. | Text | `campaign_id` |
| Channel | The Meta platforms where the ads can be delivered, such as Facebook, Instagram, Messenger, or Audience Network. | Text | `targeting` |
### Click Performance
| Metric | Description | Data type | API Key |
| ---------------------- | ------------------------------------------------------------------------------------------- | --------- | ------------------------ |
| Outbound Clicks | The number of clicks on links that take people away from Meta properties. | Number | `outbound_clicks` |
| Unique Outbound Clicks | The estimated number of people who clicked a link that took them away from Meta properties. | Number | `unique_outbound_clicks` |
### Computed Metric
These are calculated by Adriel from other metrics; they have no single underlying Meta field.
| Metric | Description | Data type | API Key |
| ---------------------------------------- | --------------------------------------------------------- | ---------- | ----------------- |
| Cost Per Messaging Conversations Started | Spend divided by messaging conversations started. | Currency | *Adriel-computed* |
| Cost Per New Messaging Connections | Spend divided by new messaging connections. | Currency | *Adriel-computed* |
| Cost Per Outbound Click | Spend divided by outbound clicks. | Currency | *Adriel-computed* |
| CPR | Cost per result — spend divided by results. | Currency | *Adriel-computed* |
| Frequency | Impressions divided by reach. | Ratio | *Adriel-computed* |
| Outbound CTR | Outbound clicks divided by impressions. | Percentage | *Adriel-computed* |
| ROAS | Return on ad spend — conversion value divided by spend. | Ratio | *Adriel-computed* |
| Video Played To 100% (%) | Plays reaching 100% completion as a share of total plays. | Percentage | *Adriel-computed* |
| Video Played To 25% (%) | Plays reaching 25% completion as a share of total plays. | Percentage | *Adriel-computed* |
| Video Played To 50% (%) | Plays reaching 50% completion as a share of total plays. | Percentage | *Adriel-computed* |
| Video Played To 75% (%) | Plays reaching 75% completion as a share of total plays. | Percentage | *Adriel-computed* |
| View Rate | Video views as a share of impressions. | Percentage | *Adriel-computed* |
### Conversion Performance
| Metric | Description | Data type | API Key |
| ---------------- | ---------------------------------------------------------------------------- | ---------- | ------------------------------------------------------------- |
| Conversion Value | The purchase value attributed to the ads. | Currency | `action_values`, `conversion_values`, `catalog_segment_value` |
| Conversions | The number of purchase conversions attributed to the ads. | Number | `actions`, `conversions`, `catalog_segment_actions` |
| Result Rate | Rate of results relative to reach or impressions for the campaign objective. | Percentage | *Adriel-computed* |
| Revenue | The purchase value attributed to the ads from Meta conversion events. | Currency | `action_values`, `conversion_values`, `catalog_segment_value` |
**Conversion events come from your Pixel.** Adriel can only display conversion events that Ad Manager already receives; if a Pixel records an event but does not forward it to Ad Manager, that event will not appear in Adriel. Meta exposes 17 standard Pixel events ([Meta Pixel standard events reference](https://developers.facebook.com/docs/meta-pixel/reference)); for each, a count and a value metric are generated across every enabled attribution window (see [Attribution windows](#attribution-windows)). Any custom conversions active in the ad account are imported as well.
### Engagement
| Metric | Description | Data type | API Key |
| ----------------- | ----------------------------------------------------------------------------------------------------- | --------- | ------------------------ |
| Engagement | The total number of actions people took involving the ads. | Number | `inline_post_engagement` |
| Page Engagement | The number of actions people took on the Facebook Page and its posts that were attributed to the ads. | Number | `actions` |
| Post Comments | The number of comments attributed to the ads. | Number | `actions` |
| Post Engagement | The number of interactions with posts promoted by the ads. | Number | `actions` |
| Post Reactions | The number of reactions to posts attributed to the ads. | Number | `actions` |
| Post Saves | The number of times posts promoted by the ads were saved. | Number | `actions` |
| Post Shares | The number of times posts promoted by the ads were shared. | Number | `actions` |
| Video Impressions | The number of times ads with recorded video views were shown on screen. | Number | `impressions` |
### Impression Click Performance
| Metric | Description | Data type | API Key |
| ------------ | ------------------------------------------------------------------------------------------- | ---------- | -------------------- |
| Clicks (All) | The total number of clicks on the ads, including link clicks and other interactions. | Number | `clicks` |
| CPC | Cost per click. | Currency | *Adriel-computed* |
| CPM | Cost per thousand impressions. | Currency | *Adriel-computed* |
| CTR | Click-through rate — clicks divided by impressions. | Percentage | *Adriel-computed* |
| Impressions | The number of times the ads were shown on screen. | Number | `impressions` |
| Link Clicks | The number of clicks on links to destinations or experiences on or outside Meta properties. | Number | `inline_link_clicks` |
| Reach | The estimated number of people who saw the ads at least once. | Number | `reach` |
### Video Performance
| Metric | Description | Data type | API Key |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------- | --------- | -------------------------------- |
| 15s Video Plays | The number of times a video played for at least 15 seconds, or nearly its full length when shorter. | Number | `video_15_sec_watched_actions` |
| 30s Video Plays | The number of times a video played for at least 30 seconds, or nearly its full length when shorter. | Number | `video_30_sec_watched_actions` |
| 3s Video Plays | The number of video views that Meta records as video-view actions, typically after at least three seconds of playback. | Number | `actions` |
| ThruPlays | The number of times a video was played to completion, or for at least 15 seconds when the video was longer than 15 seconds. | Number | `video_thruplay_watched_actions` |
| Video Play | The number of times a video started playing, excluding replays for the same impression. | Number | `video_play_actions` |
| Video Played To 100% (Views) | The number of times a video was played through its full length, including plays that skipped to the end. | Number | `video_p100_watched_actions` |
| Video Played To 25% (Views) | The number of times a video was played through at least 25% of its length, including plays that skipped to that point. | Number | `video_p25_watched_actions` |
| Video Played To 50% (Views) | The number of times a video was played through at least 50% of its length, including plays that skipped to that point. | Number | `video_p50_watched_actions` |
| Video Played To 75% (Views) | The number of times a video was played through at least 75% of its length, including plays that skipped to that point. | Number | `video_p75_watched_actions` |
| Views | The number of video-view actions attributed to the ads. | Number | `actions` |
### Meta Ads-specific
These metrics exist only for Meta Ads and aren't part of any cross-connector category. Every group above is a standard category shared with other connectors.
| Metric | Description | Data type | API Key |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------- | -------------------------------- |
| Ad Spend | The estimated amount spent on the selected Meta ads during the reporting period. | Currency | `spend` |
| Blocked Messaging Connections | The number of times people blocked messaging conversations after interacting with the ads. | Number | `actions` |
| Cost Per Unique Outbound Click | The estimated average amount spent for each unique outbound click. | Currency | `cost_per_unique_outbound_click` |
| CPV | The average amount spent for each video view. | Currency | `spend`, `actions` |
| Estimated Ad Recall Rate | The estimated percentage of people reached who would remember seeing the ad if asked within two days. | Percentage | `estimated_ad_recall_rate` |
| Estimated Ad Recallers | The estimated number of people who would remember seeing the ad if asked within two days. | Number | `estimated_ad_recallers` |
| Frequency | The estimated average number of times each person saw the ads. | Ratio | `frequency` |
| Inline Link Clicks | The number of clicks on links to destinations or experiences on or outside Meta properties. | Number | `inline_link_clicks` |
| Inline Post Engagement | The total number of actions people took involving the ads. | Number | `inline_post_engagement` |
| Instagram Profile Visits | The number of visits to an Instagram profile attributed to the ads. | Number | `instagram_profile_visits` |
| Lead | The number of lead actions attributed to the ads. | Number | `actions` |
| Messaging Conversations Started | The number of messaging conversations started within seven days of an attributed interaction with the ads. | Number | `actions` |
| New Messaging Connections | The number of first replies sent in messaging conversations attributed to the ads. | Number | `actions` |
| Page Likes | The number of Facebook Page likes attributed to the ads. | Number | `actions` |
| Photo Views | The number of photo views attributed to the ads. | Number | `actions` |
| Post Comment | The text of a top-level Facebook or Instagram comment associated with an ad. | Text | `message`, `text` |
| Result | The number of outcomes achieved by the ad based on its selected objective and settings. | Number | `results` |
| Result Type | The type of outcome used for the reported result, based on the ad objective and settings. | Text | `results` |
| Social Spend | The amount spent on ads shown with social information, such as a friend's interaction with a Page. | Currency | `social_spend` |
| Unique Clicks | The estimated number of people who clicked the ads. | Number | `unique_clicks` |
| Unique Inline Link Clicks | The estimated number of people who clicked a link in the ads. | Number | `unique_inline_link_clicks` |
| Unique Outbound CTR | The estimated percentage of people reached who performed an outbound click. | Percentage | `unique_outbound_clicks_ctr` |
| Video Average Play Time | The average time, in seconds, that the videos were played for each impression, including replays. | Duration | `video_avg_time_watched_actions` |
## Breakdowns
### Basic
| Breakdown | Description | API Key |
| --------- | -------------------------------------- | ----------------- |
| Channel | Groups results by advertising channel. | *Adriel-assigned* |
### Campaign Structure
| Breakdown | Description | API Key |
| ------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------- |
| Ad Name | Groups results by ad name. | `ad_name` |
| Ad Set Name | Groups results by ad set name. | `adset_name` |
| Campaign Name | Groups results by campaign name. | `campaign_name` |
| Objective | Groups results by the business objective selected for the campaign. | `objective` |
| Platform | Groups results by Meta publishing platform, such as Facebook, Instagram, Messenger, or Audience Network. | `publisher_platform` |
| Status | Groups results by the current delivery status of the campaign, ad set, or ad. | `status`, `effective_status` |
### Creatives
Adriel post-processes ad creatives to generate these breakdowns.
| Breakdown | Description | API Key |
| ----------------------- | --------------------------------------------------------------- | ---------- |
| Ad Copy | Groups results by words identified in the ad creative. | `creative` |
| Color Clustering | Groups results by similar colors identified in the ad creative. | `creative` |
| Creative Image | Groups results by the unique visual identifier of the ad image. | `creative` |
| Emoji Analysis | Groups results by emojis identified in the ad creative. | `creative` |
| Facebook Creative Image | Groups results by the image used in the ad creative. | `creative` |
### Date
Meta's API returns daily records; all time-grouping breakdowns are Adriel-side aggregations of the same underlying daily data.
| Breakdown | Description | API Key |
| ----------------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------- |
| Auto Time Breakdown | Automatically groups results by an appropriate time interval for the selected date range. | *Adriel-side* |
| Daily Breakdown | Groups results by calendar day. | `date_start`, `date_stop` |
| Hourly Breakdown | Groups results by hour using the audience's time zone. | `hourly_stats_aggregated_by_audience_time_zone` |
| Monthly Breakdown | Groups results by calendar month. | `date_start`, `date_stop` |
| Quarterly Breakdown | Groups results by calendar quarter. | `date_start`, `date_stop` |
| Week Date Breakdown | Groups results by the date representing each reporting week. | `date_start`, `date_stop` |
| Week Number Breakdown (W#) | Groups results by week number in the year. | *Adriel-side* |
| Weekly Breakdown (Start: Mon) | Groups results by calendar week. | `date_start`, `date_stop` |
| Weekly Breakdown (Start: Sun) | Groups results into weeks running from Sunday through Saturday. | `date_start`, `date_stop` |
| Yearly Breakdown | Groups results by calendar year. | `date_start`, `date_stop` |
### Others
| Breakdown | Description | API Key |
| ----------- | --------------------------------------------- | ------------- |
| No Grouping | Shows all results as a single combined group. | *Adriel-side* |
### Meta Ads-specific
These breakdowns exist only for Meta Ads and aren't part of any cross-connector category. Every group above is a standard category shared with other connectors.
| Breakdown | Description | API Key |
| -------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------- |
| Ad | Groups results by Meta ad. | `ad_id` |
| Ad Account | Groups results by Meta ad account. | `account_id` |
| Ad Set | Groups results by Meta ad set. | `adset_id` |
| Age | Groups results by the age range of the people who saw the ads. | `age` |
| Campaign | Groups results by Meta campaign. | `campaign_id` |
| Country | Groups results by the country where the people who saw the ads were located. | `country` |
| Creative Body | Groups results by the primary body text used in the ad creative. | `body_asset` |
| Creative Description | Groups results by the description text used in the ad creative. | `description_asset` |
| Creative Headline | Groups results by the title text used in the ad creative. | `title_asset` |
| Device Target | Groups results by the device platform on which the ads were shown. | `device_platform` |
| DMA Region | Groups results by designated market area. | `dma` |
| Gender | Groups results by the reported gender of the people who saw the ads. | `gender` |
| Location | Groups results by the region where the people who saw the ads were located. | `region` |
| Location Coordinate | Groups results by the combined country and region reported for the people who saw the ads. | `country`, `region` |
| Operating System | Groups results by the device on which the ad impression occurred. | `impression_device` |
| Placement | Groups results by the Meta platform and placement position where the ads were shown. | `publisher_platform`, `platform_position` |
| Post Comment ID | Groups results by individual top-level Facebook or Instagram comments associated with an ad. | `id` |
| State (US Only) | Groups results by U.S. state using Meta's country and region data. | `country`, `region` |
| UTM Campaign | Groups results by the UTM campaign value used in destination URLs. | `creative` |
| UTM Content | Groups results by the UTM content value used in destination URLs. | `creative` |
| UTM Medium | Groups results by the UTM medium value used in destination URLs. | `creative` |
| UTM Source | Groups results by the UTM source value used in destination URLs. | `creative` |
| UTM Term | Groups results by the UTM term value used in destination URLs. | `creative` |
**UTM breakdowns are Adriel-parsed.** Meta doesn't return UTM values; Adriel parses them from each ad's landing URL and exposes them for grouping.
**`Post Comment ID` is not cached.** Queries using the Post Comment ID breakdown always hit Meta live and may run slower than cache-backed queries.
### Breakdown × level compatibility
| Breakdown | Ad account | Campaign | Ad set | Ad |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | -------- | ------ | ------------------------- |
| Age, Gender, Country, Location, State (US Only), Location Coordinate, DMA Region, Device Target, Placement, Creative Headline / Description / Body, Creative Image, Hourly | Yes | Yes | No | No |
| Operating System | Yes | Yes | Yes | Yes |
| Post Comment ID | Yes *(channel filter required)* | — | — | Yes *(top-level ad only)* |
**Breakdown × level incompatibility.** Most breakdowns cannot be queried at the ad set or ad level due to Meta API constraints. Attempting to do so returns `INVALID_DIMENSIONS_COMBINATION` ([Meta Insights breakdowns](https://developers.facebook.com/docs/marketing-api/insights/breakdowns)).
## Limitations
* **30-month campaign recency filter** — only campaigns created within the last 30 months are imported; older campaigns are not available in the connector.
* **No deleted-data exclusion** — historical data for deleted campaigns / ad sets / ads is preserved.
* **No data-size limit** — the connector adaptively chunks wide queries; there is no hard row-count cap on a single query.
* **No historical date-range limit** on report data specifically — the practical limit is the 30-month campaign recency filter above, plus Meta API-side limits (typically 37 months of historical data for aggregate metrics — [Meta Marketing API Insights limits & best practices](https://developers.facebook.com/docs/marketing-api/insights/best-practices/)).
## API references (Meta)
* [Meta Marketing API Insights](https://developers.facebook.com/docs/marketing-api/insights/)
* [Campaign insights reference](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign-group/insights)
* [Ad set insights reference](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign/insights)
* [Ad insights reference](https://developers.facebook.com/docs/marketing-api/reference/adgroup/insights/)
* [Generic breakdowns](https://developers.facebook.com/docs/marketing-api/insights/breakdowns?locale=en_US#genericbreakdowns)
* [Insights API breakdowns](https://developers.facebook.com/docs/marketing-api/insights/breakdowns?locale=en_US#insights-api-breakdowns)
## See also
* [How to connect Meta Ads to Adriel](/data-sources/g-n/meta-ads/how-to-connect) (paired how-to)
* [Facebook Page Organic data reference](/data-sources/a-f/facebook-page-organic/data-reference) — for organic Page metrics
* [Instagram Organic data reference](/data-sources/g-n/instagram-organic/data-reference) — for organic Instagram metrics