Marketing API Version

Ad Set Insights

We will deprecate app_store_clicks, deeplink_clicks, and website_clicks in 2.10. These will be replaced by click_to_app_store, click_to_app_deeplink, and click_to_website that you can access via the action_link_click_destination breakdown.

Reading

Insights on advertising performance of this ad set

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
Page management Apps
No data
Other Apps
No data

Parameters

NameDescription
action_attribution_windows
list<enum{1d_view, 7d_view, 28d_view, 1d_click, 7d_click, 28d_click, 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_canvas_component_name, action_carousel_card_id, action_carousel_card_name, action_destination, action_device, action_link_click_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 will see a conversion on Jan 1st. When you query the API with action_report_time=conversion, you will see a conversion on Jan 2nd.

breakdowns
list<enum{age, country, dma, gender, frequency_value, hourly_stats_aggregated_by_advertiser_time_zone, hourly_stats_aggregated_by_audience_time_zone, impression_device, place_page_id, publisher_platform, platform_position, device_platform, product_id, region, ad_format_asset, body_asset, call_to_action_asset, description_asset, image_asset, link_url_asset, title_asset, video_asset}>

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 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 will 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 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 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, NONE}
Required
value
string
Required
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: 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_canvas_component_name, action_carousel_card_id, action_carousel_card_name, action_destination, action_device, action_link_click_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.

Fields

Reading from this edge will return a JSON formatted result:

{ "data": [], "paging": {}, "summary": {} }

data

A list of AdsInsights nodes.

paging

For more details about pagination, see the Graph API guide.

summary

Aggregated information about the edge, such as counts. Specify the fields to fetch in the summary param (like summary=account_currency).

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.

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.

call_to_action_clicks

numeric string

The number of times people clicked the call-to-action button on your ad.

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 Facebook Canvas that people saw. Canvas is a screen that opens on mobile after a person clicks the Canvas link in your ad. It may include a series of interactive or multimedia components, including video, images, product catalogs and more.

canvas_avg_view_time

numeric string

The average total time, in seconds, that people spent viewing a Facebook Canvas. Canvas is a screen that opens on mobile after a person clicks the Canvas link in your ad. It may include a series of interactive or multimedia components, including video, images, product catalogs and more.

canvas_component_avg_pct_view

The average percentage of time spent viewing each component of a Facebook Canvas. Canvas is a screen that opens on mobile after a person clicks the Canvas link in your ad. It may include a series of interactive or multimedia components, including video, images, product catalogs and more.

clicks

numeric string

The number of clicks on your ads.

comparison_node

AdsInsightsComparison

Parent node that encapsulates fields to be compared (current time range Vs comparison time range)

cost_per_10_sec_video_view

The average cost for each 10-second video view.

cost_per_action_type

The average cost of a relevant action.

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 Objective.

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_total_action

numeric string

The average cost of a relevant action.

cost_per_unique_action_type

The average cost of each unique action.

cost_per_unique_click

numeric string

The average cost for each unique click (all).

cost_per_unique_inline_link_click

numeric string

The average cost of each unique inline link click.

cost_per_unique_outbound_click

The average cost for each unique outbound click.

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.

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.

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 Objective.

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 Objective.

frequency

numeric string

The average number of times each person saw your ad.

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.

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 you selected for your campaign. Your objective reflects the goal you want to achieve with your advertising.

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.

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.

relevance_score

AdgroupRelevanceScore

A rating from 1 to 10 that estimates how well your target audience is responding to your ad. This score is shown after your ad receives more than 500 impressions. It's only visible when looking at reporting for ads and does not appear for ad sets and campaigns.

social_clicks

numeric string

The number of clicks (all) when your ad was displayed with social information, which shows other Facebook friends who engaged with your Facebook Page or ad.

social_impressions

numeric string

The number of times your ads were viewed when displayed with social information, which shows Facebook friends who engaged with your Facebook Page or ad.

social_reach

numeric string

The number of people who saw your ad when displayed with social information, which shows other Facebook friends who engaged with your Facebook Page or ad.

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.

total_action_value

numeric string

The total value of all conversions attributed to your ads.

total_actions

numeric string

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

total_unique_actions

numeric string

The number of people who took an action that was attributed to your ads.

unique_actions

The number of people who took an action that was attributed to your ads.

unique_clicks

numeric string

The number of people who performed a click (all).

unique_ctr

numeric string

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

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.

unique_inline_link_clicks

numeric string

The number of people who performed an inline link click.

unique_link_clicks_ctr

numeric string

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

unique_outbound_clicks

The number of people who performed an outbound click.

unique_outbound_clicks_ctr

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

unique_social_clicks

numeric string

The number of people who performed a click (all) on your ad when it was displayed with social information, which shows other Facebook friends who engaged with your Facebook Page or ad.

video_10_sec_watched_actions

The number of times your video was watched for an aggregate of at least 10 seconds, or for nearly its total length, whichever happened first.

video_30_sec_watched_actions

The number of times your video was watched for an aggregate of at least 30 seconds, or for nearly its total length, whichever happened first.

video_avg_percent_watched_actions

The average percentage of your video that people watched.

video_avg_time_watched_actions

The average time a video was watched.

video_p100_watched_actions

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

video_p25_watched_actions

The number of times your video was watched at 25% of its length, including watches that skipped to this point.

video_p50_watched_actions

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

video_p75_watched_actions

The number of times your video was watched at 75% of its length, including watches that skipped to this point.

video_p95_watched_actions

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

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.

Validation Rules

ErrorDescription
100Invalid parameter
2500Error parsing graph query
275Cannot determine the target object for this request. Currently supported objects include ad account, business account and associated objects.
2642Invalid cursors values
278Reading advertisements requires an access token with the extended permission ads_read
274The ad account is not enabled for usage in Ads API. Please add it in developers.facebook.com/apps -> select your app -> settings -> advanced -> advertising accounts -> Ads API
200Permissions error
273This Ads API call requires the user to be admin of the ad account
105The number of parameters exceeded the maximum for this operation

Creating

Example

You can make a POST request to insights edge from the following paths:
When posting to this edge, an AdReportRun will be created.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
  • ads_read
Page management Apps
No data
Other Apps
No data

Parameters

NameDescription
action_attribution_windows
list<enum{1d_view, 7d_view, 28d_view, 1d_click, 7d_click, 28d_click, 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_canvas_component_name, action_carousel_card_id, action_carousel_card_name, action_destination, action_device, action_link_click_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 will see a conversion on Jan 1st. When you query the API with action_report_time=conversion, you will see a conversion on Jan 2nd.

breakdowns
list<enum{age, country, dma, gender, frequency_value, hourly_stats_aggregated_by_advertiser_time_zone, hourly_stats_aggregated_by_audience_time_zone, impression_device, place_page_id, publisher_platform, platform_position, device_platform, product_id, region, ad_format_asset, body_asset, call_to_action_asset, description_asset, image_asset, link_url_asset, title_asset, video_asset}>

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 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 will 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 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 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, NONE}
Required
value
string
Required
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: 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_canvas_component_name, action_carousel_card_id, action_carousel_card_name, action_destination, action_device, action_link_click_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.

Return Type

Struct {
report_run_id: numeric string,
}

Validation Rules

ErrorDescription
100Invalid parameter

Updating

You can't perform this operation on this endpoint.

Deleting

You can't perform this operation on this endpoint.