Skip to main content

Facebook Marketing

Availability:
Available Airbyte CloudAvailable Airbyte OSSAvailable PyAirbyte
Support Level:
Airbyte Connector
Connector Version:
3.3.20(Last updated a day ago)
CDK Version:
5.17.0
Sync Success Rate:
Usage Rate:

This page contains the setup guide and reference information for the Facebook Marketing source connector.

Prerequisites​

Setup guide​

Set up Facebook Marketing​

For Airbyte Cloud:​

  1. Log into your Airbyte Cloud account.
  2. Click Sources and then click + New source.
  3. On the Set up the source page, select Facebook Marketing from the Source type dropdown.
  4. Enter a name for the Facebook Marketing connector.
  5. To authenticate the connection, click Authenticate your account to authorize your Facebook account. Ensure you are logged into the right account, as Airbyte will authenticate the account you are currently logged in to.

For Airbyte Open Source:​

  1. Navigate to the Airbyte Open Source dashboard.
  2. Click Sources and then click + New source.
  3. On the Set up the source page, select Facebook Marketing from the Source type dropdown.
  4. Enter a name for the Facebook Marketing connector.
  1. In the Access Token field, enter the Marketing API access token.

(For Airbyte Open Source) Generate an access token and request a rate limit increase​

To set up Facebook Marketing as a source in Airbyte Open Source, you will first need to create a Facebook app and generate a Marketing API access token. You will then need to request a rate limit increase from Facebook to ensure your syncs are successful.

  1. Navigate to Meta for Developers and follow the steps provided in the Facebook documentation to create a Facebook app.

  2. While creating the app, when you are prompted for "What do you want your app to do?", select Other. You will also need to set the app type to Business when prompted.

  3. From your App’s dashboard, set up the Marketing API.

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

  5. Request a rate limit increase: Facebook heavily throttles API tokens generated from Facebook apps with the default Standard Access tier, 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.

tip

You can use the Access Token Tool at any time to view your existing access tokens, including their assigned permissions and lifecycles.

Facebook Marketing Source Settings​

  1. For Account ID(s), enter one or multiple comma-separated Facebook Ad Account ID Numbers to use when pulling data from the Facebook Marketing API. To find this ID, open your Meta Ads Manager. The Ad Account ID number is in the Account dropdown menu or in your browser's address bar. Refer to the Facebook docs for more information.

  1. (Optional) For Start Date, use the provided datepicker, or enter the date programmatically in the YYYY-MM-DDTHH:mm:ssZ format. If the start date is not set, then all data will be replicated except for Insight data, which only pulls data for the last 37 months.

    info

    Insight tables are only able to pull data from the last 37 months. If you are syncing insight tables and your start date is older than 37 months, your sync will not succeed for those streams.

  1. (Optional) For End Date, use the provided datepicker, or enter the date programmatically in the YYYY-MM-DDTHH:mm:ssZ format. This is the date until which you'd like to replicate data for all Incremental streams. All data generated between the start date and this end date will be replicated. Not setting this option will result in always syncing the latest data.
  1. (Optional) Multiselect the Campaign Statuses to include data from Campaigns for particular statuses.
  1. (Optional) Multiselect the AdSet Statuses to include data from AdSets for particular statuses.
  1. (Optional) Multiselect the Ad Statuses to include data from Ads for particular statuses.
  1. (Optional) Toggle the Fetch Thumbnail Images button to fetch the thumbnail_url and store the result in thumbnail_data_url for each Ad Creative.
  1. (Optional) In the Custom Insights section, you may provide a list of ad statistics entries. Each entry should have a unique name and can contain fields, breakdowns or action_breakdowns. Fields refer to the different data points you can collect from an ad, while breakdowns and action_breakdowns let you segment this data for more detailed insights. Click on Add to create a new entry in this list.

To retrieve specific fields from Facebook Ads Insights combined with other breakdowns, you can choose which fields and breakdowns to sync. However, please note that not all fields can be requested, and many are only functional when combined with specific other fields. For example, the breakdown app_id is only supported with the total_postbacks field. For more information on the breakdown limitations, refer to the Facebook documentation.

info

Additional data streams for your Facebook Marketing connector are dynamically generated according to the Custom Insights you specify. If you have an existing Facebook Marketing source and you decide to update or remove some of your Custom Insights, you must also update the connections to sync these streams by refreshing the schema.

To configure Custom Insights:

  1. For Name, enter a name for the insight. This will be used as the Airbyte stream name.
  1. (Optional) For Level, enter the level of granularity for the data you want to pull from the Facebook Marketing API (account, ad, adset, campaign). Set to ad by default.
  1. (Optional) For Fields, use the dropdown list to select the fields you want to pull from the Facebook Marketing API.
  1. (Optional) For Breakdowns, use the dropdown list to select the breakdowns you want to configure.
  1. (Optional) For Action Breakdowns, use the dropdown list to select the action breakdowns you want to configure.

  1. (Optional) For Action Report Time, enter the action report time you want to configure. This value determines the timing used to report action statistics. For example, if a user sees an ad on Jan 1st but converts on Jan 2nd, this value will determine how the action is reported.

    • impression: Actions are attributed to the time the ad was viewed (Jan 1st).
    • conversion: Actions are attributed to the time the action was taken (Jan 2nd).
    • mixed: Click-through actions are attributed to the time the ad was viewed (Jan 1st), and view-through actions are attributed to the time the action was taken (Jan 2nd).
  1. (Optional) For Time Increment, you may provide a value in days by which to aggregate statistics. The sync will be chunked into intervals of this size. For example, if you set this value to 7, the sync will be chunked into 7-day intervals. The default value is 1 day.
  1. (Optional) For Start Date, enter the date in the YYYY-MM-DDTHH:mm:ssZ format. The data added on and after this date will be replicated. If this field is left blank, Airbyte will replicate all data.
  1. (Optional) For End Date, enter the date in the YYYY-MM-DDTHH:mm:ssZ format. The data added on and before this date will be replicated. If this field is left blank, Airbyte will replicate the latest data.
  1. (Optional) For Custom Insights Lookback Window, you may set a window in days to revisit data during syncing to capture updated conversion data from the API. Facebook allows for attribution windows of up to 28 days, during which time a conversion can be attributed to an ad. If you have set a custom attribution window in your Facebook account, please set the same value here. Otherwise, you may leave it at the default value of 28. For more information on action attributions, please refer to the Meta Help Center.
  1. (Optional) For Page Size of Requests, you can specify the number of records per page for paginated responses. Most users do not need to set this field unless specific issues arise or there are unique use cases that require tuning the connector's settings. The default value is set to retrieve 100 records per page.
  1. (Optional) For Insights Window Lookback, you may set a window in days to revisit data during syncing to capture updated conversion data from the API. Facebook allows for attribution windows of up to 28 days, during which time a conversion can be attributed to an ad. If you have set a custom attribution window in your Facebook account, please set the same value here. Otherwise, you may leave it at the default value of 28. For more information on action attributions, please refer to the Meta Help Center.
  1. (Optional) For Insights Job Timeout, you may set a custom value in range from 10 to 60. It establishes the maximum amount of time (in minutes) of waiting for the report job to complete.
  1. Click Set up source and wait for the tests to complete.

Supported sync modes​

The Facebook Marketing source connector supports the following sync modes:

Supported Streams​

Airbyte also supports the following Prebuilt Facebook Ad Insights Reports:

StreamBreakdownsAction Breakdowns
Ad Insights Action Carousel Card---action_carousel_card_id, action_carousel_card_name
Ad Insights Action Conversion Devicedevice_platformaction_type
Ad Insights Action Product IDproduct_id---
Ad Insights Action Reaction---action_reaction
Ad Insights Action Video Sound---action_video_sound
Ad Insights Action Video Type---action_video_type
Ad Insights Action Type---action_type
Ad Insights Age And Genderage, genderaction_type, action_target_id, action_destination
Ad Insights Delivery Devicedevice_platformaction_type
Ad Insights Delivery Platformpublisher_platformaction_type
Ad Insights Delivery Platform And Device Platformpublisher_platform, device_platformaction_type
Ad Insights Demographics Ageageaction_type
Ad Insights Demographics Countrycountryaction_type
Ad Insights Demographics DMA Regiondmaaction_type
Ad Insights Demographics Gendergenderaction_type
Ad Insights DMAdmaaction_type, action_target_id, action_destination
Ad Insights Countrycountryaction_type, action_target_id, action_destination
Ad Insights Platform And Devicepublisher_platform, platform_position, impression_deviceaction_type
Ad Insights Regionregionaction_type, action_target_id, action_destination

You can segment the Ad Insights 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.

Entity-Relationship Diagram (ERD)​

Facebook Marketing Attribution Reporting​

The Facebook Marketing connector uses the lookback_window parameter to repeatedly read data from the last <lookback_window> days during an Incremental sync. This means some data will be synced twice (or possibly more often) despite the cursor value being up to date, in order to capture updated ads conversion data from Facebook. You can change this date window by adjusting the lookback_window parameter when setting up the source, up to a maximum of 28 days. Smaller values will result in fewer duplicates, while larger values provide more accurate results. For a deeper understanding of the purpose and role of the attribution window, refer to this Meta article.

Data type map​

Integration TypeAirbyte Type
stringstring
numbernumber
arrayarray
objectobject

Troubleshooting​

Handling "Please reduce the amount of data you're asking for, then retry your request" response from Facebook Graph API​

This response indicates that the Facebook Graph API requires you to reduce the fields (amount of data) requested. To resolve this issue:

  1. Go to the Schema Tab: Navigate to the schema tab of your connection.
  2. Select the Source: Click on the source that is having issues with synchronization.
  3. Toggle Fields: Unselect (toggle off) the fields you do not require. This action will ensure that these fields are not requested from the Graph API.

Reference​

Config fields reference

Field
Type
Property name
array<string>
account_ids
object
credentials
string
access_token
string
start_date
string
end_date
array<undefined>
campaign_statuses
array<undefined>
adset_statuses
array<undefined>
ad_statuses
boolean
fetch_thumbnail_images
array<object>
custom_insights
integer
page_size
integer
insights_lookback_window
integer
insights_job_timeout
boolean
action_breakdowns_allow_empty
string
client_id
string
client_secret

Changelog​

Expand to review
VersionDatePull RequestSubject
3.3.202024-11-2548632Update dependencies
3.3.192024-11-0448155Update dependencies
3.3.182024-10-2947894Update dependencies
3.3.172024-10-2843787Update dependencies
3.3.162024-07-1546546Raise exception on missing stream
3.3.152024-07-1542562Add friendly messages for "reduce fields" and "start date" errors
3.3.142024-07-1541958Update cdk to filter invalid fields from configured catalog
3.3.132024-07-1341732Update dependencies
3.3.122024-07-1141644Remove discriminator with missing schemas
3.3.112024-07-1041039Pick request fields from configured json schema properties if present
3.3.102024-07-1041458Update dependencies
3.3.92024-07-0941106Update dependencies
3.3.82024-07-0640934Update dependencies
3.3.72024-07-0140645Use latest CDK version possible
3.3.62024-06-2440241Update AdsInsights fields - removed adset_start
3.3.52024-06-2640545Fixed issue when the STATE is literal None (RFR)
3.3.42024-06-2540485Update dependencies
3.3.32024-06-2240191Update dependencies
3.3.22024-06-0639174[autopull] Upgrade base image to v1.2.2
3.3.12024-06-1539511Fix validation of the spec custom_insights.time_increment field
3.3.02024-06-3033648Add support to field source_instagram_media_id to ad_creatives report
3.2.02024-06-0537625Source Facebook-Marketing: Add Selectable Auth
3.1.02024-06-0138845Update AdsInsights fields - removed cost_per_conversion_lead and conversion_lead_rate
3.0.02024-04-3036608Update body_asset, call_to_action_asset, description_asset, image_asset, link_url_asset, title_asset, video_asset breakdowns schema.
2.1.92024-05-1738301Fix data inaccuracies when wish_bid is requested
2.1.82024-05-0737771Handle errors without API error codes/messages
2.1.72024-04-2436634Update to CDK 0.80.0
2.1.62024-04-2436634Schema descriptions
2.1.52024-04-1737341Move rate limit errors to transient errors.
2.1.42024-04-1637367Skip config migration when the legacy account_id field does not exist
2.1.32024-04-1637320Add retry for transient error
2.1.22024-03-2936689Fix key error account_id for custom reports.
2.1.12024-03-1836025Fix start_date selection behaviour
2.1.02024-03-1235978Upgrade CDK to start emitting record counts with state and full refresh state
2.0.12024-03-0835913Fix lookback window
2.0.02024-03-0135746Update API to v19.0
1.4.22024-02-2235539Add missing config migration from include_deleted field
1.4.12024-02-2135467Fix error with incorrect state transforming in the 1.4.0 version
1.4.02024-02-2032449Replace "Include Deleted Campaigns, Ads, and AdSets" option in configuration with specific statuses selection per stream
1.3.32024-02-1535061Add integration tests
1.3.22024-02-1235178Manage dependencies with Poetry
1.3.12024-02-0534845Add missing fields to schemas
1.3.02024-01-0933538Updated the Ad Account ID(s) property to support multiple IDs
1.2.32024-01-0433934Make ready for airbyte-lib
1.2.22024-01-0233828Add insights job timeout to be an option, so a user can specify their own value
1.2.12023-11-2232731Removed validation that blocked personal ad accounts during check
1.2.02023-10-3131999Extend the AdCreatives stream schema
1.1.172023-10-1931599Base image migration: remove Dockerfile and use the python-connector-base image
1.1.162023-10-1131284Fix error occurring when trying to access the funding_source_details field of the AdAccount stream
1.1.152023-10-0631132Fix permission error for AdAccount stream
1.1.142023-09-2630758Exception should not be raises if a stream is not found
1.1.132023-09-2230706Performance testing - include socat binary in docker image
1.1.122023-09-2230655Updated doc; improved schema for custom insight streams; updated SAT or custom insight streams; removed obsolete optional max_batch_size option from spec
1.1.112023-09-2130650Fix None issue since start_date is optional
1.1.102023-09-1530485added 'status' and 'configured_status' fields for campaigns stream schema
1.1.92023-08-3129994Removed batch processing, updated description in specs, added user-friendly error message, removed start_date from required attributes
1.1.82023-09-0429666Adding custom field boosted_object_id to a streams schema in campaigns catalog CustomAudiences
1.1.72023-08-2129674Exclude rule from stream CustomAudiences
1.1.62023-08-1829642Stop batch requests if only 1 left in a batch
1.1.52023-08-1829610Automatically reduce batch size
1.1.42023-08-0829412Add new custom_audience stream
1.1.32023-08-0829208Add account type validation during check
1.1.22023-08-0329042Fix broken advancedAuth references for spec
1.1.12023-07-2627996Remove reference to authSpecification
1.1.02023-07-1126345Add new action_report_time attribute to AdInsights class
1.0.12023-07-0727979Added the ability to restore the reduced request record limit after the successful retry, and handle the unknown error (code 99) with the retry strategy
1.0.02023-07-0527563Migrate to FB SDK version 17
0.5.02023-06-2627728License Update: Elv2
0.4.32023-05-1227483Reduce replication start date by one more day
0.4.22023-06-0927201Add complete_oauth_server_output_specification to spec
0.4.12023-06-0226941Remove authSpecification from spec.json, use advanced_auth instead
0.4.02023-05-2926720Add Prebuilt Ad Insights reports
0.3.72023-05-1226000Handle config errors
0.3.62023-04-2722999Specified date formatting in specification
0.3.52023-04-2624994Emit stream status messages
0.3.42023-04-1822990Increase pause interval
0.3.32023-04-1425204Fix data retention period validation
0.3.22023-04-0825003Don't fetch thumbnail_data_url if it's None
0.3.12023-03-2724600Reduce request record limit when retrying second page or further
0.3.02023-03-1619141Added Level parameter to custom Ads Insights
0.2.862023-03-0123625Add user friendly fields description in spec and docs. Extend error message for invalid Account ID case.
0.2.852023-02-1423003Bump facebook_business to 16.0.0
0.2.842023-01-2722003Set AvailabilityStrategy for streams explicitly to None
0.2.832023-01-1321149Videos stream remove filtering
0.2.822023-01-0921149Fix AdAccount schema
0.2.812023-01-0521057Remove unsupported fields from request
0.2.802022-12-2120736Fix update next cursor
0.2.792022-12-0720402Exclude Not supported fields from request
0.2.782022-12-0720165Fix fields permission error
0.2.772022-12-0620131Update next cursor value at read start
0.2.762022-12-0320043Allows action_breakdowns to be an empty list - bugfix for #20016
0.2.752022-12-0320016Allows action_breakdowns to be an empty list
0.2.742022-11-2519803New default for action_breakdowns, improve "check" command speed
0.2.732022-11-2119645Check "breakdowns" combinations
0.2.722022-11-0418971Handle FacebookBadObjectError for empty results on async jobs
0.2.712022-10-3118734Reduce request record limit on retry
0.2.702022-10-2618045Upgrade FB SDK to v15.0
0.2.692022-10-1718045Remove "pixel" field from the Custom Conversions stream schema
0.2.682022-10-1217869Remove "format" from optional datetime end_date field
0.2.672022-10-0417551Add cursor_field for custom_insights stream schema
0.2.652022-09-2917371Fix stream CustomConversions enable_deleted=False
0.2.642022-09-2217304Migrate to per-stream state.
0.2.642022-09-2217027Limit time range with 37 months when creating an insight job from lower edge object. Retry bulk request when getting error code 960
0.2.632022-09-0615724Add the Custom Conversion stream
0.2.622022-09-0116222Remove end_date from config if empty value (re-implement #16096)
0.2.612022-08-2916096Remove end_date from config if empty value
0.2.602022-08-1915788Retry FacebookBadObjectError
0.2.592022-08-0415327Shift date validation from config validation to stream method
0.2.582022-07-2515012Add DATA_RETENTION_PERIODvalidation and fix failed_delivery_checks field schema type issue
0.2.572022-07-2514831Update Facebook SDK to version 14.0.0
0.2.562022-07-1914831Add future start_date and end_date validation
0.2.552022-07-1814786Check if the authorized user has the "MANAGE" task permission when getting the funding_source_details field in the ad_account stream
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
Was this page helpful?