Skip to main content

Facebook Marketing

This page guides you through the process of setting up the Facebook Marketing source connector.

Prerequisites

Set up Facebook Marketing as a source in Airbyte

For Airbyte Cloud

To set up Facebook Marketing as a source in Airbyte Cloud:

  1. Log into your Airbyte Cloud account.

  2. In the left navigation bar, click Sources. In the top-right corner, click + New source.

  3. On the Set up the source page, select Facebook Marketing from the Source type dropdown.

  4. For Name, enter a name for the Facebook Marketing connector.

  5. Click Authenticate your account to authorize your Meta for Developers account. Airbyte will authenticate the account you are already logged in to. Make sure you are logged into the right account.

  6. For Start Date, enter the date in the YYYY-MM-DDTHR:MIN:S format. The data added on and after this date will be replicated. If this field is blank, Airbyte will replicate all data.

    warning

    Insight tables are only able to pull data from 37 months. If you are syncing insight tables and your start date is older than 37 months, your sync will fail.

  7. For End Date, enter the date in the YYYY-MM-DDTHR:MIN:S format. The data added on and before this date will be replicated. If this field is blank, Airbyte will replicate the latest data.

  8. For Account ID, enter your Facebook Ad Account ID Number.

  9. (Optional) Toggle the Include Deleted button to include data from deleted Campaigns, Ads, and AdSets.

    info

    The Facebook Marketing API does not have a concept of deleting records in the same way that a database does. While you can archive or delete an ad campaign, the API maintains a record of the campaign. Toggling the Include Deleted button lets you replicate records for campaigns or ads even if they were archived or deleted from the Facebook platform.

  10. (Optional) Toggle the Fetch Thumbnail Images button to fetch the thumbnail_url and store the result in thumbnail_data_url for each Ad Creative.

  11. (Optional) In the Custom Insights section, click Add. To retrieve specific fields from Facebook Ads Insights combined with other breakdowns, you can choose which fields and breakdowns to sync.

    We recommend following the Facebook Marketing documentation to understand the breakdown limitations. Some fields can not be requested and many others only work when combined with specific fields. For example, the breakdown app_id is only supported with the total_postbacks field.

    To configure Custom Insights:

    1. For Name, enter a name for the insight. This will be used as the Airbyte stream name

    2. For Fields, enter a list of the fields you want to pull from the Facebook Marketing API.

    3. For End Date, enter the date in the YYYY-MM-DDTHR:MIN:S format. The data added on and before this date will be replicated. If this field is blank, Airbyte will replicate the latest data.

    4. For Breakdowns, enter a list of the breakdowns you want to configure.

    5. For Start Date, enter the date in the YYYY-MM-DDTHR:MIN:S format. The data added on and after this date will be replicated. If this field is blank, Airbyte will replicate all data.

    6. For Time Increment, enter the number of days over which you want to aggregate statistics.

      For example, if you set this value to 7, Airbyte will report statistics as 7-day aggregates starting from the Start Date. Suppose the start and end dates are October 1st and October 30th, then the connector will output 5 records: 01 - 06, 07 - 13, 14 - 20, 21 - 27, and 28 - 30 (3 days only).  
    7. For Action Breakdown, enter a list of the action breakdowns you want to configure.

    8. For Custom Insights Lookback Window, fill in the appropriate value. See more on this parameter.

    9. Click Done.

  12. For Page Size of Requests, fill in the size of the page in case pagintion kicks in. Feel free to ignore it, the default value should work in most cases.

  13. For Insights Lookback Window, fill in the appropriate value. See more on this parameter.

  14. Click Set up source.

For Airbyte Open Source

To set up Facebook Marketing as a source in Airbyte Open Source:

  1. Navigate to Meta for Developers and create an app with the app type Business.

  2. From your App’s dashboard, setup the Marketing API.

  3. Generate a Marketing API access token: From your App’s Dashboard, click Marketing API --> Tools. Select all the available token permissions (ads_management, ads_read, read_insights, business_management) and click Get token. Copy the generated token for later use.

  4. Request a rate increase limit: 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 to request Advanced Access to the relevant permissions.

  5. Navigate to the Airbyte Open Source Dashboard. Add the access token when prompted to do so and follow the same instructions as for setting up the Facebook Connector on Airbyte Cloud.

Supported sync modes

The Facebook Marketing source connector supports the following sync modes:

Supported tables

You can replicate the following tables using the Facebook Marketing connector:

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.

Facebook Marketing Attribution Reporting

Please be informed that the connector uses the lookback_window parameter to perform the repetitive read of the last <lookback_window> days in the Incremental sync mode. This means some data will be synced twice (or possibly more often) despite the cursor value being up-to-date. You can change this date window by modifying the lookback_window parameter when setting up the source. The smaller the value - the fewer duplicates you will have. The greater the value - the more precise results you will get. More details on what the attribution window is and what purpose it serves can be found in this Facebook Article.

Data type mapping

Integration TypeAirbyte Type
stringstring
numbernumber
arrayarray
objectobject

Changelog

VersionDatePull RequestSubject
0.2.542022-06-2914267Make MAX_BATCH_SIZE available in config
0.2.532022-06-1613623Add fields bid_amount bid_strategy bid_constraints to ads_set stream
0.2.522022-06-1413749Fix the not syncing any data issue
0.2.512022-05-3013317Change tax_id to string (Canadian has letter in tax_id)
0.2.502022-04-2712402Add lookback window to insights streams
0.2.492022-05-2013047Fix duplicating records during insights lookback period
0.2.482022-05-1913008Update CDK to v0.1.58 avoid crashing on incorrect stream schemas
0.2.472022-05-0612685Update CDK to v0.1.56 to emit an AirbyeTraceMessage on uncaught exceptions
0.2.462022-04-2212171Allow configuration of page_size for requests
0.2.452022-05-0312390Better retry logic for split-up async jobs
0.2.442022-04-1411751Update API to a directly initialise an AdAccount with the given ID
0.2.432022-04-1311801Fix user_tos_accepted schema to be an object
0.2.422022-04-0611761Upgrade Facebook Python SDK to version 13
0.2.412022-03-2811446Increase number of attempts for individual jobs
0.2.402022-02-2810698Improve sleeps time in rate limit handler
0.2.392022-03-0910917Retry connections when FB API returns error code 2 (temporary oauth error)
0.2.382022-03-0810531Add time_increment parameter to custom insights
0.2.372022-02-2810655Add Activities stream
0.2.362022-02-2410588Fix execute_in_batch for large amount of requests
0.2.352022-02-1810348Add error code 104 to backoff triggers
0.2.342022-02-1710180Performance and reliability fixes
0.2.332021-12-2810180Add AdAccount and Images streams
0.2.322022-01-0710138Add primary_key for all insights streams.
0.2.312021-12-299138Fix videos stream format field incorrect type
0.2.302021-12-208962Add asset_feed_spec field to ad creatives stream
0.2.292021-12-178649Retrieve ad_creatives image as data encoded
0.2.282021-12-138742Fix for schema generation related to "breakdown" fields
0.2.272021-11-298257Add fields to Campaign stream
0.2.262021-11-197855Add Video stream
0.2.252021-11-127904Implement retry logic for async jobs
0.2.242021-11-097744Fix fail when async job takes too long
0.2.232021-11-087734Resolve $ref field for discover schema
0.2.222021-11-057605Add job retry logics to AdsInsights stream
0.2.212021-10-054864Update insights streams with custom entries for fields, breakdowns and action_breakdowns
0.2.202021-10-046719Update version of facebook_business package to 12.0
0.2.192021-09-306438Annotate Oauth2 flow initialization parameters in connector specification
0.2.182021-09-286499Fix field values converting fail
0.2.172021-09-144978Convert values' types according to schema types
0.2.162021-09-146060Fix schema for ads_insights stream
0.2.152021-09-145958Fix url parsing and add report that exposes conversions
0.2.142021-07-194820Improve the rate limit management
0.2.122021-06-203743Refactor 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.102021-06-163973Update version of facebook_business to 11.0
0.2.92021-06-103996Add AIRBYTE_ENTRYPOINT for Kubernetes support
0.2.82021-06-093973Add 80000 as a rate-limiting error code
0.2.72021-06-033646Add missing fields to AdInsights streams
0.2.62021-05-253525Fix handling call rate limit
0.2.52021-05-203396Allow configuring insights lookback window
0.2.42021-05-133395Fix an issue that caused losing Insights data from the past 28 days while incremental sync
0.2.32021-04-283116Wait longer (5 min) for async jobs to start
0.2.22021-04-032726Fix base connector versioning
0.2.12021-03-122391Support FB Marketing API v10
0.2.02021-03-092238Protocol allows future/unknown properties
0.1.42021-02-241902Add include_deleted option in params
0.1.32021-02-151990Support Insights stream via async queries
0.1.22021-01-221699Add incremental support
0.1.12021-01-151552Release Native Facebook Marketing Connector