Facebook Fields and Dimensions

The following table lists the Facebook fields and dimensions along with their common names and descriptions.

List of Facebook Fields and Dimensions

Field Field Name Type Description
account_currency Account Currency Field Currency that is used by your ad account.
account_id Account Id Field The ID number of your ad account, which groups your advertising activity. Your ad account includes your campaigns, ads and billing.
account_name Account Name Field The name of your ad account, which groups your advertising activity. Your ad account includes your campaigns, ads and billing.
action_attribution_windows Action Attribution Windows Field 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_brand Brand Dimension View your data by actions taken on brands from your catalogue. These values are estimated.
action_breakdowns Action Breakdowns Field How to break down action results. Supports more than one breakdowns. Default value is [action_type”].”
action_canvas_component_id Canvas component ID Dimension View your data by each component in a Canvas experience. These values are estimated.
action_canvas_component_name Instant Experience component Dimension View your data by each component in an Instant Experience. These values are estimated.
action_carousel_card_id Carousel card ID Dimension View your data by each card in a carousel ad. These values are estimated.
action_carousel_card_name Carousel Card Dimension View your data by each card in a carousel ad. These values are estimated.
action_category Category Dimension View your data by actions taken on categories from your catalogue. These values are estimated.
action_destination Destination Dimension View your data by the URL that people went to after clicking on your ad. These values are estimated.
action_device Conversion device Dimension 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 Dimension View the channels through which customers interacted with your business, either on or off Facebook.
action_reaction Post reaction type Dimension View your data by the reactions on 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_report_time Action Report Time Field Determines the report time of action stats. For example, if a person saw the ad on Jan 1st but converted on Jan 2nd, when you query the API with action_report_time=impression, you see a conversion on Jan 1st. When you query the API with action_report_time=conversion, you see a conversion on Jan 2nd.
action_target_id Target ID Dimension The ID of 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 Dimension The kind of actions taken on your ad, page, app or event after your ad was served to someone, even if they didn’t click on it. Action types include page likes, app installs, conversions, event responses, and more.
action_values Action Values Field The total value of all conversions attributed to your ads.
action_video_sound Video sound Dimension View your data by whether sound was on or off for a video view. These values are estimated.
action_video_type Video View Type Dimension View your data by whether a video view came from an automatic play or through clicking to play. These values are estimated.
actions Actions Field The total number of actions people took that are attributed to your ads. Actions may include engagement, clicks or conversions.
activity_recency Activity recency Dimension View your data by the viewer’s recent off-site activity. These values are estimated.
ad_id Ad Id Field The unique ID of the ad you’re viewing in reporting.
ad_name Ad Name Field The name of the ad you’re viewing in reporting.
adset_id Adset Id Field 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 Field 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.
age Age Dimension View your data by age range. These values are estimated.
attribution_setting Attribution Setting Field 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 Field 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 Field 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 Field The unique ID number of the ad campaign you’re viewing in reporting. Your campaign contains ad sets and ads.
campaign_name Campaign Name Field The name of the ad campaign you’re viewing in reporting. Your campaign contains ad sets and ads.
canvas_avg_view_percent Canvas Avg View Percent Field 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 product catalog and more.
canvas_avg_view_time Canvas Avg View Time Field 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 Field The total value of all conversions from your catalog segment attributed to your ads.
clicks Clicks Field The number of clicks on your ads.
conversion_rate_ranking Conversion Rate Ranking Field A ranking of your ad’s expected conversion rate. Your ad is ranked against ads with your optimization goal 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.
conversion_values Conversion Values Field The total value of all conversions across all channels (i.e. 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 Field The total number of conversions across all channels (i.e. 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 Field 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. Has to be used together with converted product ID breakdown.
converted_product_value Converted Product Value Field The value of purchases recorded by your merchant partner’s pixel or app SDK for a given product ID and driven by your ads. Has to be used together with converted product ID breakdown.
cost_per_action_type Cost Per Action Type Field The average cost of a relevant action.
cost_per_conversion Cost Per Conversion Field The average cost of a conversion across all channels (i.e. 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 Field 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. This metric is estimated and in development.
cost_per_inline_link_click Cost Per Inline Link Click Field The average cost of each inline link click.
cost_per_inline_post_engagement Cost Per Inline Post Engagement Field The average cost of each inline post engagement.
cost_per_outbound_click Cost Per Outbound Click Field The average cost for each outbound click.
cost_per_thruplay Cost Per Thruplay Field The average cost for each ThruPlay. This metric is in development.
cost_per_unique_action_type Cost Per Unique Action Type Field The average cost of each unique action. This metric is estimated.
cost_per_unique_click Cost Per Unique Click Field The average cost for each unique click (all). This metric is estimated.
cost_per_unique_inline_link_click Cost Per Unique Inline Link Click Field The average cost of each unique inline link click. This metric is estimated.
cost_per_unique_outbound_click Cost Per Unique Outbound Click Field The average cost for each unique outbound click. This metric is estimated.
country Country Dimension 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.
cpc Cpc Field The average cost for each click (all).
cpm Cpm Field The average cost for 1,000 impressions.
cpp Cpp Field The average cost to reach 1,000 people. This metric is estimated.
creative_media_type Media type Dimension View your data by the type of media in your ad. Media can include image, video or both image and 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.
ctr Ctr Field The percentage of times people saw your ad and performed a click (all).
date_preset Date Preset Field Represents a relative time range. This field is ignored if time_range or time_ranges is specified.
date_start Date Start Field The start date for your data. This is controlled by the date range you’ve selected for your reporting view.
date_stop Date Stop Field The end date for your data. This is controlled by the date range you’ve selected for your reporting view.
days_1 Day Dimension View your data by each day when your ads were active. These values are estimated.
days_14 2 weeks Dimension View your data by each two-week period when your ads were active. This breakdown is estimated.
days_7 Week Dimension View your data by each week when your ads were active. These values are estimated.
dda_results Dda Results Field 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 Field Determine whether to return a summary. If summary is set, this param is be ignored; otherwise, a summary section with the same fields as specified by fields will be included in the summary section.
device_platform Device platform Dimension View your data by the placement in which your ad was shown and devices that people were using when they saw your ads (e.g. Facebook desktop News Feed, Instagram mobile News Feed). These values are estimated.
dma DMA Dimension 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, data will appear in the non-DMA region category. These values are estimated.
engagement_rate_ranking Engagement Rate Ranking Field 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 Field 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. This metric is estimated and in development.
estimated_ad_recallers Estimated Ad Recallers Field 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 Field Select fields on the exporting report file. It is an optional param. Exporting columns are equal to the param fields, if you leave this param blank
export_format Export Format Field Set the format of exporting report file. If the export_format is set, Report file is asyncrhonizely generated. It expects [xls”
export_name Export Name Field Set the file name of the exporting report.
frequency Frequency Field The average number of times each person saw your ad. This metric is estimated.
frequency_value Frequency distribution Dimension 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.
full_view_impressions Full View Impressions Field The number of Full Views on your Page’s posts as a result of your ad.
full_view_reach Full View Reach Field The number of people who performed a Full View on your Page’s post as a result of your ad.
gender Gender Dimension View your data by gender. These values are estimated.
hourly_stats_aggregated_by_advertiser_time_zone Time of day (ad account time zone) Dimension 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) Dimension 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 Dimension View your data by the devices that people were using when they saw your ads. These values are estimated.
impressions Impressions Field The number of times your ads were on screen.
inline_link_click_ctr Inline Link Click Ctr Field The percentage of time people saw your ads and performed an inline link click.
inline_link_clicks Inline Link Clicks Field 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 Field 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 Field 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 Field 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 Field 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 Field 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 Field The objective reflecting 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 Field 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 Field The number of clicks on links that take people off Facebook-owned properties.
outbound_clicks_ctr Outbound Clicks Ctr Field The percentage of times people saw your ad and performed an outbound click.
place_page_id Business Locations Dimension 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.
place_page_name Place Page Name Field The name of the place page involved in impression or click. Has to be used together with Business Locations breakdown.
platform_position Placement Dimension View your data by the placement in which your ad was shown (e.g. Facebook desktop News Feed, Instagram mobile News Feed). These values are estimated.
product_id Product ID Dimension 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 Dimension View your data by the platform where your ad was shown (e.g. Facebook, Instagram). These values are estimated.
purchase_roas Purchase Roas Field 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 Field qualifying_question_qualify_answer_rate
quality_ranking Quality Ranking Field 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 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 (https://www.facebook.com/help/403110480493160) and does not apply to campaigns or ad sets, only ads.
reach Reach Field 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.
region Region Dimension 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 Dimension 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.
social_spend Social Spend Field The total amount you’ve spent so far for your ads showed with social information. (ex: Jane Doe likes this).
spend Spend Field The estimated total amount of money you’ve spent on your campaign, ad set or ad during its schedule. This metric is estimated.
unique_actions Unique Actions Field The number of people who took an action that was attributed to your ads. This metric is estimated.
unique_clicks Unique Clicks Field The number of people who performed a click (all). This metric is estimated.
unique_ctr Unique Ctr Field 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 Field 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 Field The number of people who performed an inline link click. This metric is estimated.
unique_link_clicks_ctr Unique Link Clicks Ctr Field The percentage of people who saw your ad and performed a link click. This metric is estimated.
unique_outbound_clicks Unique Outbound Clicks Field The number of people who performed an outbound click. This metric is estimated.
unique_outbound_clicks_ctr Unique Outbound Clicks Ctr Field The percentage of people who saw your ad and performed an outbound click. This metric is estimated.
video_30_sec_watched_actions Video 30 Sec Watched Actions Field 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’ll count video views separately and exclude any time spent replaying the video.
video_avg_time_watched_actions Video Avg Time Watched Actions Field 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 Field 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 Field 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 Field 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 Field 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 Field 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 Field The number of times your video starts to play. This is counted for each impression of a video, and excludes replays. This metric is in development.
video_play_curve_actions Video Play Curve Actions Field 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 thru 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.
website_ctr Website Ctr Field The percentage of times people saw your ad and performed a link click.
website_purchase_roas Website Purchase Roas Field 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.



Revision History

Refer to the following table for the list of key updates made to this page:

Date Release Description of Change
Jul-22-2021 NA New document.
Last updated on 26 Jul 2021