Parameters and Fields

Available parameters from these ad objects: Ad Account, Ad Campaign, Ad Set, Ad.

Parameters

Name	Description
`action_attribution_windows` list<enum{1d_view, 7d_view, 28d_view, 1d_click, 7d_click, 28d_click, dda, default}>	Default value: `default` The `default` option means `["1d_view","28d_click"]`. Determines what is 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.
`action_breakdowns` list<enum{action_device, 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: `Array` How to break down action results. Supports more than one breakdowns. Default value is ["action_type"].
`action_report_time` enum{impression, conversion}	Default value: `impression` 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.
`breakdowns` list<enum{ad_format_asset, age, body_asset, call_to_action_asset, country, description_asset, gender, image_asset, impression_device, link_url_asset, product_id, region, title_asset, video_asset, dma, frequency_value, hourly_stats_aggregated_by_advertiser_time_zone, hourly_stats_aggregated_by_audience_time_zone, place_page_id, publisher_platform, platform_position, device_platform}>	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.
`date_preset` enum{today, yesterday, this_month, last_month, this_quarter, lifetime, 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 `time_range` or `time_ranges` is specified.
`default_summary` boolean	Default value: `false` 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.
`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: `Array` Filters on the report data. This parameter is an array of filter objects.
`field` string	Required
`operator` enum {EQUAL, NOT_EQUAL, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, IN_RANGE, NOT_IN_RANGE, CONTAIN, NOT_CONTAIN, IN, NOT_IN, STARTS_WITH, ANY, ALL, AFTER, BEFORE, ON_OR_AFTER, ON_OR_BEFORE, NONE}	Required
`value` string	Required
`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 `product_id`.
`sort` list<string>	Default value: `Array` 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, 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: `Array` Similar to `action_breakdowns`, but applies to summary. Default value is ["action_type"].
`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` or `date_preset`, you may choose to have the results for the whole period, or have results for smaller time slices. If "all_days" is used, it means one result set for the whole period. If "monthly" is used, you will get one result set for each calendar month in the given period. Or you can have one result set for each N-day period specified by this param. This param is ignored if `time_ranges` is specified.
`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` is provided.
`since` datetime	A date in the format of "YYYY-MM-DD", which means from the beginning midnight of that day.
`until` datetime	A date in the format of "YYYY-MM-DD", which means to the beginning midnight of the following day.
`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 `time_increment` setting in this case.If `time_ranges` is specified, `date_preset`, `time_range` and `time_increment` are ignored.
`since` datetime	A date in the format of "YYYY-MM-DD", which means from the beginning midnight of that day.
`until` datetime	A date in the format of "YYYY-MM-DD", which means to the beginning midnight of the following day.
`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.

Existing date_presets. These will be deprecated with the new Graph API version.

Preset	Definition
`today`	Today, since 12:00 AM in your account's time zone.
`yesterday`	Yesterday, the 24-hour period between 12:00 AM and 11:59 PM in your account's time zone.
`last_week`	The complete 7-day period starting on the previous Monday and ending on the most recent Sunday.
`last_month`	The complete previous month, starting on the first day and ending on the last day of the month.
`last_3_months`	The complete previous 2 months, plus all complete days of the current month, not including today.
`this_week`	The current week, beginning on the most recent Monday and including today.
`this_month`	The current month, beginning on the first day and including today.
`this_quarter`	The current quarter, beginning on the first day of the first month of the calendar-year quarter and including today.
`last_3d`	Last 2 days, including today.
`last_7_days`	Last 6 days, including today.
`last_14_days`	Last 13 days, including today.
`last_28_days`	Last 27 days, including today.
`last_30_days`	Last 29 days, including today.
`last_90_days`	Last 89 days, including today.
`lifetime`	From the start

Available New `date_presets`

Preset	Definition
`today`	Today, since 12:00 AM in your account's time zone.
`yesterday`	Yesterday, the 24-hour period between 12:00 AM and 11:59 PM in your account's time zone.
`this_week_sun_today`	The current week, beginning on the most recent Sunday and including today.
`this_week_mon_today`	The current week, beginning on the most recent Monday and including today.
`last_week_sun_sat`	The complete 7-day period starting on the previous Sunday and ending on the most recent Saturday.
`last_week_mon_sun`	The complete 7-day period starting on the previous Monday and ending on the most recent Sunday.
`this_month`	The current month, beginning on the first day and including today.
`last_month`	The complete previous month, starting on the first day and ending on the last day of the month.
`this_quarter`	The current quarter, beginning on the first day of the first month of the calendar-year quarter and including today.
`last_3d`	The complete previous 3 days, ending at 11:59 PM last night and not including today.
`last_7d`	The complete previous 7 days, ending at 11:59 PM last night (in your account's time zone) and not including today.
`last_14d`	The complete previous 14 days, ending at 11:59 PM last night (in your account's time zone) and not including today.
`last_28d`	The complete previous 28 days, ending at 11:59 PM last night (in your account's time zone) and not including today.
`last_30d`	The complete previous 30 days, ending at 11:59 PM last night (in your account's time zone) and not including today.
`last_90d`	The complete previous 90 days, ending at 11:59 PM last night (in your account's time zone) and not including today.
`this_year`	The current year, beginning on January 1 and including today.
`last_year`	The complete previous year, starting on January 1 at 12:00 AM and ending on December 31 at 11:59 PM.
`lifetime`	From the start

Fields

The fields available in the fields parameter for this endpoint. The Insights API can return metrics which are estimated or in-development. In some cases a metric may be both estimated and in-development. For more information, see Insights API, Estimated and In-Development Metrics.

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. Default
`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` list<AdsActionStats>	The total value of all conversions attributed to your ads.
`actions` list<AdsActionStats>	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. Default
`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. Default
`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.
`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. Default
`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` list<AdsActionStats>	The total value of all conversions from your catalog segment attributed to your ads.
`clicks` numeric string	The number of clicks on your ads.
`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` list<AdsActionStats>	The total value of all conversions attributed to your ads, including contact, customize_product, donate, find_location, schedule, start_trial, submit_application, subscribe.
`conversions` list<AdsActionStats>	The total number of conversions attributed to your ads, including contact, customize_product, donate, find_location, schedule, start_trial, submit_application, subscribe.
`converted_product_quantity` list<AdsActionStats>	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` list<AdsActionStats>	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` list<AdsActionStats>	The average cost of a relevant action.
`cost_per_conversion` list<AdsActionStats>	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.
`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` list<AdsActionStats>	The average cost for each outbound click.
`cost_per_thruplay` list<AdsActionStats>	The average cost for each ThruPlay. This metric is in development.
`cost_per_unique_action_type` list<AdsActionStats>	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` list<AdsActionStats>	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. Default
`date_stop` string	The end date for your data. This is controlled by the date range you've selected for your reporting view. Default
`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.
`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.
`impressions` numeric string	The number of times your ads were on screen. Default
`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.
`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` numeric string	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` list<AdsActionStats>	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.
`outbound_clicks` list<AdsActionStats>	The number of clicks on links that take people off Facebook-owned properties.
`outbound_clicks_ctr` list<AdsActionStats>	The percentage of times people saw your ad and performed an outbound click.
`purchase_roas` list<AdsActionStats>	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.
`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. Default
`unique_actions` list<AdsActionStats>	The number of people who took an action that was attributed to your ads. This metric is estimated.
`unique_clicks` numeric string	The number of people who performed a click (all). This metric is estimated.
`unique_ctr` numeric string	The percentage of people who saw your ad and performed a unique click (all). This metric is estimated.
`unique_inline_link_click_ctr` numeric string	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` numeric string	The number of people who performed an inline link click. This metric is estimated.
`unique_link_clicks_ctr` numeric string	The percentage of people who saw your ad and performed a link click. This metric is estimated.
`unique_outbound_clicks` list<AdsActionStats>	The number of people who performed an outbound click. This metric is estimated.
`unique_outbound_clicks_ctr` list<AdsActionStats>	The percentage of people who saw your ad and performed an outbound click. This metric is estimated.
`video_30_sec_watched_actions` list<AdsActionStats>	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` list<AdsActionStats>	The average time a video was played, including any time spent replaying the video for a single impression.
`video_p100_watched_actions` list<AdsActionStats>	The number of times your video was played at 100% of its length, including plays that skipped to this point.
`video_p25_watched_actions` list<AdsActionStats>	The number of times your video was played at 25% of its length, including plays that skipped to this point.
`video_p50_watched_actions` list<AdsActionStats>	The number of times your video was played at 50% of its length, including plays that skipped to this point.
`video_p75_watched_actions` list<AdsActionStats>	The number of times your video was played at 75% of its length, including plays that skipped to this point.
`video_p95_watched_actions` list<AdsActionStats>	The number of times your video was played at 95% of its length, including plays that skipped to this point.
`video_play_actions` list<AdsActionStats>	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` list<AdsActionStats>	The percentage of times people saw your ad and performed a link click.
`website_purchase_roas` list<AdsActionStats>	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.

Insights

Parameters and Fields

Parameters

Existing date_presets. These will be deprecated with the new Graph API version.

Available New date_presets

Fields

Available New `date_presets`