Graph API Version

Insights

This Insights API can be accessed from the following four edges. Parameters are documented in the following docs:

Note: conversion_rate_ranking, engagement_rate_ranking, and quality_ranking are not metrics you can use if you are also using Dynamic Creative Optimization.

Reading

Provides insights on your advertising performance. Allows for deduped metrics across child objects, sorting of metrics, and async reporting.

Parameters

This endpoint doesn't have any parameters.

Fields

FieldDescription
account_currency
string

Currency that is used by your ad account.

account_id
numeric string

The ID number of your ad account, which groups your advertising activity. Your ad account includes your campaigns, ads and billing.

account_name
string

The name of your ad account, which groups your advertising activity. Your ad account includes your campaigns, ads and billing.

action_values

The total value of all conversions attributed to your ads.

actions

The total number of actions people took that are attributed to your ads. Actions may include engagement, clicks or conversions.

ad_id
numeric string

The unique ID of the ad you're viewing in reporting.

ad_name
string

The name of the ad you're viewing in reporting.

adset_id
numeric string

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
string

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.

app_id
string

The ID of the application associated with the Ad Account or Campaign requested. The application information, including its ID, is viewable in the App Dashboard.
Note: This breakdown is only supported by the total_postbacks field.

attribution_setting
string

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.
Both 1-day and 7-day click attribution settings will include iOS14.5 modeled conversions (from opted out users) which will provide a more accurate view of ad performance and enable our delivery systems to optimize based on more comprehensive data.
Note: The attribution_setting field only returns values when use_unified_attribution_setting is set to true.

buying_type
string

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
numeric string

The unique ID number of the ad campaign you're viewing in reporting. Your campaign contains ad sets and ads.

campaign_name
string

The name of the ad campaign you're viewing in reporting. Your campaign contains ad sets and ads.

canvas_avg_view_percent
numeric string

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
numeric string

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

The total value of all conversions from your catalog segment attributed to your ads.

clicks
numeric string

The number of clicks on your ads.

coarse_conversion_value
string

Allows advertisers and ad networks to receive directional post-install quality insights when the volume of campaign conversions isn't high enough to meet the privacy threshold needed to unlock the standard conversion value. Possible values of this breakdown are low, medium and high.
Note: This breakdown is only supported by the total_postbacks_detailed_v4 field.

conversion_rate_ranking
string

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

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

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

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

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

The average cost of a relevant action.

cost_per_conversion

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
numeric string

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
numeric string

The average cost of each inline link click.

cost_per_inline_post_engagement
numeric string

The average cost of each inline post engagement.

cost_per_outbound_click

The average cost for each outbound click.

cost_per_thruplay

The average cost for each ThruPlay. This metric is in development.

cost_per_unique_action_type

The average cost of each unique action. This metric is estimated.

cost_per_unique_click
numeric string

The average cost for each unique click (all). This metric is estimated.

cost_per_unique_inline_link_click
numeric string

The average cost of each unique inline link click. This metric is estimated.

cost_per_unique_outbound_click

The average cost for each unique outbound click. This metric is estimated.

cpc
numeric string

The average cost for each click (all).

cpm
numeric string

The average cost for 1,000 impressions.

cpp
numeric string

The average cost to reach 1,000 people. This metric is estimated.

ctr
numeric string

The percentage of times people saw your ad and performed a click (all).

date_start
string

The start date for your data. This is controlled by the date range you've selected for your reporting view.

date_stop
string

The end date for your data. This is controlled by the date range you've selected for your reporting view.

dda_results
list<AdsInsightsDdaResult>

Estimated incremental conversions caused by a given ad based on the objective and settings you selected. This is a modeled value.

engagement_rate_ranking
string

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
numeric string

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
numeric string

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.

fidelity_type
string

To differentiate StoreKit-rendered ads from view-through ads, SKAdNetwork defines a fidelity-type parameter, which you include in the ad signature and receive in the install-validation postback. Use a fidelity-type value of 1 for StoreKit-rendered ads and attributable web ads, and 0 for view-through ads.
Note: This breakdown is only supported by the total_postbacks_detailed_v4 field.

frequency
numeric string

The average number of times each person saw your ad. This metric is estimated.

full_view_impressions
numeric string

The number of Full Views on your Page's posts as a result of your ad.

full_view_reach
numeric string

The number of people who performed a Full View on your Page's post as a result of your ad.

hsid
string

The hsid key is available for ad impressions that use SKAdNetwork 4 and later. This integer can have up to four digits. You can encode information about your advertisement in each set of digits; you may receive two, three, or all four digits of the sourceIdentifier in the first winning postback, depending on the ad impression's postback data tier.
Note: This breakdown is only supported by the total_postbacks_detailed_v4 field.

impressions
numeric string

The number of times your ads were on screen.

inline_link_click_ctr
numeric string

The percentage of time people saw your ads and performed an inline link click.

inline_link_clicks
numeric string

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
numeric string

The total number of actions that people take involving your ads. Inline post engagements use a fixed 1-day-click attribution window.

instagram_upcoming_event_reminders_set
numeric string

The number of reminders set on an upcoming event, taking into account reminders unset.

instant_experience_clicks_to_open
numeric string

The number of clicks on your ad that open an Instant Experience. This metric is in development.

instant_experience_clicks_to_start
numeric string

The number of times an interactive component in an Instant Experience starts. This metric is in development.

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.

is_conversion_id_modeled
string

A boolean flag that indicates whether the conversion_bits are modeled. A 0 indicates conversion_bits aren't modeled, and a 1 indicates that conversion_bits are modeled.
Note: This breakdown is only supported by the total_postbacks_detailed field.

landing_destination
string

The landing destination (onsite or offsite) of your Shop ad.

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
string

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
string

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

The number of clicks on links that take people off Facebook-owned properties.

outbound_clicks_ctr

The percentage of times people saw your ad and performed an outbound click.

postback_sequence_index
string

Sequence of postbacks received from SkAdNetwork API version 4.0. Possible values of this breakdown are 0 (first postback), 1 (second postback) and 2 (third postback).
Note: This breakdown is only supported by the total_postbacks_detailed_v4 field.

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
numeric string

qualifying_question_qualify_answer_rate

quality_ranking
string

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
numeric string

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.

redownload
string

Boolean flag that indicates the customer redownloaded and reinstalled the app when the value is true. A 1 indicates customer has reinstalled the app and 0 indicates that customer hasn’t reinstalled the app
Note: This breakdown is only supported by the total_postbacks_detailed_v4 field.

skan_campaign_id
string

The raw campaign ID received as a part of Skan postback from iOS 15+.
Note: This breakdown is only supported by the total_postbacks_detailed field.

skan_conversion_id
string

The assigned Conversion ID (also referred to as Priority ID) of the event and/or event bundle configured in the application’s SKAdNetwork configuration schema. The app events configuration can be viewed and adjusted in Facebook Events Manager. You can learn more about configuring your app events for Apple's SKAdNetwork here.
Note: This breakdown is only supported by the total_postbacks field.

social_spend
numeric string

The total amount you've spent so far for your ads showed with social information. (ex: Jane Doe likes this).

spend
numeric string

The estimated total amount of money you've spent on your campaign, ad set or ad during its schedule. This metric is estimated.

total_postbacks
string

The total number of postbacks received from Apple’s SKAdNetwork API. Postbacks from SKAdNetwork provide visibility into the number of app installs and post-install events that occurred. This metric is reported by a third-party API.
Note: total_postbacks should not be queried with other field values. Request this metric separately from others.

total_postbacks_detailed

Used to fetch detailed insights of total postbacks received from Apple’s SKAdNetwork API by using it along with breakdowns such as skan_campaign_id, is_conversion_id_modeled, etc. This metric is reported by a third-party API.
Note: total_postbacks_detailed should not be queried with other field values. Request this metric separately from others.

total_postbacks_detailed_v4

The total number of postbacks received from Apple’s SKAdNetwork API. Postbacks from SKAdNetwork provide visibility into the number of app installs and post-install events that occurred. This metric is reported by a third-party API.
Note: total_postbacks_detailed should not be queried with other field values. Request this metric separately from others.

user_segment_key
string

The user segment (ex: new, existing) of Advantage+ Shopping Campaigns (ASC). Existing user is specified by the custom audience in ASC settings.

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'll count video views separately and exclude any time spent replaying the video.

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

The number of times your video was played at 100% of its length, including plays that skipped to this point.

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

The number of times your video was played at 50% of its length, including plays that skipped to this point.

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

The number of times your video was played at 95% of its length, including plays that skipped to this point.

video_play_actions

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
list<AdsHistogramStats>

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

The percentage of times people saw your ad and performed a link click.

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.

Creating

You can't perform this operation on this endpoint.

Updating

You can't perform this operation on this endpoint.

Deleting

You can't perform this operation on this endpoint.