Facebook Marketing

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

Prerequisites

• A Facebook Ad Account ID

• For Pipeloom:

  • Facebook app with the Marketing API enabled
  • The following permissions: ads_management, ads_read, business_management and read_insights.

Setup guide

Set up Facebook Marketing

For Pipeloom:

1. Navigate to the Pipeloom 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.

5. For Authentication, select Service Account Key Authentication and enter the Marketing API access token you generated. See the steps below for how to generate a token.

Pipeloom

This guide outlines the steps required to configure your Meta Developer account and create an app to utilize the Facebook Marketing API.

Follow these five key steps:

1. Register as a Meta Developer: If you haven't already, create your developer account.
2. Create a New App: Set up a new application within your Developer Dashboard.
3. Integrate the Marketing API: Add the Marketing API product to your newly created app.
4. Generate an Access Token: Obtain the necessary credentials to authenticate your API requests.
5. Request Increased Rate Limits: Ensure your app can handle the required data volume by requesting Advanced Access.

1. Register as a Meta Developer

A Meta Developer account is your gateway to the App Dashboard, SDKs, APIs, development tools, and documentation.

To register, follow the official instructions: Register as a Meta Developer

2. Create a New App

Your Meta app serves as a container for your API credentials and permissions. Meta uses it to monitor API usage, enforce rate limits, and ensure application security.

• Go to the Meta for Developers App Dashboard and click Create App.

• Important: During the setup process, at the "Use case" step, select:

  Create an app without a use case Choose this option if you'd like to get an app ID without automatically adding any permissions, features, or products.

• App Type: Choose Business as the app type when prompted.

3. Add the Marketing API Product

After creating your app, you’ll need to enable the Marketing API to begin making requests.

• In your app’s dashboard, open the sidebar menu.
• Click Add Product.
• Find and select Marketing API from the list of available products.

For an overview of the Marketing API, see the Facebook Developer Marketing API Docs.

4. Generate an Access Token

To authorize your application to interact with the Facebook Marketing API, you'll need to generate an access token with the appropriate permissions.

• From your app's dashboard, go to Marketing API > Tools.

• In the Token Permissions section, select the following permissions:

  • ads_management: Manage ads and campaigns.
  • ads_read: Read ad and campaign data.
  • read_insights: Access insights data for ads, ad sets, and campaigns.
  • business_management: Manage business assets (often required to access ad accounts connected to a Meta Business Manager).

• Click Get Token to generate the access token.

• Copy the generated token securely. Use this Access Token to authenticate your API calls when using the “Service Account Key Authentication” method.

:::tip You can always view your existing access tokens, their permissions, and lifecycles using the Access Token Tool. :::

5. Request Increased Rate Limits

By default, API tokens generated from apps with "Standard Access" are heavily throttled by Facebook.

This can make them unsuitable for applications requiring frequent or large data syncs (like with Pipeloom).

To ensure reliable performance, you'll need to request "Advanced Access."

• Access App Review

  • From your app's dashboard, go to App Review > Permissions and Features.

• Identify Required Permissions

  • For each of the following permissions marked as "Standard Access", click the Request advanced access button:
    • ads_read
    • ads_management
  • Facebook may prompt you to fill out a form detailing how the permission is used.

• Complete Business Verification

  • Make sure your app is associated with a verified Business Manager account.
  • This is a prerequisite for obtaining Advanced Access.

• Submit the App Review Request

  • Once all information is provided, submit the request through the App Review interface.
  • Monitor the status in the dashboard as Facebook reviews your application.

• Meet Rate Limit Requirements

  • Once you’ve been granted advanced access, you must consistently make at least 1,500 Marketing API calls within any rolling 15-day window to maintain your status.
  • Facebook continuously evaluates your API activity based on the past 15 days, not just immediately after approval.
  • Falling below the 1,500 call threshold during any 15-day period may result in your advanced access being revoked.

Refer to Facebook's official documentation on Access Levels and Authorization for detailed instructions on requesting Advanced Access.

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.

2. (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. :::

3. (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.

4. (Optional) Multiselect the Campaign Statuses to include data from Campaigns for particular statuses.

5. (Optional) Multiselect the AdSet Statuses to include data from AdSets for particular statuses.

6. (Optional) Multiselect the Ad Statuses to include data from Ads for particular statuses.

   :::caution Status filtering and missing records When no statuses are selected for Campaign Statuses, AdSet Statuses, or Ad Statuses, the connector relies on the Facebook Marketing API's default behavior, which excludes records in ARCHIVED and DELETED states. This means archived campaigns, ad sets, and ads will not appear in your synced data.

   To ensure a complete dataset, explicitly select all statuses you want to include. This is especially important when using Full Refresh sync mode, because previously synced records that have since been archived will not be re-fetched unless you include the ARCHIVED status. :::

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

8. (Optional) If needed, you can change default action breakdowns for Built-in Ads Insights stream. Remove all if you need to make it empty list or change default values.

9. (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 Pipeloom stream name.

2. (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. The level you select determines the primary key used for deduplication in Incremental Append + Deduped sync mode. For details, see the primary key behavior by level section.

3. (Optional) For Fields, use the dropdown list to select the fields you want to pull from the Facebook Marketing API.

4. (Optional) For Breakdowns, use the dropdown list to select the breakdowns you want to configure.

:::info High-cardinality breakdowns Some breakdowns, such as product_id, can produce thousands of rows per day. 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 with a one-day window to validate the breakdown combination, and falls back to a logged warning if the single-day call also exceeds the limit. Real syncs use async jobs and are not affected by this limit. :::

5. (Optional) For Action Breakdowns, use the dropdown list to select the action breakdowns you want to configure.

6. Action Report Time is deprecated and hidden from the UI since v3.5.0. It defaults to mixed and cannot be changed through Pipeloom. If you set it programmatically (via API or Terraform), the available values are impression (attributed to view time), conversion (attributed to action time), or mixed (click-through to view time, view-through to action time).

7. (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. Cannot be used together with Time Increment Period.

8. (Optional) For Time Increment Period, select a calendar-aligned aggregation period instead of a fixed number of days. This produces consistently aligned time buckets regardless of the start date, making cross-client comparison easier. Available options:

   • daily — equivalent to Time Increment = 1 (1-day buckets).
   • weekly — aligns to Monday-through-Sunday calendar weeks.
   • monthly — aligns to calendar month boundaries (1st to last day of each month). This is natively supported by the Facebook API.

Cannot be used together with Time Increment. When switching between Time Increment and Time Increment Period (or vice versa), a full re-sync will be triggered.

9. (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, Pipeloom will replicate all data.

10. (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, Pipeloom will replicate the latest data.

11. (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 click-through attribution windows of up to 28 days, during which time a conversion can be attributed to an ad. View-through attribution is limited to 1 day. 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.

12. (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 applies only to this specific custom insight. For more details, see the global Include Incrementality setting described below.

13. (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.

14. (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 click-through attribution windows of up to 28 days, during which time a conversion can be attributed to an ad. View-through attribution is limited to 1 day. 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.

15. (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.

16. (Optional) Toggle Include Incrementality to add the incrementality attribution window to all built-in Ads Insights streams. When enabled, the connector appends "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 containing the incremental lift value attributed to the ad. This field is only populated for ad accounts that have active Conversion Lift studies configured in Facebook. For accounts without lift studies, the field is null. Disabled by default. For more details on the incrementality attribution window, refer to the Ads Action Stats API reference.

17. Click Set up source and wait for the tests to complete.

Supported sync modes

The Facebook Marketing source connector supports the following sync modes:

• Full Refresh - Overwrite
• Full Refresh - Append
• Incremental Sync - Append (except for the AdCreatives, AdAccount, CustomConversions, and CustomAudiences streams)
• Incremental Sync - Append + Deduped (except for the AdCreatives, AdAccount, CustomConversions, and CustomAudiences streams)

Supported Streams

Notes on Streams:

:::info Custom Audiences The rule field in the Custom Audiences stream may not be synced for all records due to limitations with the Facebook Marketing API. Syncing this field may also cause your sync to return the error message Please reduce the amount of data. See our Troubleshooting section for more information. :::

:::info Ad Creatives From Ads The ad_creatives_from_ads stream is an alternative to ad_creatives that fetches creative data through the Ads endpoint instead of the AdCreatives endpoint. Use this stream if ad_creatives fails with the error "Please reduce the amount of data you're asking for." The output schema matches ad_creatives with one addition - an updated_time field carrying the parent ad's timestamp - but this stream only returns creatives associated with ads; orphaned creatives not linked to any ad are excluded. For more details, see the Troubleshooting section.

When using incremental sync, the cursor is the parent ad's updated_time because AdCreative does not expose a timestamp of its own. Content changes always create a new creative and are picked up, but in-place renames, status or ad-label changes on a creative, and edits to the page post behind effective_object_story_id may not move the parent ad's timestamp and can be missed; use full refresh to capture those changes. The first incremental sync always reads the full ads history to seed the cursor (the start_date setting is not applied to this stream), so the time savings begin with the second sync. :::

Pipeloom also supports the following Prebuilt Facebook Ad Insights Reports:

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

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
• Comscore Market
• Gender & Age
• Platform & Device
• Region

For more information, see the Facebook Insights API documentation.

Custom Insights primary keys

The primary key for Custom Insights streams depends on the configured Level setting. This determines how the connector deduplicates records when using Incremental Append + Deduped sync mode.

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

Entity-Relationship Diagram (ERD)

Timezone handling for Insights streams

The Facebook Insights API interprets time_range date filters (since and until) in the ad account's timezone, not UTC. For ad accounts in timezones ahead of UTC (such as Asia/Tokyo at UTC+9 or Europe/Berlin at UTC+1), the connector automatically detects each account's timezone and adjusts the sync date range so that the current day's data is not missed. This per-account adjustment applies to all Ads Insights streams, including built-in and custom Insights streams. No configuration is required.

If you sync multiple ad accounts in different timezones within a single connection, each account's date range is computed independently based on its own timezone setting.

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.

IP allow list

If you use Pipeloom and your organization restricts access to specific IPs, add the Pipeloom IP addresses to your allow list.

Data type map

Troubleshooting

Handling "Please reduce the amount of data you're asking for, then retry your request"

This response indicates that the Facebook Graph API is refusing a synchronous request because it would return too much data in a single response. Where the error occurs determines what action, if any, you should take.

During a sync (on a stream other than ad_creatives): reduce the fields requested for that stream.

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.

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 that uses a high-cardinality breakdown (for example, product_id): no action is required. Since v5.2.7, the connector retries the breakdown validation call with a one-day time range and, if that also exceeds the limit, logs a warning and continues. The breakdown combination is still validated and real syncs are not affected, because they use async jobs that handle large result sets.

"Please reduce the amount of data" error on the Ad Creatives stream

If the ad_creatives stream fails with the error "Please reduce the amount of data you're asking for, then retry your request" and you do not want to disable any fields, you can switch to the ad_creatives_from_ads stream instead. This alternative stream fetches the same creative data but retrieves it through the Ads endpoint one creative at a time, which avoids the data-size limitation. The output schema is identical to ad_creatives.

Note that ad_creatives_from_ads is slower than ad_creatives because it makes individual API calls per creative. It also only returns creatives that are associated with ads — orphaned creatives that are not linked to any ad will not be included.

Missing records in Campaigns, Ad Sets, or Ads streams

If you notice that some campaigns, ad sets, or ads are missing from your synced data, the most common cause is the status filtering configuration.

The Facebook Marketing API excludes records in ARCHIVED and DELETED states by default. When the Campaign Statuses, AdSet Statuses, or Ad Statuses fields are left empty in the connector configuration, the connector does not override this default, and archived or deleted records are silently omitted.

This is particularly noticeable after a Full Refresh sync: records that were previously synced when they were active will not reappear if they have since been archived. You can verify this by looking up the missing record IDs directly in the Facebook API. Individual record lookups by ID return data regardless of status, but the listing endpoints the connector uses do not.

To resolve this:

1. Go to Settings > Source > Facebook Marketing.
2. For each of Campaign Statuses, AdSet Statuses, and Ad Statuses, select all statuses you want to include. At minimum, add ARCHIVED alongside the active statuses.
3. Trigger a Full Refresh sync to re-fetch the complete dataset.

Missing data for 7-day and 28-day view-through attribution windows

Starting January 12, 2026, Meta removed support for the 7-day view-through (7d_view) and 28-day view-through (28d_view) attribution windows in the Ads Insights API. In v4.1.3, these attribution windows were removed from request parameters for ads_insights and Ads Insights Reports streams. In v5.0.0, the 7d_view and 28d_view columns were also removed from stream schemas. Data previously returned for these windows is no longer available. For more information, see Meta's 2025 Out-Of-Cycle Changes.

What data is still available

• The 1d_view attribution window remains supported and continues returning data where applicable.
• Click-through attribution windows (1d_click, 7d_click, 28d_click) are not affected by this change.

Connection check fails with "Invalid access token" after re-authenticating

If your connection check fails with an "Invalid access token" or "Error validating access token" error shortly after you re-authenticated through the OAuth flow, your saved token may have been corrupted by Chrome's autofill feature.

What happened

Chrome can detect two adjacent form fields — the Ad Account ID (text) followed by the Access Token (password) — as a login form and silently inject saved browser credentials into them. When the connector configuration is saved with this autofilled value, an internal migration overwrites the valid OAuth token with the autofilled value, causing all subsequent syncs and connection checks to fail.

This issue was fixed in connector version 6.0.2 (airbytehq/airbyte#81331). If you are on an older version, upgrade to 6.0.2 or later to prevent recurrence.

How to fix it

1. Open your Facebook Marketing source configuration in Pipeloom.
2. Click Authenticate your account (or Re-authenticate) to go through the OAuth flow again. This generates a fresh, valid access token.
3. Click Save and then run Test Connection to confirm the new token works.

If the connection check still fails after re-authenticating, contact Pipeloom Support for further assistance.

Missing purchases or purchase value metrics

You may notice that Purchases or purchase value fields in the Ads Insights stream appear incomplete or under-reported for certain date ranges. This issue has been observed across multiple platforms, including direct Facebook API calls. It's not specific to Pipeloom, but linked to intermittent upstream API behavior.

What’s happening

API users have reported missing purchase metrics on Reddit and in the Facebook Developer and Community forums. In some cases, action values like offsite_conversion.fb_pixel_purchase appear correctly at the ad or ad set level, but disappear at the campaign or account level. API users documented similar API behavior in the Facebook Developer Community several years ago. It appears to have resurfaced more frequently as of 2025.

Why it happens

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

• Attribution window processing: Facebook re-attributes purchases up to 28 days after a click or 1 day after an impression, meaning recent data can fluctuate or appear missing until finalized.

• Complex breakdowns or field combinations: including multiple breakdowns like action_type, action_target_id, and action_destination can result in partial or truncated responses.

• Intermittent API-side behavior: Facebook's data availability and aggregation logic can vary between endpoints and attribution windows, leading to temporary inconsistencies.

• Throughput and rate limits: when you exceed API throughput or many queries run concurrently, Facebook may return partial datasets or suppress some metrics.

How to resolve the issue

1. Refresh recent data: update the Start Date on the source connector to just before the data discrepancy begins and then trigger a "Refresh and Retain" sync from the connection's settings tab. Many customers see missing metrics restored after doing this.

2. Simplify breakdowns: temporarily remove Action breakdowns like action_type, action_target_id, and action_destination from the Ads Insights stream configuration, then re-sync. Reintroduce them gradually.

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

4. Limit concurrency: if you have multiple Facebook Marketing connections using the same access token to authenticate, try staggering their sync schedules to reduce contention and avoid hitting Facebook API limits. This only works across multiple connections. No method exists to stagger syncs within a single connection that includes multiple ad accounts.

5. Verify with Facebook Ads Manager: compare values directly in Facebook Ads Manager at the ad or ad set level, where action values often appear correctly even if they’re missing in aggregated results.