Custom Reports

Our Facebook Ads connector supports custom reports that allow selecting the following parameters and fields:

Aggregation
Action Report Time (optional)
Click Attribution Window (optional)
View Attribution Window (optional)
Engaged-view Attribution Window (optional)
Breakdowns (optional)
Action Breakdowns (optional)

NOTE: Some of these parameters have limitations described in the following sections. See the Facebook Breakdowns Limitations documentation for more information.

Aggregation

This parameter supports the following values:

Day
Week
Month
Lifetime

Aggregation levels

Depending on the aggregation you select, we provide the corresponding column (the source field in the Facebook report is date_start):

date for Day and Lifetime aggregations
week for Week aggregation
month for Month aggregation

Action report time

This parameter supports the following values:

impression
conversion
mixed

Attribution windows

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

Facebook Ads setup form attribution windows

IMPORTANT: Rollback sync time frames for custom reports depend on the maximum value between the Click Attribution Window and View Attribution Window settings. See our Facebook Ads rollback sync documentation for more information.

Click attribution window

This parameter supports the following values:

none
1 day
7 days
28 days

View attribution window

This parameter supports the following values:

none
1 day
7 days
28 days

Engaged-view attribution window

This parameter supports the following values:

none
1 day

Breakdowns

This parameter supports the following values:

action_converted_product_id
age
skan_conversion_id
skan_campaign_id
link_url_asset
ad_format_asset
frequency_value
image_asset
call_to_action_asset
video_asset
coarse_conversion_value
fidelity_type
is_conversion_id_modeled
hourly_stats_aggregated_by_advertiser_time_zone
impression_device
product_id
hourly_stats_aggregated_by_audience_time_zone
device_platform
hsid
redownload
country
postback_sequence_index
dma
region
title_asset
publisher_platform
app_id
description_asset
place_page_id
body_asset
gender
platform_position
hourly_stats_aggregated_by_advertiser_time_zone
hourly_stats_aggregated_by_audience_time_zone

Restrictions

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.
The reach and frequency fields will return 0 when hourly breakdowns are in use.
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, offsite conversion events do not support the delivery and action breakdowns. This includes demographic breakdowns such as age, gender, and region. See Apple's iOS 14 changes in Facebook API for more information.

Action breakdowns

action_canvas_component_name
action_carousel_card_id
action_carousel_card_name
action_destination
action_device
action_reaction
action_target_id
action_type
action_video_sound
action_video_type

Restrictions

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

Conversions and actions

Conversions from Facebook are shared between two fields: actions and conversions. For conversion values, use action_values and conversion_values instead. See Facebook Insight Parameters for definitions of these fields.

When creating your report, remember to include the action_type from the "Action Breakdowns" selection as well as the following fields:

For conversions: conversions and actions from the "Fields" selection.
For conversion values: conversion_values and action_values from the "Fields" selection.

To avoid discrepancies, we recommend using a union of the two resulting child tables (e.g. <TABLE_NAME>_conversions and <TABLE_NAME>_actions).

If you select an action breakdown and field(s), Fivetran creates a secondary table or tables. We name secondary tables by appending the main table name with the field names.

We create separate tables for fields of the list<AdsActionStats> and list<AdsHistogramStats> types listed in Facebook's Insights API documentation.

The action breakdowns are columns in the table, and the field value is the number of actions that occur.

NOTE: The action data is hierarchical: a simple sum of all actions will not equal the field total_actions. See Actions you can measure in Facebook Ads Reporting for more information.

Combinations of breakdowns

You must note the limited compatibility between breakdowns and action breakdowns when creating a custom report.

Expand for details

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_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 *

Sample custom reports

DT refers to destination table name specified in setup form.
* refers to all possible values.

Post engagement report

Expand for details

This report shows the effectiveness of your posts, measured by engagements (comments, likes, etc.)

Level: Adset

Metric	Parameter	Parameter Value	Table	Column	Value
Adset Name	field	adset_name	DT	`adset_name`	*
Campaign Name	field	campaign_name	DT	`campaign_name`	*
Cost Per Post Engagement	field	cost_per_inline_post_engagement	DT	`cost_per_inline_post_engagement`	*
Actions	field	actions	DT_actions	*	*
Frequency	field	frequency	DT	`frequency`	*
Amount Spent	field	spend	DT	`spend`	*
Action Reaction	action_breakdown	action_reaction	DT	*	*
Post Reaction	action_breakdown	action_type	DT_action_type	`action_type`	post_reaction
Post Shares	action_breakdown	action_type	DT_action_type	`action_type`	share
Post Comments	action_breakdown	action_type	DT_action_type	`action_type`	comment

Page likes report

Expand for details

This is a basic report that captures the performance of all ads run for the sole purpose of increasing Page Likes.

Level: Adset

Metric	Parameter	Parameter Value	Table	Column	Value
Adset Name	field	adset_name	DT	`adset_name`	*
Campaign Name	field	campaign_name	DT	`campaign_name`	*
Actions	field	actions	DT_actions	*	*
Frequency	field	frequency	DT	`frequency`	*
Amount Spent	field	spend	DT	`spend`	*
Cost Per Page Like	field	cost_per_action_type	DT_cost_per_action_type	*	*
Page Likes	action_breakdown	action_type	DT_action_type	`action_type`	likes
Age	breakdown	age	DT	`age`	*
Gender	breakdown	gender	DT	`gender`	*

Conversions report

Expand for details

This report is for those that use conversion tracking and shows the number of conversions your campaigns are generating.

Level: Adset

Metric	Parameter	Parameter Value	Table	Column	Value
Adset Name	field	adset_name	DT	`adset_name`	*
Campaign Name	field	campaign_name	DT	`campaign_name`	*
Actions	field	actions	DT_actions	*	*
Frequency	field	frequency	DT	`frequency`	*
Amount Spent	field	spend	DT	spend	*
Website Conversion Value	field	action_values	DT_action_values	*	*
Cost Per Website Conversion	field	cost_per_action_type	DT_cost_per_action_type	*	*
Destination	action_breakdown	action_destination	DT_actions	`action_destination`	*
Website Conversions	action_breakdown	action_type	DT_actions	`action_type`	offsite_conversion

Account performance report

Expand for details

This is an overview report that captures several data points and is a measurement of the overall success of your Ad Account(s).

Level: Adset

Metric	Parameter	Parameter Value	Table	Column	Value
Account Name	field	account_name	DT	`account_name`	*
Adset Name	field	adset_name	DT	`adset_name`	*
Campaign Name	field	campaign_name	DT	`campaign_name`	*
Frequency	field	frequency	DT	`frequency`	*
Reach	field	reach	DT	`reach`	*
Amount Spent	field	spend	DT	`spend`	*
Post Engagements	field	inline_post_engagement	DT	`inline_post_engagement`	*
Actions	field	actions	DT_actions	*	*
Page Likes	action_breakdown	action_type	DT_actions	`action_type`	likes
Post Reactions	action_breakdown	action_type	DT_actions	`action_type`	post_reaction
Post Shares	action_breakdown	action_type	DT_actions	`action_type`	share
Post Comment	action_breakdown	action_type	DT_actions	`action_type`	comment
Website Conversions	action_breakdown	action_type	DT_actions	`action_type`	offsite_conversion

Website drive report

Expand for details

This report measures traffic driven from Facebook to your external website and includes Cost-Per-Click as well as the total amount spent on the Campaign/Adset.

Level: Adset

Metric	Parameter	Parameter Value	Table	Column	Value
Adset Name	field	adset_name	DT	`adset_name`	*
Campaign Name	field	campaign_name	DT	`campaign_name`	*
Frequency	field	frequency	DT	`frequency`	*
Outbound Clicks	field	outbound_clicks	DT	`outbound_clicks`	*
Cost Per Outbound Click	field	cost_per_outbound_click	DT_cost_per_outbound_click	*	*

To build and troubleshoot custom reports, see the Facebook Graph API Explorer.