Meta Ads: OAuth Setup and Metrics

Overview

clariBI connects to Meta Ads (formerly Facebook Ads) through OAuth, giving you direct access to your advertising data without manual exports. Once connected, you can build dashboards, generate reports, and use AI analytics to understand your ad performance.

This guide covers the OAuth setup process, the metrics available, and how to start analyzing your ad data.

Prerequisites

Before connecting, make sure you have:

• An active clariBI account on Starter or above (Trial plans support up to 3 data sources)
• Analyst role or above in your clariBI organization (Viewers and Members cannot create data sources)
• An active Meta Ads account with at least one campaign
• Admin or standard access to the advertising account you want to connect

Connecting Meta Ads

Step 1: Start the Connection

1. Go to Data Sources in the left sidebar.
2. Click Add Source.
3. Select Meta Ads as the data source type.

Step 2: Authorize with Meta

1. Click Connect with Meta.
2. A Meta login window opens. Sign in with your Facebook account.
3. Review the permissions:
4. Access your ad account data -- Read-only access to campaigns, ad sets, ads, and metrics
5. Access your Page and app information -- Used to identify your connected assets
6. Click Continue as [Your Name].
7. Select the ad accounts you want to share with clariBI. You can select all or choose specific ones.
8. Click Done, then OK to confirm.

Like Google Ads, clariBI requests read-only access. It cannot create, modify, or pause your campaigns.

Step 3: Select Your Ad Account

If your Meta Business account manages multiple ad accounts:

1. Select the ad account(s) you want to connect.
2. Click Continue.

Step 4: Configure Sync Settings

1. Sync frequency: Hourly, every 6 hours, daily, or weekly.
2. Historical data: Last 30 days, 90 days, 6 months, or 1 year.
3. Attribution window: Choose the attribution model Meta uses to count conversions -- 1-day click, 7-day click (default), 1-day view, or 7-day click + 1-day view.
4. Click Save and Sync.

Meta Ads Metrics Available

Metrics are available at the campaign, ad set, and ad level. Breakdowns by age, gender, placement, device, and country are supported.

Building Ad Performance Dashboards

Once your ad data is synced, you can build dashboards to track ad performance.

Ad Performance Dashboard

1. Create a new dashboard.
2. Add a KPI widget showing total ad spend.
3. Add a bar chart comparing conversions by campaign.
4. Add a line chart showing CPC trends over time.
5. Add a table widget with your top 10 campaigns ranked by ROAS (Return on Ad Spend).

Using AI to Analyze Ad Data

With your ad data connected, try these conversational AI queries:

• "Which Meta Ads campaign had the lowest cost per conversion last month?"
• "Compare our Meta Ads CPM across all placements this quarter"
• "Show me week-over-week trends in our ad spend"
• "What is our ROAS for the last 90 days?"

Each query costs 1 AI credit. See AI Credits: How They Work for details.

Managing Ad Connections

Re-Authenticating

OAuth tokens expire periodically. When a token expires, clariBI shows a warning on the data source and pauses syncing.

To re-authenticate:

1. Go to Data Sources.
2. Find the affected data source (it shows an "Authentication Required" badge).
3. Click Re-authenticate.
4. Complete the OAuth flow again.

Google Ads tokens typically expire after a few months. Meta Ads tokens expire after 60 days unless you have granted long-lived access.

Disconnecting an Ad Account

1. Go to Data Sources.
2. Click the three-dot menu next to the ad data source.
3. Select Disconnect.
4. Confirm the disconnection.

Disconnecting removes the sync but does not delete previously imported data. Dashboards and reports using the data continue to show historical information, but no new data is pulled.

Revoking Access from the Ad Platform

You can also revoke clariBI's access from within Google or Meta:

• Google: Go to myaccount.google.com/permissions and remove clariBI.
• Meta: Go to Facebook Settings > Business Integrations and remove clariBI.

After revoking, the data source in clariBI shows an authentication error and stops syncing.

Troubleshooting

"Insufficient Permissions" Error

You need admin or standard access to the ad account. If you have analyst or reporting access only, ask an account admin to upgrade your permissions or connect the account themselves.

No Data After Sync

• Check that the selected date range includes dates with active campaigns.
• Verify that the correct ad account was selected (not a test or inactive account).
• Wait for the initial sync to complete -- it may take several minutes for large accounts.

Metrics Discrepancy

Small differences between clariBI and the native ad platform are normal due to:

• Attribution windows -- Make sure the attribution window in clariBI matches the one in your ad platform.
• Time zones -- clariBI uses your organization's time zone. Check that it matches the ad account's time zone.
• Sync timing -- Data may be delayed by up to 3 hours depending on the ad platform's reporting API.

For significant discrepancies, check the sync log in Data Sources > [Source] > Sync History.

Related Articles

• Connecting Your First Data Source
• AI Credits: How They Work, What Counts, Checking Balance
• Dashboard Creation and Management
• Data Source Sync Failures: Timeouts, Auth Expiry, Quotas