Advanced Analytica Advanced Analytica: IBOM
← All connectors
Facebook Marketing logo

Source connector

Facebook Marketing

Set up Facebook Marketing as a source and move its data into your chosen destination.

Version 6.1.12 certified generally available

Facebook Marketing

Use this guide to set up and reference the Facebook Marketing source connector.

Prerequisites

  • A Facebook Ad Account ID for each ad account you want to sync.
  • Access to each ad account. If you aren’t an admin, an admin must grant you access to it. For system user access tokens, assign the ad accounts to that system user.
  • To authenticate with an access token (required for Airbyte Open Source, optional for Airbyte Cloud):
    • A Meta app created with the Measure ad performance data with Marketing API use case and connected to a business portfolio.
    • A system user access token with the ads_read, ads_management, and business_management permissions. See Create a Meta app and access token.

Set up the connector

Set up Facebook Marketing

For Airbyte Cloud:

  1. Log into your Airbyte Cloud account.
  2. Click Sources, 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. For Authentication, choose one of these options:
    • Authenticate via Facebook Marketing (Oauth): Click Authenticate your account to authorise your Facebook account. First, confirm you’re logged in to the correct Facebook account. Airbyte authenticates your current account, which must access every ad account you want to sync.
    • Service Account Key Authentication: Enter a system user access token. To create one, follow Create a Meta app and access token.

For Airbyte Open Source:

  1. Go to the Airbyte Open Source dashboard.
  2. Click Sources, 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. For Authentication, select Service Account Key Authentication and enter a system user access token. To create one, follow Create a Meta app and access token.

Create a Meta app and token

Create a Meta app and system user access token for Service Account Key Authentication by following these steps. Meta occasionally changes its UI labels. If a label differs, check the linked Meta documentation.

1. Register as a Meta developer

If you don’t already have one, register as a Meta developer. A developer account gives you access to the App Dashboard.

2. Create a Meta app

  1. Go to the Meta for Developers App Dashboard and click Create App.
  2. When prompted to add a use case, select Measure ad performance data with Marketing API. This adds the ads_read, ads_management, and business_management permissions and the Marketing API Access Tier feature. Don’t select Create an app without a use case. That option creates an app without permissions or products.
  3. Connect the app to the business portfolio that owns or can access your ad accounts. Meta recommends a verified business portfolio. You need one to access ad accounts owned by other businesses.
  4. Finish creating the app.

For details, see Meta’s Create an app and Marketing API: Get started guides.

3. Generate a system user token

A system user is a non-human account in your business portfolio. Its token isn’t tied to a personal Facebook login. This makes it Meta’s recommended option for server-to-server integrations such as Airbyte.

  1. In Meta Business Settings, go to Users > System users. Click Add to create a system user. See Meta’s Add system users to your business portfolio guide.
  2. Select the system user and click Assign assets. Assign every ad account you want to sync, with at least permission to view performance. Also assign the Meta app you created in Step 2.
  3. Click Generate new token and select your app.
  4. Choose an expiration. A 60-day token is more secure. You must generate and update it in Airbyte before it expires. A token that never expires doesn’t need refreshing.
  5. Select the ads_read, ads_management, and business_management permissions, then generate the token.
  6. Copy the token and store it securely. Enter it as the Access Token when you choose Service Account Key Authentication.

The system user and app must belong to the same business portfolio. See Meta’s Install apps and generate tokens guide for details.

:::tip Check a token’s permissions and expiration with Meta’s Access Token Debugger. :::

4. Get full Marketing API access

New apps begin with Limited access to the Marketing API. Limited access has strict rate limits and supports development only. It’s usually too slow for regular syncs.

  1. In the App Dashboard, find the Marketing API Access Tier feature added by the use case.
  2. Click +Upgrade to request Full access.

Your app needs at least 500 Marketing API calls within 15 days to gain and keep full access. Its error rate must stay below 15% across its last 500 calls. Meta checks these requirements continuously and can return an app to limited access.

You only need advanced access to the ads_read or ads_management permissions when syncing ad accounts owned by other businesses. This access requires App Review and business verification. See Meta’s Marketing API: Authorization guide for details.

Fix permission errors

If a connection check or sync returns an ad account permission error, check these details:

  • The Account ID is correct. Enter only the number, without the act_ prefix.
  • The authenticated user has access to the ad account. With OAuth, Airbyte uses the Facebook account active when you clicked Authenticate your account. With an access token, assign the ad account to the system user. Check access in Meta Business Settings under Accounts > Ad accounts.
  • The token has the required permissions. Use the Access Token Debugger to confirm the token includes ads_read, ads_management, and business_management. Also confirm it hasn’t expired.
  • The ad account belongs to your business portfolio, or is shared with it. If another business owns the ad account, it must share the account with your business portfolio.

Configure source settings

  1. For Account ID(s), enter one or more comma-separated Facebook Ad Account ID numbers. To find an ID, open Meta Ads Manager and go to your ad account’s Settings. Look under Account overview. Enter only the number, without the act_ prefix.
  1. (Optional) For Start Date, use the datepicker or enter the date programmatically in YYYY-MM-DDTHH:mm:ssZ format. Without a start date, the connector replicates all data except Insights data. It only pulls Insights data from the last 37 months.

:::info Insight tables can only pull data from the last 37 months. If your start date is older, those streams won’t sync successfully. :::

  1. (Optional) For End Date, use the datepicker or enter the date programmatically in YYYY-MM-DDTHH:mm:ssZ format. The connector replicates Incremental stream data generated between the start date and this end date. Leave this option unset to keep syncing the latest data.
  1. (Optional) Select multiple Campaign Statuses values to include Campaigns data for specific statuses.
  1. (Optional) Select multiple AdSet Statuses values to include AdSets data for specific statuses.
  1. (Optional) Select multiple Ad Statuses values to include Ads data for specific statuses.

:::caution Status filtering and missing records

If you select no Campaign Statuses, AdSet Statuses, or Ad Statuses, the connector uses the Facebook Marketing API default. The API excludes records in ARCHIVED and DELETED states. As a result, archived campaigns, ad sets, and ads won’t appear in your synced data.

Select every status you need to ensure a complete dataset. This matters especially with Full Refresh sync mode. Previously synced records that are now archived won’t be fetched again unless you include ARCHIVED. :::

  1. (Optional) Toggle the Fetch Thumbnail Images button to fetch the thumbnail_url. The connector stores the result in thumbnail_data_url for each Ad Creative.
  1. (Optional) Change the default action breakdowns for the Built-in Ads Insights stream. Remove every value to create an empty list, or change the defaults.
  1. (Optional) In Custom Insights, add a list of ad statistics entries. Give each entry a unique name. Entries can contain fields, breakdowns, or action breakdowns (action_breakdowns). Fields define the ad data points collected. Breakdowns and action breakdowns segment that data for more detail. Click Add to add an entry. See Custom Insights settings for each entry’s options.

Choose the fields and breakdowns to sync specific Facebook Ads Insights data. You can’t request every field, and many only work with specific field combinations. For example, the app_id breakdown only supports the total_postbacks field. See the Facebook documentation for breakdown limits.

:::info The connector dynamically generates more data streams from your Custom Insights. After changing or removing Custom Insights, refresh the schema for connections that sync those streams. :::

Optionally, configure each custom insight’s Custom Insights settings and the Advanced settings. Then click Set up source and wait for the tests to finish.

Configure Custom Insights

Define the data each custom insight pulls:

  1. For Name, enter an insight name. Airbyte uses this as the stream name.
  1. (Optional) For Level, enter the data granularity to pull from the Facebook Marketing API: account, ad, adset, or campaign. The default is ad. Your selected level determines the deduplication primary key in Incremental Append + Deduped sync mode. See primary key behavior by level for details.
  1. (Optional) For Fields, select the Facebook Marketing API fields you want to pull from the dropdown.
  1. (Optional) For Breakdowns, select the breakdowns you want to configure from the dropdown.

:::info High-cardinality breakdowns

Some breakdowns, including product_id, can produce thousands of rows daily. Connection setup still succeeds for these breakdowns. If Facebook’s synchronous validation call returns "Please reduce the amount of data you're asking for", the connector retries using a one-day window. If that call also exceeds the limit, it logs a warning. Real syncs use async jobs and aren’t affected by this limit. :::

  1. (Optional) For Action Breakdowns, select the action breakdowns you want to configure from the dropdown.
  1. Action Report Time has been deprecated and hidden from the UI since v3.5.0. It defaults to mixed and can’t be changed through the Airbyte UI. When set programmatically through API, Terraform, or PyAirbyte, the available values are impression, conversion, or mixed. These attribute results to view time, action time, or click-through and view-through times, respectively.

Set each custom insight’s time range and attribution window:

  1. (Optional) For Time Increment, enter the number of days used to aggregate statistics. The sync runs in intervals of this size. For example, enter 7 for seven-day intervals. The default is 1 day. You can’t use this with Time Increment Period.
  1. (Optional) For Time Increment Period, select a calendar-aligned aggregation period instead of a fixed number of days. This creates consistently aligned time buckets, regardless of the start date. It makes comparisons between clients easier. Available options:

    • daily: equivalent to Time Increment = 1, creating one-day buckets.
    • weekly: aligns with Monday-to-Sunday calendar weeks.
    • monthly: aligns with calendar months, from the first through the last day. The Facebook API supports this natively.

    You can’t use this with Time Increment. Switching between Time Increment and Time Increment Period triggers a full re-sync.

  1. (Optional) For Start Date, enter the date in YYYY-MM-DDTHH:mm:ssZ format. Airbyte replicates data added on or after this date. Leave this field blank to replicate all data.
  1. (Optional) For End Date, enter the date in YYYY-MM-DDTHH:mm:ssZ format. Airbyte replicates data added on or before this date. Leave this field blank to replicate the latest data.
  1. (Optional) For Custom Insights Lookback Window, set a lookback window in days to capture updated conversion data during syncs. Facebook supports click-through attribution windows of up to 28 days. A conversion can be attributed to an ad during this period. View-through attribution is limited to 1 day. Match any custom attribution window set in your Facebook account. Otherwise, keep the default of 28 days. See the Meta Help Center for details about action attributions.
  1. (Optional) Toggle Include Incrementality to add the incrementality attribution window to this custom insight stream. When enabled, action metrics such as actions, action_values, and cost_per_action_type include an incrementality field. This setting only affects this custom insight. See the global Include Incrementality setting in Advanced settings for details.

Advanced settings

Most users don’t need to change these settings.

  1. (Optional) For Page Size of Requests, set the records per page for paginated responses. Only change this field for specific issues or use cases requiring connector tuning. The default is 100 records per page.
  1. (Optional) For Insights Window Lookback, set a lookback window in days to capture updated conversion data during syncs. Facebook supports click-through attribution windows of up to 28 days. A conversion can be attributed to an ad during this period. View-through attribution is limited to 1 day. Match any custom attribution window set in your Facebook account. Otherwise, keep the default of 28 days. See the Meta Help Center for details about action attributions.
  1. (Optional) For Insights Job Timeout, set a custom value from 10 to 60 minutes. This defines the maximum wait for the report job to finish.
  1. (Optional) Toggle Include Incrementality to add the incrementality attribution window to all built-in Ads Insights streams. When enabled, the connector adds "incrementality" to the action_attribution_windows parameter sent to the Facebook API. Action metrics such as actions, action_values, and cost_per_action_type then include an incrementality field. This field contains the incremental lift value attributed to the ad. It’s populated only for ad accounts with active Conversion Lift studies configured in Facebook. For accounts without lift studies, the field is null. This setting is disabled by default. See the Ads Action Stats API reference for details about the incrementality attribution window.

Supported sync modes

The Facebook Marketing source connector supports these sync modes:

Supported streams

Stream NameAPI DocsSupports Full RefreshSupports Incremental
activitiesLatest✅✅
ad_accountLatest✅❌
ad_creativesLatest✅❌
ad_creatives_from_adsLatest✅✅
ad_setsLatest✅✅
adsLatest✅✅
ads_insightsLatest✅✅
campaignsLatest✅✅
custom_conversionsLatest✅❌
custom_audiencesLatest✅❌
imagesLatest✅✅
videosLatest✅✅

Notes on Streams:

:::info Custom Audiences The Facebook Marketing API limits syncing of the rule field in the Custom Audiences stream. As a result, some records may omit this field. Syncing it can also return the error Please reduce the amount of data. See Troubleshooting for details. :::

:::info Ad Creatives From Ads The ad_creatives_from_ads stream provides an alternative to ad_creatives. It fetches creative data through the Ads endpoint instead of AdCreatives. Use it when ad_creatives returns “Please reduce the amount of data you’re asking for.” Its output matches ad_creatives and adds an updated_time field containing the parent ad’s timestamp. It only returns creatives linked to ads and excludes orphaned creatives. See Troubleshooting for details.

During incremental syncs, the cursor uses the parent ad’s updated_time because AdCreative has no timestamp. Content changes create a new creative and are always captured. Other changes might not update the parent ad’s timestamp and can be missed. These include in-place renames, status changes, ad-label changes, and edits to the page post behind effective_object_story_id. Use full refresh to capture these changes. The first incremental sync reads the complete ads history to initialise the cursor. The start_date setting doesn’t apply to this stream. Time savings begin with the second sync. :::

Airbyte also supports these 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 Comscore Market Regioncomscore_marketaction_type
Ad Insights Demographics Gendergenderaction_type
Ad Insights Comscore Marketcomscore_marketaction_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

:::info Breakdown opt-in requirement (effective August 6, 2026) From August 6, 2026, Meta requires certain ad accounts to opt in to impression_device, hourly_stats_aggregated_by_audience_time_zone, and frequency_value breakdowns. This affects the Ad Insights Platform And Device stream and Custom Insights streams configured with these breakdowns. The requirement only applies to non-sales-supported accounts. The connector gets insights through asynchronous report jobs, which Meta documents as a supported fallback. If these streams return no data, ask your account administrator to opt in through Ads Manager. See Meta’s 2026 out-of-cycle changes for details. :::

You can segment the Ad Insights table using the following information. With normalisation enabled, each segment syncs as a separate table:

  • Country
  • Comscore Market
  • Gender & Age
  • Platform & Device
  • Region

For details, see the Facebook Insights API documentation.

Custom Insights primary keys {#custom-insights-primary-keys}

The configured Level setting determines each Custom Insights stream’s primary key. It controls record deduplication in Incremental Append + Deduped sync mode.

LevelPrimary Key Fields
ad (default)date_start, account_id, ad_id, plus any configured breakdowns
adsetdate_start, account_id, adset_id, plus any configured breakdowns
campaigndate_start, account_id, campaign_id, plus any configured breakdowns
accountdate_start, account_id, plus any configured breakdowns

Built-in Ads Insights streams and Prebuilt Ads Insights Reports use level=ad by default. They always include ad_id in the primary key.

Entity-relationship diagram

Insights timezone handling

The Facebook Insights API interprets time_range date filters, since and until, in the ad account’s timezone rather than UTC. For timezones ahead of UTC, the connector detects each account’s timezone and adjusts its sync date range. Examples include Asia/Tokyo at UTC+9 and Europe/Berlin at UTC+1. This prevents the connector from missing the current day’s data. The per-account adjustment covers all built-in and custom Ads Insights streams. You don’t need to configure it.

When one connection syncs ad accounts across different timezones, the connector calculates each account’s date range independently.

Attribution reporting

During Incremental syncs, the connector uses lookback_window to reread the previous <lookback_window> days. This captures updated Facebook ads conversion data, but may sync some data more than once. You can change the window through lookback_window during source setup, up to 28 days. Smaller values create fewer duplicates. Larger values provide more accurate results. See Meta article for more about the attribution window’s purpose.

IP allow list

If you use Airbyte Cloud and restrict access by IP, add the Airbyte Cloud IP addresses to your allow list.

Data type map

Integration TypeAirbyte Type
stringstring
numbernumber
arrayarray
objectobject

Troubleshooting

Reduce requested data

This response means the Facebook Graph API rejected a synchronous request because one response would contain too much data. The required action depends on where the error occurs.

During a sync on a stream other than ad_creatives: request fewer fields for that stream.

  1. Go to the Schema Tab: Go to your connection’s schema tab.
  2. Select the Source: Click the source with sync issues.
  3. Toggle Fields: Clear or toggle off fields you don’t need. The Graph API will no longer receive requests for those fields.

During a sync on the ad_creatives stream: switch to the ad_creatives_from_ads stream. See the next section for details.

During connection setup for a custom insight using a high-cardinality breakdown, such as product_id: you don’t need to act. Since v5.2.7, the connector retries breakdown validation with a one-day range. If that also exceeds the limit, it logs a warning and continues. The breakdown combination remains validated. Real syncs aren’t affected because async jobs handle large result sets.

Fix Ad Creatives data errors

If ad_creatives returns “Please reduce the amount of data you’re asking for, then retry your request”, you have another option. If you don’t want to disable fields, switch to ad_creatives_from_ads. This stream gets the same creative data through the Ads endpoint, one creative at a time. This avoids the data-size limit. Its output schema matches ad_creatives.

ad_creatives_from_ads is slower than ad_creatives because it makes a separate API call for each creative. It only returns creatives linked to ads, so orphaned creatives aren’t included.

Ad creatives without object_story_spec

For some Degrees of Freedom creatives, the Graph API rejects object_story_spec requests with error 100 / 2446211. The error reads “First Dof Value Should Match Object Story Spec Field”. The ad_creatives and ad_creatives_from_ads streams return these creatives without object_story_spec instead of failing. They also log a warning containing the creative ID. ad_creatives reads every creative during each sync, restoring the field when the API returns it. In incremental mode, ad_creatives_from_ads only rereads a creative after its parent ad changes. Therefore, refresh that stream to backfill object_story_spec.

Find missing Campaigns, Ad Sets, or Ads {#missing-records-status-filtering}

If campaigns, ad sets, or ads are missing from synced data, check your status filters first.

By default, the Facebook Marketing API excludes records in ARCHIVED and DELETED states. Empty Campaign Statuses, AdSet Statuses, or Ad Statuses fields don’t override this default. The connector therefore omits archived or deleted records without notice.

This is especially visible after a Full Refresh sync. Records synced while active won’t reappear if they’ve since been archived. To confirm, look up the missing record IDs directly through the Facebook API. Individual ID lookups return records regardless of status. The connector’s listing endpoints don’t.

To restore the missing records:

  1. Go to Settings > Source > Facebook Marketing.
  2. For Campaign Statuses, AdSet Statuses, and Ad Statuses, select every status you need. At minimum, add ARCHIVED alongside the active statuses.
  3. Run a Full Refresh sync to fetch the complete dataset again.

Missing view-through attribution data

On January 12, 2026, Meta removed support for 7-day and 28-day view-through attribution windows in the Ads Insights API. These windows are 7d_view and 28d_view. Version v4.1.3 removed them from request parameters for ads_insights and Ads Insights Reports streams. Version v5.0.0 also removed the 7d_view and 28d_view columns from stream schemas. Data previously returned for these windows is no longer available. See Meta’s 2025 Out-Of-Cycle Changes for details.

Available data

  • The 1d_view attribution window remains supported and returns data where applicable.
  • This change doesn’t affect click-through attribution windows: 1d_click, 7d_click, and 28d_click.

Fix an invalid token after OAuth

Your saved token may be corrupt if a connection check fails soon after OAuth re-authentication. The error may say “Invalid access token” or “Error validating access token”. Chrome’s autofill feature can cause this problem.

Cause

Chrome may interpret two adjacent fields as a login form. These are the Ad Account ID text field and Access Token password field. It can then silently insert saved browser credentials. Saving this autofilled value lets an internal migration overwrite the valid OAuth token. All later syncs and connection checks then fail.

Connector version 6.0.2 fixed this issue (airbytehq/airbyte#81331). Upgrade older versions to 6.0.2 or later to prevent it recurring.

Fix

  1. Open your Facebook Marketing source configuration in Airbyte.
  2. Click Authenticate your account or Re-authenticate and complete OAuth again. This creates a fresh, valid access token.
  3. Click Save, then run Test Connection to confirm the new token works.

If the connection check still fails after re-authentication, contact Airbyte Support for further help.

Missing purchase metrics

Purchases or purchase value fields in Ads Insights may look incomplete or under-reported for certain date ranges. This issue affects several platforms, including direct Facebook API calls. It isn’t specific to Airbyte and relates to intermittent upstream API behaviour.

What happens

API users have reported missing purchase metrics on Reddit and in Facebook Developer and Community forums. Sometimes, action values such as offsite_conversion.fb_pixel_purchase appear at ad or ad set level. They may disappear at campaign or account level. API users documented similar behaviour in the Facebook Developer Community several years ago. It appears to have become more frequent since 2025.

Why it happens

Facebook’s Ads Insights API dynamically aggregates and filters metrics. Purchase data may be missing or inconsistent for these reasons.

  • Attribution window processing: Facebook reattributes purchases up to 28 days after a click or 1 day after an impression. Recent data can therefore change or seem missing before finalisation.

  • Complex breakdowns or field combinations: using multiple breakdowns such as action_type, action_target_id, and action_destination can produce partial or truncated responses.

  • Intermittent API behaviour: Facebook’s data availability and aggregation can vary by endpoint and attribution window, causing temporary inconsistencies.

  • Throughput and rate limits: exceeding API throughput or running many queries concurrently can return partial datasets or suppress some metrics.

Resolve the issue

  1. Refresh recent data: set the connector’s Start Date just before the discrepancy begins. Then run a “Refresh and Retain” sync from the connection’s settings tab. Many customers find this restores missing metrics.

  2. Simplify breakdowns: temporarily remove Action breakdowns such as action_type, action_target_id, and action_destination from Ads Insights. Sync again, then reintroduce them gradually.

  3. Reduce query size: for custom report streams, first sync fewer fields or a narrower date range. Check the results, then expand incrementally.

  4. Limit concurrency: stagger sync schedules for Facebook Marketing connections that share an access token. This can reduce contention and avoid Facebook API limits. It only works across separate connections. You can’t stagger syncs within one connection containing several ad accounts.

  5. Check Facebook Ads Manager: compare values at ad or ad set level. Action values often appear there when aggregated results omit them.

Changelog

Expand to review
VersionDatePull RequestSubject
6.1.122026-11-0490852Build the insights stream schema once per stream instead of for every record, which speeds up insights syncs, most of all custom insights
6.1.112026-11-0490896Raise minimum supported Python version to 3.11
6.1.102026-11-0490974Update CDK to 7.45
6.1.92026-10-2189624Keep the custom insights primary key in the configured breakdowns order so it no longer changes between syncs
6.1.82026-10-2074884Retry dropped connections, truncated responses, and read timeouts from the Facebook API, and report them as transient errors if retries are exhausted
6.1.72026-10-1689019Include Meta’s user-facing error title and message, plus the error subcode, in otherwise generic Graph API error messages
6.1.62026-10-1689047Fix in-app setup guide rendering in Airbyte Cloud, update access token setup steps to match Meta’s current docs, and correct field descriptions
6.1.52026-10-1689006Upgrade to Python 3.13 and python-connector-base 4.1.1
6.1.42026-10-1689020Fix ad_creatives and ad_creatives_from_ads failing on Facebook error 2446211 by emitting affected creatives with a null object_story_spec
6.1.32026-09-3087588Fix insights streams cursor moving backwards after interrupted sync attempts (causing progressively wider re-reads), clean up stale completed slices in state, and fix cursor advancement for monthly/weekly time increments
6.1.22026-09-2186315Fix ad-account quota errors (code 17/2446079) being retried as transient failures: read rate-limit headers on failed calls and wait out the block (API-provided reset estimate when present, 10-minute re-checks otherwise, up to 1 hour); read every business-use-case entry and the ad-account reset time from the rate-limit headers; the connection check fails fast instead of waiting
6.1.12026-08-2474266feat(source-facebook-marketing): add opt-in engaged view (ev) attribution window (AI-Triage PR)
6.1.02026-08-0483704Add incremental sync support to the ad_creatives_from_ads stream
6.0.22026-06-3081331Hide legacy top-level access_token field from UI to prevent Chrome autofill from corrupting OAuth tokens
6.0.12026-06-2480779Fix TypeError in CursorPatch.load_next_page() when Facebook API returns malformed (non-dict) responses or data items
6.0.02026-06-2380324Replace deprecated ads_insights_dma and ads_insights_demographics_dma_region streams with ads_insights_comscore_market and ads_insights_demographics_comscore_market_region following Meta’s DMA → Comscore Market transition. Remove dma from Custom Insights breakdowns.
5.2.142026-06-1179643Replace the cryptic system_error on un-generatable Ads Insights reports with a clear, actionable config_error that names the offending stream/field/breakdown and how to resolve it (unselect the field, or disable the incrementality attribution window) (oncall #12088).
5.2.132026-06-0378060Fixed sync failures on Ads Insights breakdown streams caused by invalid field requests; cap async-job status-poll batches at Meta’s 50-per-batch limit when a parent job has many children; tolerate malformed responses on the throttle-refresh ping instead of failing the whole sync.
5.2.122026-05-2778451Promoted release candidate to GA
5.2.12-rc.12026-05-2075457Bump facebook-business SDK from v23 to v25 to support Marketing API v25.0 before v23.0 sunset on June 9, 2026
5.2.112026-04-2876977Bump airbyte-cdk to ^7.17.4; facebook-business updated to 23.0.3 via lockfile refresh
5.2.102026-04-2776064Fix ad_account stream crash by catching AirbyteTracedException wrapping FacebookRequestError in list_objects
5.2.92026-04-2476995Fix TypeError crash when Facebook API returns error response with no message body
5.2.82026-04-2476996Cast API throttle and rate-limit header values to float to prevent TypeError when Facebook returns string-typed numbers
5.2.72026-04-2376951Promoted release candidate to GA
5.2.7-rc.12026-04-1674127Allow connection setup to succeed for custom insights with high-cardinality breakdowns (for example, product_id)
5.2.62026-04-1376101Replace ValueError with AirbyteTracedException for proper error classification in async job splitting
5.2.52026-04-0876134Fix undefined APILimit name in async_job.py type annotations
5.2.42026-04-0275981Fix ad_creatives_from_ads stream crash by catching AirbyteTracedException in creative detail fetching
5.2.32026-04-0275372Fix _collect_child_ids: clamp since <= until after retention validation, add retry logic for transient Job Failed status, and apply fields_exceptions filtering to exclude problematic fields from API requests
5.2.22026-03-1775130Extend upgrade deadline for version 5.0.0 breaking changes to 2026-04-10
5.2.12026-03-0974147Add calendar-aligned time periods (daily/weekly/monthly) to InsightConfig
5.2.02026-03-0972835Add ad_creatives_from_ads stream as alternative to ad_creatives
5.1.12026-03-0374255update upgradeDeadline for the v5.0.0
5.1.02026-03-0274134Add opt-in include_incrementality config option to append incrementality to action attribution windows
5.0.12026-02-2473281fix(source-facebook-marketing): Fix Facebook Marketing UTC hardcoding with per-account timezone detection
5.0.02026-02-2072779Custom Insights streams now use level-based primary keys; removed deprecated 7d_view and 28d_view attribution window columns; removed wish_bid field. All users should refresh schema and reset affected streams.
4.2.12026-02-0972952fix(source-facebook-marketing): classify ‘Invalid OAuth access token’ as config_error (AI-Triage PR)
4.2.02026-01-0771029Add 98 missing fields for custom insights streams including objective_results transformation
4.1.32026-01-0670349Remove deprecated 7d_view and 28d_view attribution windows (Facebook API deprecation effective January 12, 2026)
4.1.22025-11-1069204Add config migration that adds default action breakdowns
4.1.12025-11-0469169Finalize progressive rollout.
4.1.1-rc.12025-10-2768632Performance improvement on normalization
4.1.02025-10-0667081Promoting release candidate 4.1.0-rc.2 to a main version.
4.1.0-rc.22025-10-0266976Add missing breakdown user_segment_key
4.1.0-rc.12025-09-2566000Add field-based splitting for failed Ad-level async jobs; Upgrade to CDK v7
4.0.12025-09-1566182Classify subcode 2446289 error as config error
4.0.02025-08-2765533Migrate to Marketing API v23
3.5.122025-08-2365288Update dependencies
3.5.112025-08-1964911Allow overriding action breakdowns for default Ads Insights stream.
3.5.102025-08-1665010Update dependencies
3.5.92025-08-0964679Update dependencies
3.5.82025-08-0264406Update dependencies
3.5.72025-07-2663934Update dependencies
3.5.62025-07-1963604Update dependencies
3.5.52025-07-1263029Update dependencies
3.5.42025-07-0562811Update dependencies
3.5.32025-06-2862413Update dependencies
3.5.22025-06-2161958Update dependencies
3.5.12025-06-1461290Update dependencies
3.5.02025-06-0961477Removed action_report_time from spec as deprecated
3.4.92025-05-2460025Update dependencies
3.4.82025-05-0358889Update dependencies
3.4.72025-04-1958296Update dependencies
3.4.62025-04-1257827Update dependencies
3.4.52025-04-0557219Update dependencies
3.4.42025-03-2956467Update dependencies
3.4.32025-02-2054171Fix retry pattern
3.4.22025-03-2255991Update dependencies
3.4.12025-03-2155760Fixed KeyError during discovery due to outdated breakdown schema
3.4.02024-12-2450418Add learning_stage_info field to ad_sets stream
3.3.352025-03-0855307Update dependencies
3.3.342025-03-0154990Update dependencies
3.3.332025-02-2254386Update dependencies
3.3.322025-02-1553721Update dependencies
3.3.312025-02-1153626Log Utilization type
3.3.302025-02-0853330Update dependencies
3.3.292025-02-0152835Update dependencies
3.3.282025-01-2752032Update to API version 21
3.3.272025-01-2552365Update dependencies
3.3.262025-01-1851706Update dependencies
3.3.252025-01-1151080Update dependencies
3.3.242025-01-0450922Update dependencies
3.3.232024-12-2850533Update dependencies
3.3.222024-12-2150014Update dependencies
3.3.212024-12-1449197Update dependencies
3.3.202024-11-2548632Starting with this version, the Docker image is now rootless. Please note that this and future versions will not be compatible with Airbyte versions earlier than 0.64
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.12024-06-1339439Apply configured statuses to ads insight streams
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-0433828Make 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.662022-09-2917371Fix stream CustomConversions enable_deleted=False
0.2.652022-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-179805Performance 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
Advanced Analytica

Most businesses are sitting on information they can’t use at speed. The people who hold it are busy, and when they leave, the knowledge goes with them. The documents are static, and the processes around them weren’t designed for AI.

Advanced Analytica works with these businesses to turn that information into structured data assets. Once they're integrated, AI systems can govern it, and the business can use it. We bring in the strategy, the specification and the AI skills to rework how the business operates.

MOVE FAST. STAY SAFE.