Connector Catalog
Sources
Facebook Marketing

Feature
Supported?(Yes/No)
Notes
Full Refresh Sync
Yes
Incremental Sync
Yes
except AdCreatives and AdAccount
Incremental Deletes Sync
The Facebook Marketing API doesn’t have a concept of deleting records in the same way that a database does. While a user could archive or delete an ad campaign, there is still a record of that campaign having existed in the Facebook Marketing API. If configured by the user, the Facebook connector replicates records for campaigns or ads even if they were archived or deleted from the Facebook platform.

This Source is capable of syncing the following tables and their data:
You can segment the AdInsights table into parts based on the following information. Each part will be synced as a separate table if normalization is enabled:
  • Country
  • DMA (Designated Market Area)
  • Gender & Age
  • Platform & Device
  • Region
For more information, see the Facebook Insights API documentation.

  1. 1.
    Click Authenticate your Facebook Marketing account.
  2. 2.
    Enter your Account ID. Learn how to find it are here.
  3. 3.
    Enter a start date and your Insights settings.
  4. 4.
    You're done.

  • A Facebook Ad Account ID
  • A Facebook App which has the Marketing API enabled
  • A Facebook Marketing API Access Token
  • Request a rate limit increase from Facebook
Follow the Facebook documentation for obtaining your Ad Account ID and keep that on hand. We'll need this ID to configure Facebook as a source in Airbyte.

Visit the Facebook Developers App hub and create an App and choose "Manage Business Integrations" as the purpose of the app. Fill out the remaining fields to create your app, then follow along the "Enable the Marketing API for your app" section.
From the App's Dashboard screen (seen in the screenshot below) enable the Marketing API for your app if it is not already setup.

In the App Dashboard screen, click Marketing API --> Tools on the left sidebar. Then highlight all the available token permissions (ads_management, ads_read, read_insights, business_management) and click "Get token". A long string of characters should appear in front of you; this is the access token. Copy this string for use in the Airbyte UI later.

Facebook heavily throttles API tokens generated from Facebook Apps with the "Standard Access" tier (the default tier for new apps), making it infeasible to use the token for syncs with Airbyte. You'll need to request an upgrade to Advanced Access for your app on the following permissions:
  • Ads Management Standard Access
  • ads_read
  • ads_management
See the Facebook documentation on Authorization for information about how to request Advanced Access to the relevant permissions.
With the Ad Account ID and API access token, you should be ready to start pulling data from the Facebook Marketing API. Head to the Airbyte UI to setup your source connector!

Facebook heavily throttles API tokens generated from Facebook Apps by default, making it infeasible to use such a token for syncs with Airbyte. To be able to use this connector without your syncs taking days due to rate limiting follow the instructions in the Setup Guide below to access better rate limits.
See Facebook's documentation on rate limiting for more information on requesting a quota upgrade.

In order to retrieve specific fields from Facebook Ads Insights combined with other breakdowns, there is a mechanism to allow you to choose which fields and breakdowns to sync. It is highly recommended to follow the documentation, as there are limitations related to breakdowns. Some fields can not be requested and many others just work combined with specific fields, for example, the breakdown app_id is only supported with the total_postbacks field. By now, the only check done when setting up a source is to check if the fields, breakdowns and action breakdowns are within the ones provided by Facebook. This is, if you enter a good input, it's gonna be validated, but after, if the calls to Facebook API with those pareameters fails you will receive an error from the API. As a summary, custom insights allows to replicate only some fields, resulting in sync speed increase.

Integration Type
Airbyte Type
string
string
number
number
array
array
object
object

Version
Date
Pull Request
Subject
0.2.41
2022-03-28
11446
Increase number of attempts for individual jobs
0.2.40
2022-02-28
10698
Improve sleeps time in rate limit handler
0.2.39
2022-03-09
10917
Retry connections when FB API returns error code 2 (temporary oauth error)
0.2.38
2022-03-08
10531
Add time_increment parameter to custom insights
0.2.37
2022-02-28
10655
Add Activities stream
0.2.36
2022-02-24
10588
Fix execute_in_batch for large amount of requests
0.2.35
2022-02-18
10348
Add error code 104 to backoff triggers
0.2.34
2022-02-17
10180
Performance and reliability fixes
0.2.33
2021-12-28
10180
Add AdAccount and Images streams
0.2.32
2022-01-07
10138
Add primary_key for all insights streams.
0.2.31
2021-12-29
9138
Fix videos stream format field incorrect type
0.2.30
2021-12-20
8962
Add asset_feed_spec field to ad creatives stream
0.2.29
2021-12-17
8649
Retrieve ad_creatives image as data encoded
0.2.28
2021-12-13
8742
Fix for schema generation related to "breakdown" fields
0.2.27
2021-11-29
8257
Add fields to Campaign stream
0.2.26
2021-11-19
7855
Add Video stream
0.2.25
2021-11-12
7904
Implement retry logic for async jobs
0.2.24
2021-11-09
7744
Fix fail when async job takes too long
0.2.23
2021-11-08
7734
Resolve $ref field for discover schema
0.2.22
2021-11-05
7605
Add job retry logics to AdsInsights stream
0.2.21
2021-10-05
4864
Update insights streams with custom entries for fields, breakdowns and action_breakdowns
0.2.20
2021-10-04
6719
Update version of facebook_business package to 12.0
0.2.19
2021-09-30
6438
Annotate Oauth2 flow initialization parameters in connector specification
0.2.18
2021-09-28
6499
Fix field values converting fail
0.2.17
2021-09-14
4978
Convert values' types according to schema types
0.2.16
2021-09-14
6060
Fix schema for ads_insights stream
0.2.15
2021-09-14
5958
Fix url parsing and add report that exposes conversions
0.2.14
2021-07-19
4820
Improve the rate limit management
0.2.12
2021-06-20
3743
Refactor connector to use CDK: - Improve error handling. - Improve async job performance (insights). - Add new configuration parameter insights_days_per_job. - Rename stream adsets to ad_sets. - Refactor schema logic for insights, allowing to configure any possible insight stream.
0.2.10
2021-06-16
3973
Update version of facebook_business to 11.0
0.2.9
2021-06-10
3996
Add AIRBYTE_ENTRYPOINT for Kubernetes support
0.2.8
2021-06-09
3973
Add 80000 as a rate-limiting error code
0.2.7
2021-06-03
3646
Add missing fields to AdInsights streams
0.2.6
2021-05-25
3525
Fix handling call rate limit
0.2.5
2021-05-20
3396
Allow configuring insights lookback window
0.2.4
2021-05-13
3395
Fix an issue that caused losing Insights data from the past 28 days while incremental sync
0.2.3
2021-04-28
3116
Wait longer (5 min) for async jobs to start
0.2.2
2021-04-03
2726
Fix base connector versioning
0.2.1
2021-03-12
2391
Support FB Marketing API v10
0.2.0
2021-03-09
2238
Protocol allows future/unknown properties
0.1.4
2021-02-24
1902
Add include_deleted option in params
0.1.3
2021-02-15
1990
Support Insights stream via async queries
0.1.2
2021-01-22
1699
Add incremental support
0.1.1
2021-01-15
1552
Release Native Facebook Marketing Connector
Copy link
On this page
Features
Supported Tables
Getting Started (Airbyte Cloud)
Getting Started (Airbyte Open-Source)
Request rate limit increase
Rate Limiting & Performance Considerations (Airbyte Open Source)
Custom Insights
Changelog