Facebook will no longer be able to aggregate non-inline conversion metric values across iOS 14.5 and non-iOS 14.5 campaigns due to differences in attribution logic. Querying across iOS 14.5 and non-iOS 14.5 campaigns will result in no data getting returned for non-inline conversion metrics such as app installs and purchases. Inline event metrics like impressions, link clicks, and video views, however, can still be aggregated. Please visit our changelog for more information.
Provides insights on your advertising performance. Allows for deduped metrics across child objects, such as unique_clicks
, sorting of metrics, and async reporting.
GET /v21.0/<AD_SET_ID>/insights?fields=impressions&breakdown=publisher_platform HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
try {
// Returns a `Facebook\FacebookResponse` object
$response = $fb->get(
'/<AD_SET_ID>/insights?fields=impressions&breakdown=publisher_platform',
'{access-token}'
);
} catch(Facebook\Exceptions\FacebookResponseException $e) {
echo 'Graph returned an error: ' . $e->getMessage();
exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
echo 'Facebook SDK returned an error: ' . $e->getMessage();
exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
"/<AD_SET_ID>/insights",
{
"fields": "impressions",
"breakdown": "publisher_platform"
},
function (response) {
if (response && !response.error) {
/* handle the result */
}
}
);
Bundle params = new Bundle();
params.putString("fields", "impressions");
params.putString("breakdown", "publisher_platform");
/* make the API call */
new GraphRequest(
AccessToken.getCurrentAccessToken(),
"/<AD_SET_ID>/insights",
params,
HttpMethod.GET,
new GraphRequest.Callback() {
public void onCompleted(GraphResponse response) {
/* handle the result */
}
}
).executeAsync();
NSDictionary *params = @{
@"fields": @"impressions",
@"breakdown": @"publisher_platform",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
initWithGraphPath:@"/<AD_SET_ID>/insights"
parameters:params
HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
id result,
NSError *error) {
// Handle the result
}];
curl -X GET -G \
-d 'fields="impressions"' \
-d 'breakdown="publisher_platform"' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0/<AD_SET_ID>/insights
Parameter | Description |
---|---|
action_attribution_windows list<enum{1d_view, 7d_view, 28d_view, 1d_click, 7d_click, 28d_click, 1d_ev, dda, default, 7d_view_first_conversion, 28d_view_first_conversion, 7d_view_all_conversions, 28d_view_all_conversions, skan_view, skan_click}> | Default value: default The attribution window for the actions. |
action_breakdowns list<enum{action_device, conversion_destination, matched_persona_id, matched_persona_name, signal_source_bucket, standard_event_content_type, action_canvas_component_name, action_carousel_card_id, action_carousel_card_name, action_destination, action_reaction, action_target_id, action_type, action_video_sound, action_video_type}> | Default value: Vec How to break down action results. Supports more than one breakdowns. Default value is ["action_type"]. |
action_report_time enum{impression, conversion, mixed} | 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 |
breakdowns list<enum{ad_format_asset, age, app_id, body_asset, breakdown_reporting_ad_id, call_to_action_asset, coarse_conversion_value, country, description_asset, fidelity_type, gender, hsid, image_asset, impression_device, is_conversion_id_modeled, is_rendered_as_delayed_skip_ad, landing_destination, link_url_asset, mdsa_landing_destination, media_asset_url, media_creator, media_destination_url, media_format, media_origin_url, media_text_content, media_type, postback_sequence_index, product_id, redownload, region, skan_campaign_id, skan_conversion_id, skan_version, title_asset, user_persona_id, user_persona_name, video_asset, dma, frequency_value, hourly_stats_aggregated_by_advertiser_time_zone, hourly_stats_aggregated_by_audience_time_zone, mmm, place_page_id, publisher_platform, platform_position, device_platform, standard_event_content_type, conversion_destination, signal_source_bucket, marketing_messages_btn_name}> | 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 |
date_preset enum{today, yesterday, this_month, last_month, this_quarter, maximum, data_maximum, last_3d, last_7d, last_14d, last_28d, last_30d, last_90d, last_week_mon_sun, last_week_sun_sat, last_quarter, last_year, this_week_mon_today, this_week_sun_today, this_year} | Default value: last_30d Represents a relative time range. This field is ignored if |
default_summary boolean | Default value: false Determine whether to return a summary. If |
export_columns list<string> | 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 string | Set the format of exporting report file. If the export_format is set, Report file is asyncrhonizely generated. It expects ["xls", "csv"]. |
export_name string | Set the file name of the exporting report. |
fields list<string> | Fields to be retrieved. Default behavior is to return impressions and spend. |
filtering list<Filter Object> | Default value: Vec Filters on the report data. This parameter is an array of filter objects. |
level enum {ad, adset, campaign, account} | Represents the level of result. |
product_id_limit integer | Maximum number of product ids to be returned for each ad when breakdown by |
sort list<string> | Default value: Vec Field to sort the result, and direction of sorting. You can specify sorting direction by appending "_ascending" or "_descending" to the sort field. For example, "reach_descending". For actions, you can sort by action type in form of "actions:<action_type>". For example, ["actions:link_click_ascending"]. This array supports no more than one element. By default, the sorting direction is ascending. |
summary list<string> | If this param is used, a summary section will be included, with the fields listed in this param. |
summary_action_breakdowns list<enum{action_device, conversion_destination, matched_persona_id, matched_persona_name, signal_source_bucket, standard_event_content_type, action_canvas_component_name, action_carousel_card_id, action_carousel_card_name, action_destination, action_reaction, action_target_id, action_type, action_video_sound, action_video_type}> | Default value: Vec Similar to |
time_increment enum{monthly, all_days} or integer | Default value: all_days If it is an integer, it is the number of days from 1 to 90. After you pick a reporting period by using |
time_range {'since':YYYY-MM-DD,'until':YYYY-MM-DD} | A single time range object. UNIX timestamp not supported. This param is ignored if |
time_ranges list<{'since':YYYY-MM-DD,'until':YYYY-MM-DD}> | Array of time range objects. Time ranges can overlap, for example to return cumulative insights. Each time range will have one result set. You cannot have more granular results with |
use_account_attribution_setting boolean | Default value: false When this parameter is set to |
use_unified_attribution_setting boolean | When this parameter is set to |
Reading from this edge will return a JSON formatted result:
{ "
data
": [], "paging
": {}, "summary
": {} }
data
paging
summary
Aggregated information about the edge, such as counts. Specify the fields to fetch in the summary param (like summary=account_currency
).
Field | Description |
---|---|
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. |
activity_recency string | activity_recency |
ad_click_actions | ad_click_actions |
ad_format_asset string | ad_format_asset |
ad_id numeric string | The unique ID of the ad you're viewing in reporting. |
ad_impression_actions | ad_impression_actions |
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. |
age_targeting string | age_targeting |
attribution_setting string | The default attribution window to be used when attribution result is calculated. Each ad set has its own attribution setting value. The attribution setting for campaign or account is calculated based on existing ad sets. |
auction_bid numeric string | auction_bid |
auction_competitiveness numeric string | auction_competitiveness |
auction_max_competitor_bid numeric string | auction_max_competitor_bid |
body_asset AdAssetBody | body_asset |
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_actions | The number of actions performed attributed to your ads promoting your catalog segment, broken down by action type. |
catalog_segment_value | The total value of all conversions from your catalog segment attributed to your ads. |
catalog_segment_value_mobile_purchase_roas | The total return on ad spend (ROAS) from mobile app purchases for your catalog segment. |
catalog_segment_value_omni_purchase_roas | The total return on ad spend (ROAS) from all purchases for your catalog segment. |
catalog_segment_value_website_purchase_roas | The total return on ad spend (ROAS) from website purchases for your catalog segment. |
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 |
comparison_node AdsInsightsComparison | Parent node that encapsulates fields to be compared (current time range Vs comparison time range) |
conversion_values | conversion_values |
conversions | 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_15_sec_video_view | cost_per_15_sec_video_view |
cost_per_2_sec_continuous_video_view | cost_per_2_sec_continuous_video_view |
cost_per_action_type | The average cost of a relevant action. |
cost_per_ad_click | cost_per_ad_click |
cost_per_conversion | cost_per_conversion |
cost_per_dda_countby_convs numeric string | cost_per_dda_countby_convs |
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_one_thousand_ad_impression | cost_per_one_thousand_ad_impression |
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_conversion | cost_per_unique_conversion |
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. |
country string | country |
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. |
created_time string | created_time |
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_countby_convs numeric string | dda_countby_convs |
dda_results list<AdsInsightsDdaResult> | dda_results |
description_asset AdAssetDescription | description_asset |
device_platform string | device_platform |
dma string | dma |
estimated_ad_recall_rate_lower_bound numeric string | estimated_ad_recall_rate_lower_bound |
estimated_ad_recall_rate_upper_bound numeric string | estimated_ad_recall_rate_upper_bound |
estimated_ad_recallers_lower_bound numeric string | estimated_ad_recallers_lower_bound |
estimated_ad_recallers_upper_bound numeric string | estimated_ad_recallers_upper_bound |
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 |
frequency numeric string | The average number of times each person saw your ad. This metric is estimated. |
frequency_value string | frequency_value |
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. |
gender_targeting string | gender_targeting |
hourly_stats_aggregated_by_advertiser_time_zone string | hourly_stats_aggregated_by_advertiser_time_zone |
hourly_stats_aggregated_by_audience_time_zone string | hourly_stats_aggregated_by_audience_time_zone |
hsid string | The |
image_asset AdAssetImage | image_asset |
impression_device string | impression_device |
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 | instagram_upcoming_event_reminders_set |
instant_experience_clicks_to_open numeric string | instant_experience_clicks_to_open |
instant_experience_clicks_to_start numeric string | instant_experience_clicks_to_start |
instant_experience_outbound_clicks | instant_experience_outbound_clicks |
interactive_component_tap | interactive_component_tap |
labels string | labels |
landing_destination string | landing_destination |
location string | location |
media_asset AdAssetMedia | media_asset |
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. |
platform_position string | platform_position |
postback_sequence_index string | Sequence of postbacks received from SkAdNetwork API version 4.0. Possible values of this breakdown are |
product_id string | product_id |
publisher_platform string | publisher_platform |
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 |
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 |
rule_asset AdAssetRule | rule_asset |
shops_assisted_purchases string | shops_assisted_purchases |
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. |
title_asset AdAssetTitle | title_asset |
updated_time string | updated_time |
user_segment_key string | user_segment_key |
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_asset AdAssetVideo | video_asset |
video_avg_time_watched_actions | The average time a video was played, including any time spent replaying the video for a single impression. |
video_continuous_2_sec_watched_actions | video_continuous_2_sec_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 | 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. |
video_play_retention_0_to_15s_actions list<AdsHistogramStats> | video_play_retention_0_to_15s_actions |
video_play_retention_20_to_60s_actions list<AdsHistogramStats> | video_play_retention_20_to_60s_actions |
video_play_retention_graph_actions list<AdsHistogramStats> | video_play_retention_graph_actions |
video_time_watched_actions | video_time_watched_actions |
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. |
wish_bid numeric string | wish_bid |
Error | Description |
---|---|
100 | Invalid parameter |
2635 | You are calling a deprecated version of the Ads API. Please update to the latest version. |
3018 | The start date of the time range cannot be beyond 37 months from the current date |
104 | Incorrect signature |
80000 | There have been too many calls from this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting#ads-insights. |
190 | Invalid OAuth 2.0 Access Token |
368 | The action attempted has been deemed abusive or is otherwise disallowed |
2642 | Invalid cursors values |
200 | Permissions error |
2500 | Error parsing graph query |
insights
edge from the following paths: Parameter | Description |
---|---|
action_attribution_windows list<enum{1d_view, 7d_view, 28d_view, 1d_click, 7d_click, 28d_click, 1d_ev, dda, default, 7d_view_first_conversion, 28d_view_first_conversion, 7d_view_all_conversions, 28d_view_all_conversions, skan_view, skan_click}> | Default value: default The attribution window for the actions. For example, |
action_breakdowns list<enum{action_device, conversion_destination, matched_persona_id, matched_persona_name, signal_source_bucket, standard_event_content_type, action_canvas_component_name, action_carousel_card_id, action_carousel_card_name, action_destination, action_reaction, action_target_id, action_type, action_video_sound, action_video_type}> | Default value: Vec How to break down action results. Supports more than one breakdowns. Default value is ["action_type"] |
action_report_time enum{impression, conversion, mixed} | 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 |
breakdowns list<enum{ad_format_asset, age, app_id, body_asset, breakdown_reporting_ad_id, call_to_action_asset, coarse_conversion_value, country, description_asset, fidelity_type, gender, hsid, image_asset, impression_device, is_conversion_id_modeled, is_rendered_as_delayed_skip_ad, landing_destination, link_url_asset, mdsa_landing_destination, media_asset_url, media_creator, media_destination_url, media_format, media_origin_url, media_text_content, media_type, postback_sequence_index, product_id, redownload, region, skan_campaign_id, skan_conversion_id, skan_version, title_asset, user_persona_id, user_persona_name, video_asset, dma, frequency_value, hourly_stats_aggregated_by_advertiser_time_zone, hourly_stats_aggregated_by_audience_time_zone, mmm, place_page_id, publisher_platform, platform_position, device_platform, standard_event_content_type, conversion_destination, signal_source_bucket, marketing_messages_btn_name}> | How to break down the result. For more than one breakdown, only certain combinations are available: See "Combining Breakdowns" in the Breakdowns page. The option |
date_preset enum{today, yesterday, this_month, last_month, this_quarter, maximum, data_maximum, last_3d, last_7d, last_14d, last_28d, last_30d, last_90d, last_week_mon_sun, last_week_sun_sat, last_quarter, last_year, this_week_mon_today, this_week_sun_today, this_year} | Default value: last_30d Represents a relative time range. This field is ignored if |
default_summary boolean | Default value: false Determine whether to return a summary. If |
export_columns list<string> | Select fields on the exporting report file. It is an optional param. Exporting columns will equals to the param fields if you leave this param blank |
export_format string | Set the format of exporting report file. If the export_format is set, Report file will be asyncrhonizely generated. It expects ["xls", "csv"]. |
export_name string | Set the file name of the exporting report. |
fields list<string> | Fields to be retrieved. Default behavior is to return a list of most used fields |
filtering list<Filter Object> | Default value: Vec Filters on the report data. This parameter is an array of filter objects |
level enum {ad, adset, campaign, account} | Represents the level of result |
product_id_limit integer | Maximun number of product ids to be returned for each ad when breakdown by product_id |
sort list<string> | Default value: Vec Field to sort the result, and direction of sorting. You can specify sorting direction by appending "_ascending" or "_descending" to the sort field. For example, "reach_descending". For actions, you can sort by action type in form of "actions:<action_type>". For example, ["actions:link_click_ascending"]. This array supports no more than one element. By default, the sorting direction is ascending |
summary list<string> | If this param is used, a summary section will be included, with the fields listed in this param |
summary_action_breakdowns list<enum{action_device, conversion_destination, matched_persona_id, matched_persona_name, signal_source_bucket, standard_event_content_type, action_canvas_component_name, action_carousel_card_id, action_carousel_card_name, action_destination, action_reaction, action_target_id, action_type, action_video_sound, action_video_type}> | Default value: Vec Similar to |
time_increment enum{monthly, all_days} or integer | Default value: all_days If it is an integer, it is the number of days from 1 to 90. After you pick a reporting period by using |
time_range {'since':YYYY-MM-DD,'until':YYYY-MM-DD} | A single time range object. UNIX timestamp not supported. This param is ignored if |
time_ranges list<{'since':YYYY-MM-DD,'until':YYYY-MM-DD}> | Array of time range objects. Time ranges can overlap, for example to return cumulative insights. Each time range will have one result set. You cannot have more granular results with |
use_account_attribution_setting boolean | Default value: false When this parameter is set to true, your ads results will be shown using the attribution settings defined for the ad account |
use_unified_attribution_setting boolean | When this parameter is set to |
report_run_id
: numeric string, Error | Description |
---|---|
100 | Invalid parameter |
200 | Permissions error |
2635 | You are calling a deprecated version of the Ads API. Please update to the latest version. |
190 | Invalid OAuth 2.0 Access Token |
80000 | There have been too many calls from this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting#ads-insights. |