Facebook (Meta) Ads connector installation guide

This guide explains how to connect your Meta Ads account to Windsor.ai, including prerequisites, required permissions, authorization behavior, setup steps, supported data levels, and troubleshooting tips.

Before connecting Facebook Ads to Windsor.ai, make sure you have:

• A Meta (Facebook) Business Manager account (Meta Business Suite)
• At least one active ad account inside Meta Business Manager
• A Windsor.ai account (https://onboard.windsor.ai/)

Meta access control is based on two layers:

1. User roles (what a human user can do in Ads Manager)
2. API permissions (what an application can read via the Meta API)

Let’s define which roles allow viewing Meta ads and accessing performance reports via Windsor.ai. 

To pull Facebook Ads performance data via Windsor.ai, your Facebook ad account must have at least one of the following roles: 

• Ad Account Analyst
• Employee access with “View performance” enabled

Please note that this is the minimum role type that you need to get the data from the Facebook Ads API.

During Facebook authorization, Meta will request the following API permissions:

These permissions are used in the read-only mode.

❗ Note: Authorization is handled through secure OAuth, meaning your Meta login credentials are never shared with or stored by Windsor.ai. Access can be revoked at any time directly from your Meta account settings.

1. Log in to your Windsor.ai account.

2. Navigate to the Data Sources search in the left-hand bar.

3. Find Facebook Ads (https://onboard.windsor.ai/app/facebook) in the list.

4. Click the button “Grant Facebook Ads Access.” You will be redirected to Meta’s authorization screen. Log in using the Facebook account that has access to your ad account(s). Meta will display the permissions requested.

5. Click the “Edit access.”

Please make sure all the necessary permissions are granted.

6. After verifying all the requested access, click “Continue.”

7. After successfully connecting, all the available Meta Ads accounts will appear in your windsor.ai dashboard. You can choose one or more (even all) ad accounts to pull data from.

❗ Important: During authorization, you will see Windsor.ai requesting permissions such as “manage your business” and “manage ads for ad accounts you have access to.” Although Meta uses the word “manage,” Windsor.ai does not create ads, edit or modify campaigns, and does not publish or manage Page content. These permission labels are defined by Meta and apply to all third-party analytics and reporting tools that read advertising data.

The Windsor.ai Facebook Ads connector pulls paid advertising data from Facebook and Instagram Ads using the Meta Marketing API. 

The primary data levels available are:

• Campaign
• Ad set
• Ad
• Ad account
• Creative
• Audience and catalog items

📋 Windsor.ai supports a comprehensive Facebook Ads schema with 560+ metrics and 150+ dimensions. The full list of supported fields can be found in the Facebook Ads Field Reference.

If you don’t see any ad accounts, newly added ad accounts do not appear, or data stops syncing unexpectedly, this is usually caused by a change in permissions after the initial connection.

Meta evaluates user roles, Business Manager access, and Page permissions at the time of authorization. If ad account access is granted or modified later, you will not be able to get the data from the Facebook Ads connector.

To resolve this:

• Disconnect the Facebook Ads connector in Windsor.ai
• Reconnect and reauthorize the connector
• Ensure all requested permissions are approved
• Confirm the user has access to the required ad accounts in Meta Business Manager

This process refreshes permissions and ensures Windsor.ai can discover all available ad accounts and assets.

If you encounter issues while connecting or using the Facebook Ads connector in Windsor.ai:

• Resetting your Windsor.ai business integrations on Facebook helps resolve various permissions and authentication issues. See the reset instructions here.
• Frequently asked support questions and troubleshooting guides can be found here.
• Check Meta Ads Manager and Meta Business Manager for account status, billing, or permission changes.
• Contact Windsor.ai Support for connector setup, authorization, or data synchronization issues.
• Contact Meta Support for Facebook account, Ad Account, Page, or API-related issues.

Last updated: 2025-12-16