Release Status Released Availability Free
Status Page Facebook Ads Status Page Default Historical Sync 1 year
Whitelist Tables/Columns Supported/Unsupported Default Replication Frequency 30 minutes
Full Table Endpoints 0 Incremental Endpoints 8
Destination Incompatibilities Possible incompatibilities. Learn more.

Connecting Facebook Ads

Connecting your Facebook Ads data to Stitch is a five-step process:

  1. Add Facebook Ads as a Stitch data source
  2. Grant Stitch access to your Facebook Ads data
  3. Define the Historical Sync
  4. Define the Replication Frequency
  5. Select tables to sync

Prerequisites

Before you dive into connecting Facebook Ads, you should verify that:

  1. The user setting up the integration has access to everything in the Facebook Ads account. We’ve identified an issue with replicating data that arises when a user’s permissions are restricted: for example, not having access to all campaigns or ads.

    Even if you only intend to sync certain pieces of data post-setup, the user completing the initial setup should still have full access.

  2. All ad-blocking software you are currently using is paused. Because Facebook authentication uses pop ups, you may encounter issues if ad blockers aren’t disabled during the setup.

Add Facebook Ads as a Stitch Data Source

  1. On the Stitch Dashboard page, click the Add an Integration button.

  2. Click the Facebook Ads icon.

  3. Enter a name for the integration. This is the name that will display on the for the integration; it’ll also be used to create the schema in your data warehouse.

    For example, the name “Stitch Facebook Ads” would create a schema called stitch_facebook-ads in the data warehouse. This schema is where all the tables for this integration will be stored.

Defining the Historical Sync

The Sync Historical Data setting will define the starting date for your Facebook Ads integration. This means that data equal to or newer than this date will be replicated to your data warehouse.

Change this setting if you want to sync data beyond Facebook Ads’s default setting of 1 year. For a detailed look at historical syncs, check out the Syncing Historical SaaS Data article.

Define the Replication Frequency

The Replication Frequency controls how often Stitch will attempt to replicate data from your Facebook Ads integration. By default the frequency is set to 30 minutes, but you can change it to better suit your needs.

Before setting the Replication Frequency, note that:

  • The more often Facebook Ads is set to replicate, the higher the number of replicated rows.

  • The number of rows in the source may not equal the number of rows replicated by Stitch. Tables that use Full Table Replication will result in a higher number of replicated rows.

  • Some or all of the tables in Facebook Ads have an attribution window. This means that during every replication job, the past 28 days’ worth of data will be replicated. See the Replication section below for more details.

  • If you’re using a data warehouses that doesn’t natively support nested structures, you’ll see a higher number of replicated rows due to the de-nesting Stitch performs.

To help prevent overages, we recommend setting the Replication Frequency to something less frequent - like 6 hours instead of 30 minutes. For tips on reducing your row count, check out the Reducing Your Row Count section of our Billing Guide.

After selecting a Replication Frequency, click Save Integration.

Granting Stitch Access to Your Facebook Ads Data

  1. After clicking the Authorize button, a small pop-up window will display:

    You’ll be taken through a series of steps to allow Stitch to access data from your Public Profile, Facebook Ads, and related stats. Click Okay to advance through these steps.

  2. After you’ve finished authorizing Stitch, you’ll be prompted to select the Facebook Ad Accounts you want to pull data from. Select the desired accounts by clicking the checkbox in the Connect column.

    If you don’t see the profiles that you would expect to, verify your Facebook Ads permissions before reaching out to support.

  3. Click the Save Connections button.

After your credentials are validated, you’ll be directed back to Stitch (click the All Done button to wrap things up) and the Integration Details page will display.

Selecting Tables to Sync

To complete the setup, you’ll need to select tables you want to sync to your data warehouse.

Check out the Schema section to learn more about the available tables in Facebook Ads.

  1. In the Integration Details page, click the Tables to Replicate tab.
  2. Locate a table you want to replicate.

  3. To sync a table, click the checkbox next to the table’s name. A green checkmark means the table is set to sync.

  4. Repeat this process for all the tables you want to replicate.

Facebook Ads’s Intial Sync

After you finish setting up Facebook Ads, you might see its Sync Status show as Pending on either the Stitch Dashboard or in the Integration Details page.

For a new integration, a Pending status indicates that Stitch is in the process of scheduling the initial sync for the integration. This may take some time to complete.

Replicating Facebook Ads Data

Every time Stitch runs a replication job for Facebook Ads, the last 28 days’ worth of data will be replicated.

This is applicable to all tables in the integration.

Stitch replicates data in this way to account for updates made to existing records within the default attribution window of 28 days, thus ensuring you won’t make decisions based on stale (or false) data. As a result, you may see a higher number of replicated rows than what’s being generated in Facebook Ads.

Setting the Replication Frequency to a higher frequency - like 30 minutes - can result in re-replicating recent data and contribute to high row counts. Syncing fewer tables or selecting a lower frequency can help prevent overages.

Facebook Ads & Nested Data Structures

Some endpoints in Facebooks APIs use heavily nested structures to structure their data. If you’re using a data warehouse that doesn’t natively support nested structures, quite a few subtables may be created as a result of Stitch’s de-nesting feature.

To adjust for this and the querying strategy mentioned above, many of our customers set their Replication Frequencies to a less frequent interval or only select a few tables to sync. This will help keep your row count low.

Facebook Ads Schema

Facebook Ads’ campaign structure contains three levels: campaigns, ad sets, and ads. There is also a fourth level for developers called creatives.

To learn more about how Facebook Ads data is structured, we recommend checking out their API guide.

Included Tables

Note that these tables won't automatically be created in your data warehouse. You must set them to sync in the Integration Details page first.

Stitch's Facebook Ads integration includes these tables:


facebook_campaigns

Replication Method: Incremental
Primary Key: id
Contains Nested Structures?: Yes

The facebook_campaigns table contains info about the campaigns in your Facebook Ads account.

Table Info & Attributes

facebook_campaigns & Nested Structures

This table contains nested structures. If you use a data warehouse that doesn't natively support nested structures, some of the attributes listed below may be in a subtable.

These items are marked with a *

Replication & Attribution Windows

Every time a replication job runs for Facebook Ads, the past 28 days' worth of data will be replicated for this table. As a result, you may see a higher number of replicated rows than what's being generated in Facebook Ads.

Stitch replicates data in this way to account for updates made to existing records within Facebook Ads's default attribution window, thus ensuring you won't make decisions based on stale (or false) data.

facebook_campaigns Attributes

While we try to include everything Facebook Ads has here, this may not be a full list of attributes. Refer to Facebook Ads's documentation for a full list and description of each attribute.

  • Campaign ID (id)

  • account_id

  • adlabels

  • buying_type

  • can_use_spend_cap

  • configured_status

  • effective_status

  • name

  • objective

  • recommendations

  • spend_cap

  • start_time

  • status

  • stop_time

  • created_time

  • updated_time

facebook_adsets

Replication Method: Incremental
Primary Key: id:updated_time
Contains Nested Structures?: Yes

The facebook_adsets table contains info about the Ad Sets in your Facebook Ads account.

Table Info & Attributes

facebook_adsets & Nested Structures

This table contains nested structures. If you use a data warehouse that doesn't natively support nested structures, some of the attributes listed below may be in a subtable.

These items are marked with a *

updated_time & Querying

Because this table uses updated_time as part of the Primary Key, query results might return various versions of the same adgroup. To reflect the latest state of the adgroup, use the latest updated_time timestamp.

Replication & Attribution Windows

Every time a replication job runs for Facebook Ads, the past 28 days' worth of data will be replicated for this table. As a result, you may see a higher number of replicated rows than what's being generated in Facebook Ads.

Stitch replicates data in this way to account for updates made to existing records within Facebook Ads's default attribution window, thus ensuring you won't make decisions based on stale (or false) data.

facebook_adsets Attributes

While we try to include everything Facebook Ads has here, this may not be a full list of attributes. Refer to Facebook Ads's documentation for a full list and description of each attribute.

  • Adset ID (id)

  • account_id

  • adlabels

  • adset_schedule

  • bid_amount

  • bid_info

  • billing_event

  • budget_remaining

  • campaign

  • campaign_id

  • creative_sequence

  • daily_budget

  • effective_status

  • end_time

  • frequency_cap

  • frequency_cap_reset_period

  • frequency_control_specs

  • instagram_actor_id

  • is_autobid

  • is_average_price_pacing

  • lifetime_budget

  • lifetime_frequency_cap

  • lifetime_imps

  • name

  • optimization_goal

  • pricing_type

  • promoted_object

  • recommendations

  • recurring_budget_semantics

  • rf_prediction_id

  • rtb_flag

  • status

  • targeting

  • time_based_ad_rotation_id_blocks

  • time_based_ad_rotation_intervals

  • updated_time

  • use_new_app_click

  • created_time

  • updated_time

facebook_ads

Replication Method: Incremental
Primary Key: id:updated_time
Contains Nested Structures?: Yes

The facebook_ads table contains info about the ads in your Facebook Ads account.

Table Info & Attributes

facebook_ads & Nested Structures

This table contains nested structures. If you use a data warehouse that doesn't natively support nested structures, some of the attributes listed below may be in a subtable.

These items are marked with a *

updated_time & Querying

Because this table uses updated_time as part of the Primary Key, query results might return various versions of the same adgroup. To reflect the latest state of the adgroup, use the latest updated_time timestamp.

Replication & Attribution Windows

Every time a replication job runs for Facebook Ads, the past 28 days' worth of data will be replicated for this table. As a result, you may see a higher number of replicated rows than what's being generated in Facebook Ads.

Stitch replicates data in this way to account for updates made to existing records within Facebook Ads's default attribution window, thus ensuring you won't make decisions based on stale (or false) data.

facebook_ads Attributes

While we try to include everything Facebook Ads has here, this may not be a full list of attributes. Refer to Facebook Ads's documentation for a full list and description of each attribute.

  • Ad ID (id)

  • account_id

  • ad_review_feedback

  • adlabels

  • adset

  • adset_id

  • bid_amount

  • bid_info

  • bid_type

  • campaign

  • campaign_id

  • configured_status

  • conversion_specs

  • creative

  • effective_status

  • last_updated_by_app_id

  • name

  • recommendations

  • status

  • tracking_specs

  • created_time

  • updated_time

facebook_adcreative

Replication Method: Incremental
Primary Key: id
Contains Nested Structures?: Yes

The facebook_adcreative table contains info about the creatives used in ads in your Facebook Ads account.

Table Info & Attributes

facebook_adcreative & Nested Structures

This table contains nested structures. If you use a data warehouse that doesn't natively support nested structures, some of the attributes listed below may be in a subtable.

These items are marked with a *

Replication & Attribution Windows

Every time a replication job runs for Facebook Ads, the past 28 days' worth of data will be replicated for this table. As a result, you may see a higher number of replicated rows than what's being generated in Facebook Ads.

Stitch replicates data in this way to account for updates made to existing records within Facebook Ads's default attribution window, thus ensuring you won't make decisions based on stale (or false) data.

facebook_adcreative Attributes

While we try to include everything Facebook Ads has here, this may not be a full list of attributes. Refer to Facebook Ads's documentation for a full list and description of each attribute.

  • Creative ID (id)

  • actor_id

  • adlabels

  • applink_treatment

  • body

  • call_to_action_type

  • effective_object_story_id

  • image_crops

  • image_hash

  • image_url

  • instagram_actor_id

  • instagram_permalink_url

  • instagram_story_id

  • link_og_id

  • link_url

  • name

  • object_id

  • object_story_id

  • object_story_spec

  • object_type

  • object_url

  • platform_customizations

  • product_set_id

  • run_status

  • template_url

  • thumbnail_url

  • title

  • url_tags

  • use_page_actor_override

facebook_ads_insights

Replication Method: Incremental
Primary Key: ad_id:adset_id:campaign_id:date_start
Contains Nested Structures?: Yes

The facebook_ads_insights table contains entries for each campaign/set/ad combination for each day, along with detailed statistics.

Table Info & Attributes

facebook_ads_insights & Nested Structures

This table contains nested structures. If you use a data warehouse that doesn't natively support nested structures, some of the attributes listed below may be in a subtable.

These items are marked with a *

Replication & Attribution Windows

Every time a replication job runs for Facebook Ads, the past 28 days' worth of data will be replicated for this table. As a result, you may see a higher number of replicated rows than what's being generated in Facebook Ads.

Stitch replicates data in this way to account for updates made to existing records within Facebook Ads's default attribution window, thus ensuring you won't make decisions based on stale (or false) data.

facebook_ads_insights Attributes

While we try to include everything Facebook Ads has here, this may not be a full list of attributes. Refer to Facebook Ads's documentation for a full list and description of each attribute.

  • Ad ID (ad_id)

  • Ad Set ID (adset_id)

  • Campaign ID (campaign_id)

  • account_id

  • account_name

  • ad_name

  • adset_name

  • app_store_clicks

  • call_to_action_clicks

  • campaign_name

  • canvas_avg_view_percent

  • canvas_avg_view_time

  • clicks

  • cost_per_inline_link_click

  • cost_per_inline_post_engagement

  • cost_per_total_action

  • cost_per_unique_click

  • cost_per_unique_inline_link_click

  • cpc

  • cpm

  • cpp

  • ctr

  • date_start

  • date_stop

  • deeplink_clicks

  • frequency

  • impressions

  • inline_link_click_ctr

  • inline_link_clicks

  • inline_post_engagement

  • newsfeed_avg_position

  • newfeed_clicks

  • newsfeed_impressions

  • objective

  • reach

  • relevance_score__negative_feedback

  • relevance_score__positive_feedback

  • relevance_score__score

  • relevance_score__status

  • social_clicks

  • social_impressions

  • social_reach

  • social_spend

  • spend

  • total_action_value

  • total_actions

  • total_unique_actions

  • unique_clicks

  • unique_ctr

  • unique_impressions

  • unique_inline_link_click_ctr

  • unique_inline_link_clicks

  • unique_link_clicks_ctr

  • unique_social_clicks

  • unique_social_impressions

  • website_clicks

facebook_ads_insights_age_and_gender

Replication Method: Incremental
Primary Key: ad_id:adset_id:campaign_id:date_start
Contains Nested Structures?: Yes

The facebook_ads_insights_age_and_gender table contains the same info as the facebook_ads_insights table, but segments it by age and gender.

Table Info & Attributes

facebook_ads_insights_age_and_gender & Nested Structures

This table contains nested structures. If you use a data warehouse that doesn't natively support nested structures, some of the attributes listed below may be in a subtable.

These items are marked with a *

Replication & Attribution Windows

Every time a replication job runs for Facebook Ads, the past 28 days' worth of data will be replicated for this table. As a result, you may see a higher number of replicated rows than what's being generated in Facebook Ads.

Stitch replicates data in this way to account for updates made to existing records within Facebook Ads's default attribution window, thus ensuring you won't make decisions based on stale (or false) data.

facebook_ads_insights_age_and_gender Attributes

While we try to include everything Facebook Ads has here, this may not be a full list of attributes. Refer to Facebook Ads's documentation for a full list and description of each attribute.

  • Ad ID (ad_id)

  • Ad Set ID (adset_id)

  • Campaign ID (campaign_id)

  • account_id

  • account_name

  • ad_name

  • adset_name

  • app_store_clicks

  • call_to_action_clicks

  • campaign_name

  • canvas_avg_view_percent

  • canvas_avg_view_time

  • clicks

  • cost_per_inline_link_click

  • cost_per_inline_post_engagement

  • cost_per_total_action

  • cost_per_unique_click

  • cost_per_unique_inline_link_click

  • cpc

  • cpm

  • cpp

  • ctr

  • date_start

  • date_stop

  • deeplink_clicks

  • frequency

  • impressions

  • inline_link_click_ctr

  • inline_link_clicks

  • inline_post_engagement

  • newsfeed_avg_position

  • newfeed_clicks

  • newsfeed_impressions

  • objective

  • reach

  • relevance_score__negative_feedback

  • relevance_score__positive_feedback

  • relevance_score__score

  • relevance_score__status

  • social_clicks

  • social_impressions

  • social_reach

  • social_spend

  • spend

  • total_action_value

  • total_actions

  • total_unique_actions

  • unique_clicks

  • unique_ctr

  • unique_impressions

  • unique_inline_link_click_ctr

  • unique_inline_link_clicks

  • unique_link_clicks_ctr

  • unique_social_clicks

  • unique_social_impressions

  • website_clicks

facebook_ads_insights_country

Replication Method: Incremental
Primary Key: ad_id:adset_id:campaign_id:date_start
Contains Nested Structures?: Yes

The facebook_ads_insights_country table contains the same info as the facebook_ads_insights table, but segments it by country.

Table Info & Attributes

facebook_ads_insights_country & Nested Structures

This table contains nested structures. If you use a data warehouse that doesn't natively support nested structures, some of the attributes listed below may be in a subtable.

These items are marked with a *

Replication & Attribution Windows

Every time a replication job runs for Facebook Ads, the past 28 days' worth of data will be replicated for this table. As a result, you may see a higher number of replicated rows than what's being generated in Facebook Ads.

Stitch replicates data in this way to account for updates made to existing records within Facebook Ads's default attribution window, thus ensuring you won't make decisions based on stale (or false) data.

facebook_ads_insights_country Attributes

While we try to include everything Facebook Ads has here, this may not be a full list of attributes. Refer to Facebook Ads's documentation for a full list and description of each attribute.

  • Ad ID (ad_id)

  • Ad Set ID (adset_id)

  • Campaign ID (campaign_id)

  • account_id

  • account_name

  • ad_name

  • adset_name

  • app_store_clicks

  • call_to_action_clicks

  • campaign_name

  • canvas_avg_view_percent

  • canvas_avg_view_time

  • clicks

  • cost_per_inline_link_click

  • cost_per_inline_post_engagement

  • cost_per_total_action

  • cost_per_unique_click

  • cost_per_unique_inline_link_click

  • cpc

  • cpm

  • cpp

  • ctr

  • date_start

  • date_stop

  • deeplink_clicks

  • frequency

  • impressions

  • inline_link_click_ctr

  • inline_link_clicks

  • inline_post_engagement

  • newsfeed_avg_position

  • newfeed_clicks

  • newsfeed_impressions

  • objective

  • reach

  • relevance_score__negative_feedback

  • relevance_score__positive_feedback

  • relevance_score__score

  • relevance_score__status

  • social_clicks

  • social_impressions

  • social_reach

  • social_spend

  • spend

  • total_action_value

  • total_actions

  • total_unique_actions

  • unique_clicks

  • unique_ctr

  • unique_impressions

  • unique_inline_link_click_ctr

  • unique_inline_link_clicks

  • unique_link_clicks_ctr

  • unique_social_clicks

  • unique_social_impressions

  • website_clicks

facebook_ads_insights_placement_and_device

Replication Method: Incremental
Primary Key: ad_id:adset_id:campaign_id:date_start
Contains Nested Structures?: Yes

The facebook_ads_insights_placement_and_device table contains the same info as the facebook_ads_insights table, but segments it by placement and device.

Table Info & Attributes

facebook_ads_insights_placement_and_device & Nested Structures

This table contains nested structures. If you use a data warehouse that doesn't natively support nested structures, some of the attributes listed below may be in a subtable.

These items are marked with a *

Replication & Attribution Windows

Every time a replication job runs for Facebook Ads, the past 28 days' worth of data will be replicated for this table. As a result, you may see a higher number of replicated rows than what's being generated in Facebook Ads.

Stitch replicates data in this way to account for updates made to existing records within Facebook Ads's default attribution window, thus ensuring you won't make decisions based on stale (or false) data.

facebook_ads_insights_placement_and_device Attributes

While we try to include everything Facebook Ads has here, this may not be a full list of attributes. Refer to Facebook Ads's documentation for a full list and description of each attribute.

  • Ad ID (ad_id)

  • Ad Set ID (adset_id)

  • Campaign ID (campaign_id)

  • account_id

  • account_name

  • ad_name

  • adset_name

  • app_store_clicks

  • call_to_action_clicks

  • campaign_name

  • canvas_avg_view_percent

  • canvas_avg_view_time

  • clicks

  • cost_per_inline_link_click

  • cost_per_inline_post_engagement

  • cost_per_total_action

  • cost_per_unique_click

  • cost_per_unique_inline_link_click

  • cpc

  • cpm

  • cpp

  • ctr

  • date_start

  • date_stop

  • deeplink_clicks

  • frequency

  • impressions

  • inline_link_click_ctr

  • inline_link_clicks

  • inline_post_engagement

  • newsfeed_avg_position

  • newfeed_clicks

  • newsfeed_impressions

  • objective

  • reach

  • relevance_score__negative_feedback

  • relevance_score__positive_feedback

  • relevance_score__score

  • relevance_score__status

  • social_clicks

  • social_impressions

  • social_reach

  • social_spend

  • spend

  • total_action_value

  • total_actions

  • total_unique_actions

  • unique_clicks

  • unique_ctr

  • unique_impressions

  • unique_inline_link_click_ctr

  • unique_inline_link_clicks

  • unique_link_clicks_ctr

  • unique_social_clicks

  • unique_social_impressions

  • website_clicks

Related Troubleshooting
Questions? Feedback?

Did this article help? If you have questions or feedback, please reach out to us.

Tags: saas integrations