Meta (Facebook) Ads integration plan

Last updated 10/03/2026

tip

Note that data generated by third-party data integration counts toward the cluster's data consumption

Summary

Interface overview

Interface	Type	Granularity	Attribution	Cost	Revenue	Impressions	Clicks	Conversions
Insights API	API	Aggregated metrics		✅		✅	✅	✅

Meta (that is, Facebook) provides the ad data pull API Facebook Ads Insights API, which supports getting basic report metrics for the ads you run on Meta, such as spend, clicks, impressions, and activations

Integration process

1. Log in to the Meta for Developers backend and create a Business App
2. Generate an Access-Token
3. Log in to the AE backend, go to the Third-party Integration module, add a Meta (Facebook) Insights API plan, and complete the related configuration
4. Check whether the AE system receives the data successfully, and build reports

warning

Note that pulling Facebook Ads API data requires your server to be located outside mainland China or to have a proxy configured.

1. Create an app and get the authorization information

1.1 Create a Business App

First, log in to the Meta for Developers backend and click Create App to create an app

Next, on the Create an app page, enter the app name and contact email address, and click Next to continue

On the Use case page, select Other and click Next to continue

On the Select an app type page, select Business and click Next to continue

Next, after confirming the app's configuration, click Create app to finish creating the app

1.2 Get the Access Token

After creating the app, you need to get the Access Token. Select the app you just created and set up the Marketing API on the Dashboard tab

Next, check whether the Facebook account of the ad account you want to pull data from is the same as the Facebook account that created the Business App. Choose the corresponding method to generate the Access Token based on your situation.

1.2.1 If the ad account and the Business App belong to the same Facebook account

1. Log in to https://business.facebook.com, go to Accounts > Apps, and add a new app. In Add assets, add the ad accounts whose data you want to sync to the app's assets. In addition, if you have already created a system user, you can click Add People to grant the system user access to this app.

1. If you haven't created a system user, go to Users > System users, add a new system user, and use Add assets to add the app you created in the previous step to the system user.

1. Click Generate new token, select the app you created earlier, select the read_insights and ads_read permissions in Available permissions, and create the token, that is, the access token

1.2.2 If the ad account and the Business App belong to different Facebook accounts

If the Facebook account of your ad account isn't the same as the Developer's Facebook account, get the Access Token by following the steps above, and then complete the following configuration:

1. Log in to https://business.facebook.com with the Developer's Facebook account, go to the Business settings > Users > People module, and make sure you can see the assets under the corresponding account, that is, the app you created earlier

1. Click Business settings > Users > Partners, and click the Add button under Partners you request asset access from to link the Facebook account that owns the ad account. Log in to the Facebook account that owns the ad account and complete authorization to get access to the ad accounts under that account

1. Follow the method in 1.2.1 to create a system user, add the ad account you just authorized to the assets, and grant the system user access to the ad accounts you want to pull data from (red box in the image below). Then click Generate new token to create an access token with the read_insights and ads_read permissions

2. Plan configuration

After completing the preparation on the Meta platform, you can log in to the AE system and configure the new plan in the Third-party Integration module. The image below shows the Meta (Facebook) Insights API configuration page. Follow this section to create the plan

2.1 Authorization information configuration

Click the Configure authorization information button under Authorization Information and enter the information you obtained in the previous step in the pop-up:

Where:

• Ads account ID List: the IDs of the ad accounts you want to pull data from, which usually start with act_. Separate multiple accounts with commas (',')
• Access Token: the Access Token you got in the previous section

2.2 Sync Schedule

In the Sync Schedule module, you can set the policy for the AE system to pull Meta Insights API data on a schedule. You can choose to pull data for a period of time at a specific time every day, up to 31 days at a time. Because pulled data also counts toward the data volume, avoid pulling data for overly long periods on a schedule

2.3 Receive Settings

You can control whether the data is written as events. If you turn this off, the data is not written to the event table, so do not turn off this setting.

2.4 Configuration

Finally, in the Configuration module, you can control the details of data pulling, including the time aggregation granularity of the data, the metric fields and dimensions to pull, the event name after ingestion, the mapping between custom reportTypes and Facebook breakdowns, and the mapping between custom reportTypes and report events.

The content of the configuration is a JSON, which you can customize as follows:

Module	Name	Description
sink_event	event_mapping	Event names after ingestion. Customizable; JSON type. The Key corresponds to source.report_types, and the Value is the ingestion event name for that type of data (If you use a custom report_type, you also need to configure the mapping between the custom report_type and the event)
source	report_types	Data types to pull; list type. We recommend entering only one element, that is, pulling data for only one report at a time. Built-in support: country, hour, hourAd, age, platform. To extend to other Facebook breakdown dimensions, configure a custom reportType in extra_params.report_breakdown_map and enter the corresponding key here.
	metrics	Metrics in the data; list type. Different data types support different metrics, so pay attention when filling it in
	group_by	Grouping dimensions in the data; list type. Different data types support different group_by values, so pay attention when filling it in
transfer	double_columns	Fields to be converted to the numeric type, usually the ingestion field names of the metric fields
extra_params	report_breakdown_map	Mapping between custom reportTypes and Facebook API parameters. The Key is the reportType, and the Value contains level and breakdowns.

If you need to make changes, we recommend that you first determine source.report_types, that is, the type of data to pull

The AE system currently supports the following 5 data types. Different data types have different granularities and analysis dimensions:

Data type	Default	Time granularity	Group	Finest ad level
hour		By hour	-	Ad level
country		By day	Aggregated by country (region)	Ad level
age		By day	By age and gender	Ad level
hourAd Not recommended		By hour	-	Ad account level
platform	Yes	By day	By placement	Ad level

hourAd granularity data has the same metric fields as hour granularity data, but fewer dimension fields: it doesn't include the campaign, ad set, and ad dimension fields. Therefore, we don't recommend newly connecting data at this granularity

In addition to the built-in data types above, you can also extend custom reportTypes through extra_params.report_breakdown_map.

• Metric fields

Metric fields correspond to source.metrics in the configuration. By default, we only pull some commonly used metrics. The following lists some of the fields provided by the Ads Insights API. For all fields, see the official documentation. To make changes, enter the names of the metrics you need in source.metrics

Metric name	Ingested name	Description	Default
spend	amount_spent_usd	Total amount spent	Yes
clicks	clicks_all	Total clicks	Yes
actions	Returns multiple fields, including the following action data: Mobile app purchases Mobile app purchases conversion value Mobile app installs Mobile app sessions Mobile app registrations completed Mobile app levels completed Mobile app custom events 3-second video plays App activations Levels achieved Custom Events Page engagement Post engagement Link clicks Post saves Post reactions Post comments Post shares	In-app actions and values	Yes
action_values
conversion_values	conversion_values	Conversion value	Yes
conversion_rate_ranking	conversion_rate_ranking	Conversion rate ranking
converted_product_quantity	converted_product_quantity	Converted product quantity
	converted_product_quantity_1d_view	Converted product quantity (1-day view attribution window)
	converted_product_quantity_7d_click	Converted product quantity (7-day click attribution window)
converted_product_value	converted_product_value	Converted product value
	converted_product_value_1d_view	Converted product value (1-day view attribution window)
	converted_product_value_7d_click	Converted product value (7-day click attribution window)
cpp	cost_per_1_000_people_reached_usd	Average cost per 1,000 people reached	Yes
cost_per_estimated_ad_recallers	cost_per_estimated_ad_recall_lift_people_usd	Average cost per estimated ad recall
cost_per_inline_link_click	cost_per_inline_link_click_usd	Average cost per inline link click *Note: Inline means that the user stays within Facebook products after clicking. The same applies below
cost_per_inline_post_engagement	cost_per_inline_post_engagement_usd	Average cost per post engagement (Post Engagement)
cost_per_outbound_click	cost_per_outbound_click_usd	Average cost per outbound click *Note: Outbound means that the user is taken outside Facebook products after clicking. The same applies below
cost_per_thruplay	cost_per_thruplay_1_day_after_viewing_usd	Average cost per Thruplay (1-day view attribution window)
	cost_per_thruplay_7_days_after_clicking_usd	Average cost per Thruplay (7-day click attribution window)
	cost_per_thruplay_usd	Average cost per Thruplay
cost_per_unique_click	cost_per_unique_click_all_usd	Average cost per unique click
cost_per_unique_inline_link_click	cost_per_unique_inline_link_click_usd	Average cost per unique inline link click
cost_per_unique_outbound_click	cost_per_unique_outbound_click_usd	Average cost per unique outbound click
cpc	cpc_all_usd	CPC	Yes
cpm	cpm_cost_per_1_000_impressions_usd	CPM	Yes
ctr	ctr_all	Overall click-through rate	Yes
	ctr_link_click_through_rate	Link click-through rate	Yes
engagement_rate_ranking	engagement_rate_ranking	Engagement rate ranking
estimated_ad_recallers	estimated_ad_recall_lift_people	Estimated ad recall lift (people)
estimated_ad_recall_rate	estimated_ad_recall_lift_rate	Estimated ad recall lift rate
frequency	frequency	Average number of views	Yes
impressions	impressions	Impressions	Yes
inline_link_clicks	inline_link_clicks_in_ad	Inline link clicks
inline_link_click_ctr	inline_link_ctr_usd	Inline link click-through rate
inline_post_engagement	inline_post_engagement_in_ad	Post engagements
instant_experience_clicks_to_open	instant_experience_clicks_to_open	Instant Experience clicks
instant_experience_clicks_to_start	instant_experience_clicks_to_start	Instant Experience starts
canvas_avg_view_percent	instant_experience_view_percentage	Instant Experience view percentage
canvas_avg_view_time	instant_experience_view_time	Instant Experience average view time
outbound_clicks	outbound_clicks	Outbound clicks
outbound_clicks_ctr	outbound_ctr_click_through_rate	Outbound click-through rate
quality_ranking	quality_ranking	Quality ranking
reach	reach	Reach	Yes
video_avg_time_watched_actions	video_average_play_time	Average video play time
	video_average_play_time_1_day_after_viewing	Average video play time (1-day view attribution window)
	video_average_play_time_7_days_after_clicking	Average video play time (7-day click attribution window)
	video_average_play_time_on_ad	Average video play time (ad only)
video_play_curve_actions	video_play_curve_actions	Video play curve buckets
video_play_actions	video_plays	Video plays
	video_plays_1_day_after_viewing	Video plays (1-day view attribution window)
	video_plays_7_days_after_clicking	Video plays (7-day click attribution window)
video_p100_watched_actions	video_plays_at_100	Video completion rate
video_p25_watched_actions	video_plays_at_25	Video 25% play rate
video_p50_watched_actions	video_plays_at_50	Video 50% play rate
video_p75_watched_actions	video_plays_at_75	Video 75% play rate
video_p95_watched_actions	video_plays_at_95	Video 95% play rate
website_ctr	website_ctr	Website click-through rate

• Dimension fields

Dimension fields correspond to source.group_by in the configuration. Note that the data report type, that is, source.report_types, determines the analysis granularity used in calculation, while dimension fields only determine whether these fields are displayed. Therefore, some dimensions are unavailable for some data report types. To make changes, enter the names of the dimensions you need in source.group_by

Dimension name	Ingested name	Description	Default
campaign_id	campaign_id	Campaign ID	Yes
campaign_name	campaign_name	Campaign name	Yes
adset_id	ad_set_id	Ad Set ID	Yes
adset_name	ad_set_name	Ad Set name	Yes
ad_id	ad_id	Ad ID	Yes
ad_name	ad_name	Ad name	Yes
account_id	account_id	Ad account ID	Yes
account_name	account_name	Ad account name	Yes
account_currency	currency	Currency	Yes
objective	objective	Objective
optimization_goal	optimization_goal	Optimization goal
attribution_setting	attribution_setting	Attribution setting
buying_type	buying_type	Buying type

2.5 Event ingestion rules

• The date field in the data, that is, the date of the data, is set as the #event_time of the aggregated data

• The event names for the different data report types are:

  • country： facebook_ad_level_data_by_country
  • hour：facebook_ad_level_data_by_hour
  • hourAd：facebook_account_level_by_hour
  • age：facebook_ad_level_data_by_age_gender
  • platform：facebook_ad_level_data_by_platform

• Metric fields are ingested as numeric types, and the other fields are ingested as strings

If you use a custom reportType, the event name is determined by the configuration of the corresponding reportType in sink_event.event_mapping. For example, device can be configured as facebook_ad_level_data_by_device.

2.6 Standardized fields

Original field	Standardized field	Description
account_id	te_ads_object.ad_account_id	Ad account ID
campaign_name	te_ads_object.campaign_name	Campaign name
campaign_id	te_ads_object.campaign_id	Campaign ID
adset_name	te_ads_object.ad_group_name	Ad group name
adset_id	te_ads_object.ad_group_id	Ad group ID
ad_name	te_ads_object.ad_name	Ad name
ad_id	te_ads_object.ad_id	Ad ID
account_currency	te_ads_object.currency	Currency of the cost or revenue
impressions	te_ads_object.impressions	Impressions
clicks_all	te_ads_object.clicks	Clicks
amount_spent_usd	te_ads_object.cost	User acquisition cost