Skip to main content

Facebook Marketing

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

Prerequisites​

Setup guide​

Set up Facebook Marketing​

For Calabi Connect:​

  1. Log into your Calabi Connect 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 Calabi Connect will authenticate the account you are currently logged in to.

For Calabi Connect:​

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

Calabi Connect​

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.

📚 Further Reading: For an overview of the Marketing API, see: 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 Calabi Connect).

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.

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

Facebook Marketing Source Settings​

To configure Custom Insights:

  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​

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:

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.

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 is identical to ad_creatives, 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.

Calabi Connect 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.

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.

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

Data type map​

Integration TypeCalabi Connect Type
stringstring
numbernumber
arrayarray
objectobject

Troubleshooting​

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

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.

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

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 Calabi Connect, 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.