Facebook Ads Loader
The Facebook Ads loader pulls campaign structure and performance data from your Meta Ads accounts into your data warehouse. It uses the Meta Marketing API and supports incremental sync for insights data based on date segments.
Prerequisites
- A Meta Business Manager account with access to the ad accounts you want to sync
- A Facebook user account with at least Analyst or Advertiser access to the ad accounts
- A connected Warehouse (target warehouse) with write permissions on the target schema
Authentication
The Facebook Ads loader uses OAuth 2.0 for authentication.
OAuth 2.0 Setup
- In SignalSmith, click Add Loader and select Facebook Ads
- Click Connect with Facebook
- You’ll be redirected to Facebook’s login page
- Log in and grant SignalSmith access to your ad accounts
- Select the ad accounts you want to connect
- You’ll be redirected back to SignalSmith with the connection established
SignalSmith requests the following permissions:
| Permission | Purpose |
|---|---|
ads_read | Read ad account data (campaigns, ad sets, ads) |
read_insights | Read performance metrics and reporting data |
business_management | Access ad accounts via Business Manager |
Token Longevity
Facebook access tokens are typically short-lived (1-2 hours). SignalSmith exchanges the short-lived token for a long-lived token (60 days) and automatically handles re-authentication before expiry. If the token cannot be refreshed (e.g., user changed password, app deauthorized), you’ll need to reconnect.
Ad Account Selection
After authentication, SignalSmith lists all ad accounts accessible to the authenticated user. Select one or more ad accounts to sync. Each ad account is identified by its Account ID (e.g., act_123456789).
Available Objects
| Object | API Name | Description | Default Sync Mode |
|---|---|---|---|
| Campaigns | campaigns | Campaign settings, objective, status, and budget | Incremental |
| Ad Sets | ad_sets | Ad set targeting, budget, schedule, and optimization settings | Incremental |
| Ads | ads | Individual ad creatives with their status and configuration | Incremental |
| Ad Creatives | ad_creatives | Creative assets — images, videos, headlines, and body text | Full Refresh |
| Campaign Insights | campaign_insights | Daily campaign performance metrics | Incremental |
| Ad Set Insights | ad_set_insights | Daily ad set performance metrics | Incremental |
| Ad Insights | ad_insights | Daily ad-level performance metrics | Incremental |
| Custom Audiences | custom_audiences | Custom audience definitions and sizes | Full Refresh |
| Ad Account | ad_account | Account-level settings, currency, and timezone | Full Refresh |
Insights (Performance Reports)
Insights objects contain daily aggregated performance metrics. Each row represents one day of data for the parent entity.
Key metrics available in insights:
| Metric | Description |
|---|---|
impressions | Number of times ads were displayed |
reach | Number of unique people who saw the ad |
clicks | Total clicks (all types) |
link_clicks | Clicks on outbound links |
spend | Total amount spent (in account currency) |
cpm | Cost per 1,000 impressions |
cpc | Cost per click |
ctr | Click-through rate |
conversions | Total conversions (based on configured conversion events) |
cost_per_conversion | Average cost per conversion |
frequency | Average number of times each person saw the ad |
video_views | Number of video views (3-second threshold) |
Breakdowns
Insights can be broken down by additional dimensions for more granular analysis:
| Breakdown | Description |
|---|---|
age | Age range of the audience |
gender | Gender of the audience |
country | Country of the viewer |
placement | Where the ad was shown (Feed, Stories, Reels) |
device_platform | Device type (mobile, desktop) |
publisher_platform | Platform (Facebook, Instagram, Audience Network) |
Enable breakdowns during object configuration. Each enabled breakdown adds rows to the insights table (one row per dimension value per day).
Configuration
| Setting | Description | Default |
|---|---|---|
| Ad Account ID | Facebook ad account ID(s) to sync | — (required) |
| Objects | List of objects and reports to sync | — (you choose during setup) |
| Insights Breakdowns | Additional dimensions for insights reports | None |
| Sync Mode | Full Refresh or Incremental (per object) | Incremental |
| Date Range | Lookback period for insights reports | Last 30 days |
| Attribution Window | Conversion attribution window (1-day, 7-day, 28-day) | 7-day click, 1-day view |
| Primary Key | Composite key for insights rows | id + date (+ breakdown fields) |
| Target Schema | Warehouse schema for Facebook Ads tables | — (required) |
| Table Prefix | Optional prefix for table names | fb_ |
| Schedule | Sync frequency | Daily |
Scheduling Notes
- Attribution window: Facebook attributes conversions based on the configured attribution window. Conversion data can change for up to 28 days after the impression/click. SignalSmith re-fetches data within the lookback window to capture updated attribution.
- Data freshness: Facebook insights data is typically finalized within 48 hours. Real-time metrics may show slight discrepancies with the Ads Manager UI.
- Rate limits: The Meta Marketing API enforces rate limits based on ad account tier and API usage. SignalSmith handles rate limiting with exponential backoff.
- Insights query limits: Facebook limits insights queries to 2 years of historical data per request. The initial backfill fetches up to 2 years of history.
- Multiple ad accounts: If syncing multiple ad accounts, each account is extracted independently. Tables include an
account_idcolumn to distinguish between accounts.
Schema Mapping
Facebook Ads field types are mapped to warehouse-compatible types:
| Facebook Type | Warehouse Type | Notes |
|---|---|---|
string | VARCHAR | |
numeric string | BIGINT | IDs are returned as strings but stored as BIGINT |
float | DOUBLE | Monetary values and rates |
integer | BIGINT | Count metrics |
datetime | TIMESTAMP | UTC normalized |
enum | VARCHAR | Status values, objectives |
list | JSON / VARCHAR | Targeting specs, action breakdowns |
object | JSON / VARCHAR | Nested structures |
Troubleshooting
| Issue | Solution |
|---|---|
| ”OAuthException: Error validating access token” | Token has expired or been revoked. Re-authenticate by clicking “Reconnect" |
| "#100 Invalid parameter” | An unsupported field or breakdown was requested. Contact SignalSmith support |
| ”#17 User request limit reached” | API rate limit exceeded. SignalSmith retries automatically. If persistent, reduce sync frequency |
| Insights data doesn’t match Ads Manager | Check the attribution window setting. Facebook Ads Manager may use a different default attribution window |
| Missing recent campaign data | Campaign structure changes may take a few hours to appear in the API |
| Spend values are zero | Verify the ad account has active campaigns and that the date range covers active periods |
| ”Ad account does not have permission” | Ensure the authenticated user has Analyst or Advertiser access to the ad account |
Next Steps
- Create a model to transform your raw Facebook Ads data
- Combine ad performance data with conversion data from your CRM
- Build retargeting audiences and sync them back to Facebook