Meta Ads
The Meta Ads connector imports campaign data from Facebook and Instagram advertising. It pulls spend, impressions, clicks, and conversion data at the campaign level with daily granularity.
Authentication
Meta Ads uses OAuth 2.0 via Facebook Login. Apex requests the ads_read scope for read-only access to your ad accounts.
Click Connect on the Sensors page
Find the Meta Ads card and click Connect. You'll be redirected to Facebook's authorization screen.
Sign in with Facebook
Use the Facebook account that has access to your ad accounts. This is typically the account that manages your Business Manager.
Grant ads_read permission
Authorize Apex to read your ad account data. This is read-only — Apex cannot create, modify, or pause your campaigns.
Select your ad account
Apex lists all active ad accounts (those with account_status: 1). Select the one you want to sync.
Info
After the initial short-lived token is received, Apex automatically exchanges it for a long-lived token (60-day expiry) for more reliable background syncs.
Data Synced
Each sync pulls campaign-level insights with daily time increment:
| Metric | Description |
|---|---|
| Spend | Daily ad spend per campaign |
| Impressions | Number of times your ads were displayed |
| Clicks | Total clicks (all types) |
| Conversions | Offsite conversions and lead actions from the actions array |
Data is broken down by campaign ID, campaign name, and date.
Configuration
| Parameter | Type | Description |
|---|---|---|
accountIdrequired | string | Meta ad account ID (e.g. act_123456789). Selected during setup. |
dateRange | object | Custom date range. Default: last 30 days. Meta limits lookback to ~37 months. |
Warning
Meta's Insights API limits historical data to approximately 37 months from today. If you request data beyond this window, Apex automatically clamps the start date to the earliest available period.
How Apex Uses This Data
- Channel attribution — Meta clicks are matched to visitors via
fbclid(Facebook Click ID), captured by the tracking snippet - Cross-platform comparison — See Meta Ads performance alongside Google Ads and LinkedIn Ads in a unified view
- Cost analysis — Calculate cost per lead and ROAS when combined with revenue data from Stripe or HubSpot
- Budget allocation — Feed the budget dashboard with spend data to optimize across channels
Troubleshooting
| Issue | Cause | Fix |
|---|---|---|
| No ad accounts listed | Facebook account lacks Business Manager access | Use an account with ad account admin or advertiser role |
| "Token expired" after 60 days | Long-lived token not refreshed | Reconnect from the Sensors page |
| Conversions show 0 | No conversion tracking configured in Meta | Set up Meta Pixel or Conversions API in your Meta Business Manager |
Next Steps
- Connect LinkedIn Ads for B2B campaign data alongside Meta
- Set up goals to track conversions from Meta traffic