Facebook Ads link

The Account entity has a group of business fields:

• business
• business_city
• business_country_code
• business_name
• business_state
• business_street
• business_street2
• business_zip
• owner

These business fields require the business_management permission granted to the user. We check if this permission is granted during our setup tests, and if it is not, we display the following warning before your connector starts the next sync:

The funding_source_detailsfield of the Account requires the MANAGE task permission granted to the user.

If this field is unavailable for current Facebook Ads account, we skip it during syncs. This will be mentioned in logs with following message: "You are not granted the "MANAGE task" permission. We skipped the funding_source_details field. This is intended behavior and means that the connector is working as expected.".

The following fields in various metadata tables can cause errors when they are included in API queries:

We skip the fields listed above when we get one of typical errors from the source API. These errors are common and usually are caused by missing permissions or too much data requested:

Each report table has three types of specified metrics which are used to group data: Breakdowns, Action Breakdowns, and Fields. Each of these metrics belongs to one of the grouping levels (listed from the highest to the lowest): Account, Campaign, Ad Set, Ad or None.

NOTE: All metrics not listed in the above table have the Account level.

The lowest level any of the selected metrics has is the overall level of the report.

Example: A custom report table has the following configuration:

All metrics here have the Account grouping level except for the product_id breakdown having the Ad grouping level so the overall report grouping level is Ad.

Regardless of the overall report level, we are try to fetch all data at the Account level first:

    https://graph.facebook.com/<API_VERSION>/<AD_ACCOUNT_ID>/insights
content_copy

If the query for the Account level fails for any reason, then we try to fetch data at the next lower level. In the example case, it is the Campaign level. We fetch all campaign IDs for the current account and fetch reporting data for each campaign:

    https://graph.facebook.com/<API_VERSION>/<CAMPAIGN_ID>/insights
content_copy

If the query for the Campaign level fails for any reason, we try to fetch data at the Ad Set and Ad levels in the same way.

The level at which we successfully fetched data does not affect the resulting composed values in the destination. However, the row count may be different.

If queries failed for all levels, then the sync process stops, and we display the following warning in your dashboard:

NOTE: We don't try to fetch data at lower levels for the reports with the highest Account and the lowest None levels.

This workaround may impact duration of the sync, if the custom report contains too much data. Below are some recommendations to mitigate such an impact:

• Don't add too many metrics to a single report. We recommend splitting a complex report to several simpler ones when possible
• A report with a lower overall level should have fewer number of metrics
• Use metrics with the same level inside a single report

fieldslink

• account_currency
• account_id
• account_name
• action_values
• actions
• ad_id
• ad_name
• adset_id
• adset_name
• attribution_setting
• buying_type
• campaign_id
• campaign_name
• canvas_avg_view_percent
• canvas_avg_view_time
• catalog_segment_value
• clicks
• conversion_rate_ranking
• conversion_values
• conversions
• cost_per_10_sec_video_view
• cost_per_action_type
• cost_per_conversion
• cost_per_estimated_ad_recallers
• cost_per_inline_link_click
• cost_per_inline_post_engagement
• cost_per_outbound_click
• cost_per_thruplay
• cost_per_unique_action_type
• cost_per_unique_click
• cost_per_unique_inline_link_click
• cost_per_unique_outbound_click
• cpc
• cpm
• cpp
• ctr
• engagement_rate_ranking
• estimated_ad_recall_rate
• estimated_ad_recallers
• frequency
• full_view_impressions
• full_view_reach
• gender_targeting
• impressions
• inline_link_click_ctr
• inline_link_clicks
• inline_post_engagement
• instant_experience_clicks_to_open
• instant_experience_clicks_to_start
• instant_experience_outbound_clicks
• labels
• location
• mobile_app_purchase_roas
• objective
• outbound_clicks
• outbound_clicks_ctr
• purchase_roas
• quality_ranking
• reach
• relevance_score
• social_spend
• spend
• unique_actions
• unique_clicks
• unique_ctr
• unique_inline_link_click_ctr
• unique_inline_link_clicks
• unique_link_clicks_ctr
• unique_outbound_clicks
• unique_outbound_clicks_ctr
• video_10_sec_watched_actions
• video_30_sec_watched_actions
• video_avg_percent_watched_actions
• video_avg_time_watched_actions
• video_p100_watched_actions
• video_p25_watched_actions
• video_p50_watched_actions
• video_p75_watched_actions
• video_p95_watched_actions
• video_play_actions
• video_play_curve_actions
• video_thruplay_watched_actions
• website_ctr
• website_purchase_roas

breakdownslink

• ad_format_asset
• age
• app_id
• body_asset
• call_to_action_asset
• country
• description_asset
• dma
• gender
• frequency_value
• hourly_stats_aggregated_by_advertiser_time_zone
• hourly_stats_aggregated_by_audience_time_zone
• image_asset
• impression_device
• link_url_asset
• place_page_id
• device_platform
• product_id
• publisher_platform
• platform_position
• region
• skan_conversion_id
• title_asset
• video_asset;

action_breakdownslink

• action_carousel_card_id
• action_carousel_card_name
• action_canvas_component_name
• action_destination
• action_device
• action_reaction
• action_target_id
• action_type
• action_video_sound
• action_video_type;

sync_modelink

• AllAccounts
• SpecificAccounts

aggregationlink

• Day
• Week
• Month

config_typelink

• Prebuilt
• Custom

prebuilt_reportlink

• ACTION_CANVAS_COMPONENT
• ACTION_CAROUSEL_CARD
• ACTION_CONVERSION_DEVICE
• ACTION_PRODUCT_ID
• ACTION_REACTIONS
• ACTION_VIDEO_SOUND
• ACTION_VIDEO_VIEW_TYPE
• BASIC_AD
• BASIC_AD_SET
• BASIC_ALL_LEVELS
• BASIC_CAMPAIGN
• DELIVERY_PLATFORM
• DELIVERY_PLATFORM_AND_DEVICE
• DELIVERY_PURCHASE_ROAS
• DEMOGRAPHICS_AGE
• DEMOGRAPHICS_AGE_AND_GENDER
• DEMOGRAPHICS_COUNTRY
• DEMOGRAPHICS_DMA_REGION
• DEMOGRAPHICS_GENDER
• DEMOGRAPHICS_REGION

action_report_timelink

• impression
• conversion
• mixed

click_attribution_windowlink

• NONE
• DAY_1
• DAY_7

view_attribution_windowlink

• NONE
• DAY_1
• DAY_7

Breakdowns are estimated metrics. They are used to group data. You can select any of these breakdowns while creating your connector.

• age
• app_id
• country
• dma
• gender
• frequency_value
• reach
• 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
• skan_conversion_id
• title_asset
• video_asset

Restrictionslink

• reach and frequency_value breakdowns are related and must be selected together.

• The following fields cannot be grouped so they can't be requested if you are specifying a breakdown:

  • app_store_clicks

  • newsfeed_avg_position

  • newsfeed_clicks

  • relevance_score

  • newsfeed_impressions

    NOTE: When Facebook introduced changes related to Apple's iOS 14 updates, some metrics became unavailable with certain breakdowns selected. For example, delivery and action breakdowns are not supported for offsite conversion events. This includes demographic breakdowns such as age, gender, and region. See Apple's iOS 14 changes in Facebook API for more information.

• hourly_stats_aggregated_by_advertiser_time_zone
• hourly_stats_aggregated_by_audience_time_zone

Restrictionslink

• video_* fields cannot be requested with any hourly breakdowns.
• Hourly breakdowns do not support unique fields, which are any fields prepended with unique_*, reach or frequency.
• reach and frequency fields will return 0 when hourly breakdowns are in use.

Action breakdowns group results in action fields.

IMPORTANT: Permutations marked with an asterisk (*) can be joined with action_type, action_target_id and action_destination which is the name for action_target_id.

• action_canvas_component_name
• action_destination
• action_device
• action_reaction
• action_target_id
• action_type
• action_video_sound
• action_video_type

Restrictionslink

You can't select the following fields along with the action_device breakdown:

• instant_experience_clicks_to_open
• instant_experience_clicks_to_start
• instant_experience_outbound_clicks

• action_type *
• action_target_id *
• action_device *
• action_device, impression_device *
• action_device, publisher_platform *
• action_device, publisher_platform, impression_device *
• action_device, publisher_platform, platform_position *
• action_device, publisher_platform, platform_position, impression_device *
• action_reaction
• action_type, action_reaction
• age *
• gender *
• age, gender *
• app_id, skan_conversion_id
• country *
• region *
• frequency_value, reach
• publisher_platform *
• publisher_platform, impression_device *
• publisher_platform, platform_position *
• publisher_platform, platform_position, impression_device *
• product_id *
• hourly_stats_aggregated_by_advertiser_time_zone *
• hourly_stats_aggregated_by_audience_time_zone *

The created child tables contain the following main fields:

• action_type - The type of action taken on your ad, Page, app, or event after your ad was displayed to the user, even if they didn't click on it. Action types include Page likes, app installs, conversions, event responses, etc.
• value - The conversion metric value for the default attribution window (7d_click and 1d_view)
• 1_d_click - The conversion metric value for the "1 day after clicking the ad" attribution window
• 7_d_click - The conversion metric value for the "7 days after clicking the ad" attribution window
• 1_d_view - The conversion metric value for the "1 day after viewing the ad" attribution window
• 7_d_view - The conversion metric value for the "7 days after viewing the ad" attribution window
• inline - The conversion metric value for the default attribution window that corresponds to all conversions that occur on the ad, like 'link_click', 'video_view'

Attribution Windowslink

Facebook uses the 7d_click and 1d_view attribution windows by default. You can change each value to 1d_click and 7d_view in the setup form, respectively.

In the setup form, you also can toggle the Use unified attribution setting option, which is enabled by default. When this option is enabled, your ads results are calculated using the unified attribution settings, which are defined at the ad set level. This means using a single time period to attribute conversions to ads and to optimize the campaign. However, in this case, conversion metric values across different attribution settings cannot be aggregated.

Conversionslink

Depending on the type of your conversion, Facebook maps the values into the following AdsActionStats fields:

• actions
• action_values
• conversions
• conversion_values

In order to get the complete conversion information using the Facebook Insights API, you need to:

1. Include all the fields listed above in the report.
2. Combine them downstream of your destination using the JOIN operator or other methods.