Facebook Fields and Dimensions
Last updated on Jul 18, 2025
On This Page
The following information lists all the fields that you can include in your Facebook Ads custom reports in Hevo. The fields are grouped as defined in the Meta Marketing API and categorized as:
-
Fields (Metrics): Numeric values that represent performance metrics or user actions such as impressions, clicks, spend, conversions.
-
Dimensions: Attributes, such as age, gender, device, or region, that are used to break down or filter the metrics data.
Hevo supports fetching the following data categories from the API:
-
AdGroup Insights: Provides performance and generic metadata such as impressions, clicks, spend, campaign names, IDs, and high-level breakdowns. Read Ad Insights.
-
Ads Action Stats: Provides conversion-related data such as purchases, leads, return on ad spend (ROAS), and action-specific breakdowns. Read Ads Action Stats.
List of AdGroup Insights Fields and Dimensions
Fields
The following table lists the fields available for AdGroup Insights, along with their common names and descriptions:
| Field | Field Name | Description |
|---|---|---|
| action_attribution_windows | Action Attribution Windows | The attribution window for the actions. For example, 28d_click means the API returns all actions that happened 28 days after someone clicked on the ad. The default option means “7d_click”. |
| action_breakdowns | Action Breakdowns | How to break down action results. Supports more than one breakdown. The default value is “action_type”. |
| action_report_time | Action Report Time | Determines the report time of action stats. For example, if a person saw the ad on January 1 but converted on January 2, when you query the API with action_report_time=impression, you see a conversion on January 1. When you query the API with action_report_time=conversion, you see a conversion on January 2. |
| action_values | Action Values | The total value of all conversions attributed to your ads. |
| actions | Actions | The total number of actions people took that are attributed to your ads. Actions may include engagement, clicks or conversions. |
| ad_name | Ad Name | The name of the ad you’re viewing is reporting. |
| adset_id | Adset Id | The unique ID of the ad set you’re viewing in reporting. An ad set is a group of ads that share the same budget, schedule, delivery optimization, and targeting. |
| adset_name | Adset Name | The name of the ad set you’re viewing in reporting. An ad set is a group of ads that share the same budget, schedule, delivery optimization, and targeting. |
| attribution_setting | Attribution Setting | The default attribution window to be used when the attribution result is calculated. Each ad set has its own attribution setting value. The attribution setting for a campaign or an account is calculated based on existing ad sets. Returns mixed, indicating multiple attribution settings, skan, indicating SKAdNetwork attribution of iOS 14 app install campaigns, and na, indicating no ad set in a campaign or account. The attribution_setting field only returns values when use_unified_attribution_setting is set to true. |
| breakdowns | Breakdowns | How to break down the result. For more than one breakdown, only certain combinations are available: See Combining Breakdowns and the Breakdowns page. The option impression_device cannot be used by itself. |
| buying_type | Buying Type | The method by which you pay for and target ads in your campaigns: through dynamic auction bidding, fixed-price bidding, or reach and frequency buying. This field is currently only visible at the campaign level. |
| campaign_id | Campaign Id | The unique ID number of the ad campaign you’re viewing in reporting. Your campaign contains ad sets and ads. |
| campaign_name | Campaign Name | The name of the ad campaign you’re viewing is reporting. Your campaign contains ad sets and ads. |
| canvas_avg_view_percent | Canvas Avg View Percent | The average percentage of the Instant Experience that people saw. An Instant Experience is a screen that opens after someone interacts with your ad on a mobile device. It may include a series of interactive or multimedia components, including video, images, a product catalog, and more. |
| canvas_avg_view_time | Canvas Avg View Time | The average total time, in seconds, that people spent viewing an Instant Experience. An Instant Experience is a screen that opens after someone interacts with your ad on a mobile device. It may include a series of interactive or multimedia components, including video, images, product catalog, and more. |
| catalog_segment_value | Catalog Segment Value | The total value of all conversions from your catalog segment attributed to your ads. |
| clicks | Clicks | The number of clicks on your ads. |
| conversion_rate_ranking | Conversion Rate Ranking | A ranking of your ad’s expected conversion rate. Your ad is ranked against ads with your optimization goal that compete for the same audience. Possible values include BELOW_AVERAGE_10, BELOW_AVERAGE_20, BELOW_AVERAGE_35, AVERAGE, ABOVE_AVERAGE, or UNKNOWN if there’s not enough information about the ad. This metric is an ad relevance diagnostic and does not apply to campaigns or ad sets, only ads. |
| conversion_values | Conversion Values | The total value of all conversions across all channels, such as website, mobile app, offline, and on Facebook, attributed to your ads. Visit the Ads Action Stats reference for a list of conversion values. |
| conversions | Conversions | The total number of conversions across all channels, such as website, mobile app, offline, and on Facebook, attributed to your ads. Visit the Ads Action Stats reference for a list of conversions. |
| converted_product_quantity | Converted Product Quantity | The number of products purchased, which are recorded by your merchant partner’s pixel or app SDK for a given product ID, and driven by your ads. This number has to be used together with the converted product ID breakdown. |
| converted_product_value | Converted Product Value | The value of purchases recorded by your merchant partner’s pixel or app SDK for a given product ID and driven by your ads. It has to be used together with the converted product ID breakdown. |
| cost_per_conversion | Cost Per Conversion | The average cost of a conversion across all channels, such as website, mobile app, offline, and on Facebook. Conversions include contact, customize_product, donate, find_location, schedule, start_trial, submit_application, subscribe, recurring_subscription_payment, cancel_subscription, ad_click, ad_impression. |
| cost_per_estimated_ad_recallers | Cost Per Estimated Ad Recallers | The average cost for each estimated ad recall lift. This metric is only available for assets in the Brand awareness, Post engagement, and Video views Objectives. It is estimated and in development. |
| cost_per_inline_link_click | Cost Per Inline Link Click | The average cost of each inline link click. |
| cost_per_inline_post_engagement | Cost Per Inline Post Engagement | The average cost of each inline post engagement. |
| cost_per_outbound_click | Cost Per Outbound Click | The average cost for each outbound click. |
| cost_per_thruplay | Cost Per Thruplay | The average cost for each ThruPlay. This metric is in development. |
| cost_per_unique_click | Cost Per Unique Click | The average cost for each unique click (all). This metric is estimated. |
| cost_per_unique_inline_link_click | Cost Per Unique Inline Link Click | The average cost of each unique inline link click. This metric is estimated. |
| cost_per_unique_outbound_click | Cost Per Unique Outbound Click | The average cost for each unique outbound click. This metric is estimated. |
| cpc | Cpc | The average cost for each click (all). |
| cpm | Cpm | The average cost for 1,000 impressions. |
| cpp | Cpp | The average cost to reach 1,000 people. This metric is estimated. |
| ctr | Ctr | The percentage of times people saw your ad and performed a click (all). |
| date_preset | Date Preset | Represents a relative time range. This field is ignored if time_range or time_ranges is specified. |
| date_start | Date Start | The start date for your data. This is controlled by the date range you have selected for your reporting view. |
| date_stop | Date Stop | The end date for your data. This is controlled by the date range you have selected for your reporting view. |
| dda_results | Dda Results | Estimated incremental conversions caused by a given ad based on the objective and settings you selected. This is a modeled value. |
| default_summary | Default Summary | Determine whether to return a summary. If summary is set, this parameter is ignored; otherwise, a summary section with the same fields as specified by fields will be included in the summary section. |
| engagement_rate_ranking | Engagement Rate Ranking | A ranking of your ad’s expected engagement rate. Engagement includes all clicks, likes, comments, and shares. Your ad is ranked against ads that competed for the same audience. Possible values include BELOW_AVERAGE_10, BELOW_AVERAGE_20, BELOW_AVERAGE_35, AVERAGE, ABOVE_AVERAGE, or UNKNOWN if there’s not enough information about the ad. This metric is an ad relevance diagnostic and does not apply to campaigns or ad sets, only ads. |
| estimated_ad_recall_rate | Estimated Ad Recall Rate | The rate at which an estimated number of additional people, when asked, would remember seeing your ads within 2 days. This metric is only available for assets in the Brand awareness, Post engagement, and Video views Objectives. It is estimated and in development. |
| estimated_ad_recallers | Estimated Ad Recallers | An estimate of the number of additional people who may remember seeing your ads, if asked, within 2 days. This metric is only available for assets in the Brand awareness, Post engagement, and Video views Objectives. This metric is estimated and in development. |
| export_columns | Export Columns | Select fields on the exporting report file. It is an optional parameter. Exporting columns are equal to the param fields, if you leave this param blank |
| export_format | Export Format | Set the format of exporting the report file. If the export_format is set, the Report file is asynchronously generated. It expects “xls”. |
| export_name | Export Name | Set the file name of the exporting report. |
| frequency | Frequency | The average number of times each person saw your ad. This metric is estimated. |
| full_view_impressions | Full View Impressions | The number of Full Views on your Page’s posts as a result of your ad. |
| full_view_reach | Full View Reach | The number of people who performed a Full View on your Page’s post as a result of your ad. |
| impressions | Impressions | The number of times your ads were on screen. |
| inline_link_click_ctr | Inline Link Click Ctr | The percentage of time people saw your ads and performed an inline link click. |
| inline_link_clicks | Inline Link Clicks | The number of clicks on links to select destinations or experiences, on or off Facebook-owned properties. Inline link clicks use a fixed 1-day click attribution window. |
| inline_post_engagement | Inline Post Engagement | The total number of actions that people take involving your ads. Inline post engagements use a fixed 1-day click attribution window. |
| instant_experience_clicks_to_open | Instant Experience Clicks To Open | The number of clicks on your ad that open an Instant Experience. This metric is in development. |
| instant_experience_clicks_to_start | Instant Experience Clicks To Start | The number of times an interactive component in an Instant Experience starts. This metric is in development. |
| instant_experience_outbound_clicks | Instant Experience Outbound Clicks | The number of clicks on links in an Instant Experience that take people off Facebook-owned properties. This metric is in development. |
| mobile_app_purchase_roas | Mobile App Purchase Roas | The total return on ad spend (ROAS) from mobile app purchases. This is based on the value that you assigned when you set up the app event. |
| objective | Objective | The objective reflects the goal you want to achieve with your advertising. It may be different from the selected objective of the campaign in some cases. |
| optimization_goal | Optimization Goal | The optimization goal you selected for your ad or ad set. Your optimization goal reflects what you want to optimize for the ads. |
| outbound_clicks | Outbound Clicks | The number of clicks on links that take people off Facebook-owned properties. |
| outbound_clicks_ctr | Outbound Clicks Ctr | The percentage of times people saw your ad and performed an outbound click. |
| place_page_name | Place Page Name | The name of the page involved in the impression or click. Has to be used together with the Business Locations breakdown. |
| purchase_roas | Purchase Roas | The total return on ad spend (ROAS) from purchases. This is based on information received from one or more of your connected Facebook Business Tools and attributed to your ads. |
| qualifying_question_qualify_answer_rate | Qualifying Question Qualify Answer Rate | qualifying_question_qualify_answer_rate |
| quality_ranking | Quality Ranking | A ranking of your ad’s perceived quality. Quality is measured using feedback on your ads and the post-click experience. Your ad is ranked against ads that compete for the same audience. Possible values include BELOW_AVERAGE_10, BELOW_AVERAGE_20, BELOW_AVERAGE_35, AVERAGE, ABOVE_AVERAGE, or UNKNOWN if there’s not enough information about the ad. This metric is an ad relevance diagnostic and does not apply to campaigns or ad sets, only ads. |
| reach | Reach | The number of people who saw your ads at least once. Reach is different from impressions, which may include multiple views of your ads by the same people. This metric is estimated. |
| social_spend | Social Spend | The total amount you’ve spent so far for your ads is shown with social information such as Jane Doe likes this. |
| spend | Spend | The estimated total amount of money you’ve spent on your campaign, ad set, or ad during its schedule. This metric is estimated. |
| unique_clicks | Unique Clicks | The number of people who performed a click (all). This metric is estimated. |
| unique_ctr | Unique Ctr | The percentage of people who saw your ad and performed a unique click (all). This metric is estimated. |
| unique_inline_link_click_ctr | Unique Inline Link Click Ctr | The percentage of times people saw your ad and performed a link click. Inline click-through rate uses a fixed 1-day click attribution window. This metric is estimated. |
| unique_inline_link_clicks | Unique Inline Link Clicks | The number of people who performed an inline link click. This metric is estimated. |
| unique_link_clicks_ctr | Unique Link Clicks Ctr | The percentage of people who saw your ad and performed a link click. This metric is estimated. |
| unique_outbound_clicks | Unique Outbound Clicks | The number of people who performed an outbound click. This metric is estimated. |
| unique_outbound_clicks_ctr | Unique Outbound Clicks Ctr | The percentage of people who saw your ad and performed an outbound click. This metric is estimated. |
| website_ctr | Website Ctr | The percentage of times people saw your ad and performed a link click. |
| website_purchase_roas | Website Purchase Roas | The total return on ad spend (ROAS) from website purchases. This is based on the value of all conversions recorded by the Facebook pixel on your website and attributed to your ads. |
Dimensions
The following table lists the dimensions available for AdGroup Insights, along with their common names and descriptions:
| Field | Field Name | Description |
|---|---|---|
| activity_recency | Activity recency | View your data by the viewer’s recent off-site activity. These values are estimated. |
| age | Age | View your data by age range. These values are estimated. |
| country | Country | View your data by the country in which people live or were located when they saw your ads, depending on how you set your location targeting. These values are estimated. |
| creative_media_type | Media type | View your data by the type of media in your ad. Media can include an image, a video, or both an image and a video. In some cases, such as when an asset type has changed during an ad’s delivery or when an ad format uses a combination of image and video assets, impressions will be reported under the “Image and video” grouping. These values are estimated. |
| days_1 | Day | View your data for each day when your ads were active. These values are estimated. |
| days_14 | 2 weeks | View your data for each two-week period when your ads were active. This breakdown is estimated. |
| days_7 | Week | View your data for each week when your ads were active. These values are estimated. |
| device_platform | Device platform | View your data by the placement in which your ad was shown and devices that people were using when they saw your ads, such as Facebook desktop News Feed or Instagram mobile News Feed. These values are estimated. |
| dma | DMA | View your data by the designated marketing area (DMA) region where people live or were located when they saw your ads, depending on how you set your location targeting. The DMA region represents a US media market, or an area reached by TV, radio, newspaper, or other media. If ads were delivered outside the United States, the data will appear in the non-DMA region category. These values are estimated. |
| frequency_value | Frequency distribution | View your data by the average number of times that people saw your ad. This breakdown is only available for ad sets created with the reach and frequency buying option. These values are estimated. |
| gender | Gender | View your data by gender. These values are estimated. |
| hourly_stats_aggregated_by_advertiser_time_zone | Time of day (ad account time zone) | View your data based on the time of day in the ad account’s time zone. These values are estimated. |
| hourly_stats_aggregated_by_audience_time_zone | Time of day (viewer’s time zone) | View your data based on the time of day in the time zone where the ad was viewed. These values are estimated. |
| impression_device | Impression Device | View your data by the devices that people were using when they saw your ads. These values are estimated. |
| place_page_id | Business Locations | View your data by the impressions for each of your business locations. Business location breakdowns are only available for ads using dynamic Page location targeting. These values are estimated. |
| platform_position | Placement | View your data by the placement in which your ad was shown, such as Facebook desktop News Feed, or Instagram mobile News Feed. These values are estimated. |
| product_id | Product ID | View your data by product ID. Product ID data is only available for ads connected to a catalogue. These values are estimated. |
| publisher_platform | Platform | View your data by the platform where your ad was shown, such as Facebook or Instagram. These values are estimated. |
| region | Region | View your data by the region (such as the county or area) where people live or were located when they saw your ads, depending on how you set your location targeting. These values are estimated. |
| region_id | Region | View your data by the region (such as the county or area) where people live or were located when they saw your ads, depending on how you set your location targeting. These values are estimated. |
List of Ads Action Stats Fields and Dimensions
Fields
The following table lists the fields available for Ads Action Stats, along with their common names and descriptions:
| Field | Field Name | Description |
|---|---|---|
| cost_per_action_type | Cost Per Action Type | The average cost of a relevant action. |
| cost_per_unique_action_type | Cost Per Unique Action Type | The average cost of each unique action. This metric is estimated. |
| unique_actions | Unique Actions | The number of people who took an action that was attributed to your ads. This metric is estimated. |
| video_30_sec_watched_actions | Video 30 Sec Watched Actions | The number of times your video played for at least 30 seconds, or for nearly its total length if it’s shorter than 30 seconds. For each impression of a video, we count video views separately and exclude any time spent replaying the video. |
| video_avg_time_watched_actions | Video Avg Time Watched Actions | The average time a video was played, including any time spent replaying the video for a single impression. |
| video_p100_watched_actions | Video P100 Watched Actions | The number of times your video was played at 100% of its length, including plays that skipped to this point. |
| video_p25_watched_actions | Video P25 Watched Actions | The number of times your video was played at 25% of its length, including plays that skipped to this point. |
| video_p50_watched_actions | Video P50 Watched Actions | The number of times your video was played at 50% of its length, including plays that skipped to this point. |
| video_p75_watched_actions | Video P75 Watched Actions | The number of times your video was played at 75% of its length, including plays that skipped to this point. |
| video_p95_watched_actions | Video P95 Watched Actions | The number of times your video was played at 95% of its length, including plays that skipped to this point. |
| video_play_actions | Video Play Actions | The number of times your video starts to play is counted for each impression of a video and excludes replays. This metric is in development. |
| video_play_curve_actions | Video Play Curve Actions | A video-play-based curve graph that illustrates the percentage of video plays that reached a given second. Entries 0 to 14 represent seconds 0 through 14. Entries 15 to 17 represent second ranges [15 to 20), [20 to 25), and [25 to 30). Entries 18 to 20 represent second ranges [30 to 40), [40 to 50), and [50 to 60). Entry 21 represents plays over 60 seconds. |
Dimensions
The following table lists the dimensions available for Ad Action Stats, along with their common names and descriptions:
| Field | Field Name | Description |
|---|---|---|
| action_brand | Brand | View your data by actions taken on brands from your catalogue. These values are estimated. |
| action_canvas_component_id | Canvas component ID | View your data for each component in a Canvas experience. These values are estimated. |
| action_canvas_component_name | Instant Experience component | View your data for each component in an Instant Experience. These values are estimated. |
| action_carousel_card_id | Carousel card ID | View your data on each card in a carousel ad. These values are estimated. |
| action_carousel_card_name | Carousel Card | View your data on each card in a carousel ad. These values are estimated. |
| action_category | Category | View your data by actions taken on categories from your catalogue. These values are estimated. |
| action_destination | Destination | View your data by the URL that people went to after clicking on your ad. These values are estimated. |
| action_device | Conversion device | View your data by the devices that people were using when they took any actions as a result of your ads. These values are estimated. |
| action_event_channel | Channel | View the channels through which customers interacted with your business, either on or off Facebook. |
| action_reaction | Post reaction type | View your data by the reactions to your ads or boosted posts. The reactions button on an ad allows people to share different reactions on its content: Like, Love, Haha, Wow, Sad or Angry. These values are estimated. |
| action_target_id | Target ID | The ID of the destination that people go to after clicking on your ad. This could be your Facebook Page, an external URL for your conversion pixel or an app configured with the software development kit (SDK). |
| action_type | Type | The kind of actions taken on your ad, page, app, or event after your ad was served to someone, even if they did not click on it. Action types include page likes, app installs, conversions, event responses, and more. |
| action_video_sound | Video sound | View your data by whether sound was on or off for a video view. These values are estimated. |
| action_video_type | Video View Type | View your data by whether a video view came from an automatic play or through clicking to play. These values are estimated. |