Overview
The Ingest Facebook Ads connector reads from Meta's Marketing API (Graph API v25.0). Authentication uses a non-expiring System User access token issued from a Business Manager App — this is Meta's recommended pattern for server-to-server integrations because the token does not rotate the way user-OAuth tokens do.
Setup guide
Create the System User access token
This is a multi-step Meta workflow. Reserve 15-30 minutes for first-time setup.
- Create a Meta App — go to developers.facebook.com/apps, create a new "Business" type app, and add the Marketing API product.
- Create a System User — open Meta Business Manager, open Business Settings → Users → System Users, click Add, and choose role "Admin".
- Assign assets to the System User — give it access to the ad account(s) you want Ingest to read. Assign the role "Manage campaigns" (read access alone is not enough for the Insights endpoints).
- Generate the token — on the System User detail page, click Generate New Token, select the app from step 1, and check the scopes:
ads_read(mandatory — campaigns, adsets, ads, insights)business_management(recommended — Business Manager access)read_insights(mandatory for the insights endpoints)
- Copy the token immediately. Meta only shows it once.
Add it to Ingest
In the Ingest UI under Connectors → Facebook Ads, paste the token. Ingest stores it in AWS Secrets Manager under the key access_token. The runtime sends it as Authorization: Bearer <token> on every request.
Mind the limits
Meta does not publish a flat "X requests per second" limit. Instead, every API call is charged against a Business Use Case (BUC) budget that's specific to the ad account and the call type. The Standard Access tier for Ads Insights is 600 + 400 × N_active_ads calls per hour per account; non-insights calls have similar but distinct formulas.
The Ingest runtime dispatches at 2 req/sec by default, watches for 429 and BUC-throttle responses, and uses AIMD backoff to find the right pace per account. Errors 401 (bad/expired token) and 403 (asset-permission gap) are treated as fatal — fix the token or asset assignment before retrying.
The Insights endpoints currently use Meta's synchronous call mode. Queries that span >7 days with breakdowns can hit the row-count ceiling (error_code=100, subcode=1487534). The default generator parameters (date_preset=last_30d, time_increment=1, no breakdowns) stay well under the ceiling for typical accounts; talk to your Ingest contact if you need wider windows or breakdown dimensions.
Pick endpoints
Most customers want the campaigns / adsets / ads hierarchy plus the matching insights endpoints — the canonical "what's running and how is it performing" dataset. The full set:
- Identity / accounts:
me,adaccounts,businesses,ad_account - Ad hierarchy:
campaigns,adsets,ads - Creative assets:
adcreatives,adimages,advideos - Targeting:
custom_audiences - Performance:
account_insights,campaign_insights,adset_insights,ad_insights
Supported streams
6 endpoints are available out of the box. Each endpoint syncs into its own Iceberg table in Snowflake.
| Endpoint | Description | Reference |
|---|---|---|
| ad_account ad_account | – | |
| adaccounts adaccounts | – | |
| adimages adimages | – | |
| adsets adsets | – | |
| campaigns campaigns | – | |
| me me | – |
Authentication
- Auth type
- Bearer Token
- Sent as header
Authorization- Provider docs
- developers.facebook.com ↗
Performance & limits
- Rate limit
- Per Business-Use-Case (BUC) formulas. Standard Access for Ads Insights = 600 + 400 × N_active_ads calls/hour per ad account. Ingest dispatches at 2 req/sec by default and uses AIMD backoff on 429 / BUC-throttle responses.