Data reference

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 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.

Meta no longer returns 7-day view or 28-day view data. Meta stopped returning the 7-day view and 28-day view attribution windows in its Ads Insights API on January 12, 2026 (Meta for Developers). The (View, 7d) variants, and the (View, 28d) variants in workspaces with extended attribution, are still listed in Adriel, but Meta no longer returns data for them. For view-through conversions, use the (View, 1d) variants, which Meta still provides.

Each attribution window produces a separate metric variant. For example, purchase exists as Purchase (Click, 1d), Purchase (Click, 7d), Purchase (View, 1d), etc.

Incremental attribution

Conversion metrics also have an incremental variant, marked with the (Incremental) suffix — for example, Purchase (Incremental). Incremental attribution counts only the conversions that Meta’s models estimate were caused by the ads (Meta Business Help Center). Incremental variants are available in every workspace by default; unlike the 28-day windows, no workspace flag is needed. Which events get an (Incremental) variant depends on the event type:

Standard events — each of Meta’s 17 standard events has (Incremental) metrics on every Meta data source: conversions, conversion value, CPA, ROAS, and conversion rate.
Other actions and custom conversions — an (Incremental) metric appears only when Meta has returned an incremental value for that action or custom conversion within the last 30 days. Link Click currently has no incremental value, so it has no (Incremental) metric. Landing Page View has one on some ad accounts only.

(Incremental) metrics show blank cells with the Location breakdown and the Hourly Breakdown (see Breakdowns). Because incremental values are rounded per row, the sum of rows (for example, ad sets) can differ slightly from the total. In the Korean and Japanese UI, incremental metric names stay in English, like the other Meta conversion metrics (for example, 메타 광고: Purchase (Incremental)).

Metrics

How to read the columnsData 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 Cap	The bid cap configured for the campaigns or ad sets.	Currency	Adriel-side
Bid Strategy	The bidding strategies selected for the campaigns or ad sets.	Text	`bid_strategy`
Budget	The budget configured for the selected campaigns or ad sets.	Text	Adriel-side
Campaign Name	The name of the Meta campaign.	Text	`campaign.name`
Creative URL	The URL of the ad creative when one is available.	Text	Adriel-side
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`
Is Active	Whether the selected campaign, ad set, or ad is currently active.	Text	Adriel-side
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`
Status Text	A human-readable label for the current delivery status.	Text	Adriel-side
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 metrics (for rollup); they are no longer offered as breakdowns.

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
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`
Revenue	The purchase value attributed to the ads from Meta conversion events.	Currency	`action_values`, `conversion_values`, `catalog_segment_value`

Conversion events come from the 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); for each, a count and a value metric are generated across every enabled attribution window (see Attribution windows), plus an (Incremental) variant (see Incremental attribution). Any custom conversions active in the ad account are imported as well.

Creative Attributes

Metric	Description	Data type	API Key
Creative Image	A reference to the ad’s creative image.	Text	Adriel-side

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`
Created Date	The creation date of the Meta object represented by the report row.	Date	`created_time`
Creative Headline	The headline texts configured for the ad creative.	Array	Adriel-side
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`
Spend On Views	Spend for rows where Meta reported at least one video view.	Currency	`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`
Video Thumbnail URL	The image thumbnail for a video ad, so it can be rendered as an image (e.g. with a spreadsheet IMAGE() formula). Falls back to the ad’s regular creative image for non-video ads.	Text	`creative.thumbnail_url`, `video.thumbnails`

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`
Comscore Market	Groups results by Comscore market. Replaces DMA Region.	`comscore_market`
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 (Deprecated)	Groups results by Nielsen designated market area. Superseded by Comscore Market.	`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 values are available as metrics, not breakdowns. Meta doesn’t return UTM values; Adriel parses them from each ad’s landing URL and exposes them as metrics for rollup (see the Campaign Attributes metrics above). They are no longer offered as breakdowns.

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.

(Incremental) metrics are blank with Location and Hourly Breakdown. Meta doesn’t provide incremental values to Adriel for the Location breakdown or the Hourly Breakdown, so (Incremental) metrics show blank cells there. The widget still loads without an error.

Breakdown × level compatibility

Breakdown	Ad account	Campaign	Ad set	Ad
Age, Gender, Country, Location, State (US Only), Location Coordinate, Comscore Market, DMA Region (Deprecated), 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).

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).

Introduction

Data refresh strategy

Architecture data

Reports data

Architecture levels

Date range limits

Attribution windows

Incremental attribution

Metrics

Basic

Campaign Attributes

Campaign Structure

Click Performance

Computed Metric

Conversion Performance

Creative Attributes

Engagement

Impression Click Performance

Video Performance

Meta Ads-specific

Breakdowns

Basic

Campaign Structure

Creatives

Date

Others

Meta Ads-specific

Breakdown × level compatibility

Limitations

API references (Meta)

See also

​Introduction

​Data refresh strategy

​Architecture data

​Reports data

​Architecture levels

​Date range limits

​Attribution windows

​Incremental attribution

​Metrics

​Basic

​Campaign Attributes

​Campaign Structure

​Click Performance

​Computed Metric

​Conversion Performance

​Creative Attributes

​Engagement

​Impression Click Performance

​Video Performance

​Meta Ads-specific

​Breakdowns

​Basic

​Campaign Structure

​Creatives

​Date

​Others

​Meta Ads-specific

​Breakdown × level compatibility

​Limitations

​API references (Meta)

​See also

Introduction

Data refresh strategy

Architecture data

Reports data

Architecture levels

Date range limits

Attribution windows

Incremental attribution

Metrics

Basic

Campaign Attributes

Campaign Structure

Click Performance

Computed Metric

Conversion Performance

Creative Attributes

Engagement

Impression Click Performance

Video Performance

Meta Ads-specific

Breakdowns

Basic

Campaign Structure

Creatives

Date

Others

Meta Ads-specific

Breakdown × level compatibility

Limitations

API references (Meta)

See also