Meta Ads Integration: Facebook and Instagram Campaigns

What Data Blueprint Syncs from Meta

Meta Ads is Blueprint's third supported platform, covering Facebook and Instagram campaigns through the unified Meta Graph API. At the campaign level, Blueprint pulls campaign names, statuses, objectives, and buying types. Below campaigns, Blueprint syncs ad sets with their targeting criteria, budgets, optimization goals, and scheduling parameters. At the ad level, Blueprint captures ad names, statuses, and creative content references. Daily spend records track cost, impressions, clicks, and conversions at the campaign and ad set level, feeding directly into Budget Pacing dashboards and the AI-powered anomaly detection engine.

Conversion actions are also synced from Meta, ensuring that attribution data flows into Blueprint's performance reports. This includes standard events, custom conversions, and any conversion goals configured in your Meta Events Manager. The conversion data aligns with campaign and ad set metrics so you can track ROAS and CPA across your Meta accounts alongside Google and Microsoft data in a unified view.

It is important to understand what Meta does not provide. Unlike Google and Microsoft, Meta Ads has no concept of keywords, search terms, or Quality Scores. These are fundamentally search advertising concepts that do not apply to Meta's social and display advertising model. There is also no change history API -- Meta does not expose a log of modifications made to campaigns, ad sets, or ads through their API. This means Blueprint's Quality Score tracking, n-gram analysis, Change Impact detector, and Impression Share Erosion detector are not available for Meta Ads accounts. Budget Pacing, AI anomaly detection, and conversion tracking work fully across all three platforms.

Account Discovery and the act_ Prefix

When you click Connect Meta Ads, Blueprint initiates the Facebook Login OAuth flow. You sign in with the Facebook account that has access to your ad accounts -- this can be a personal account or a Business Manager account -- and approve the requested permissions. After authorization, Blueprint calls the listAccessibleAdAccounts endpoint on the Graph API to discover every ad account your login can reach. If you manage multiple clients through Meta Business Manager, all of those accounts appear during discovery.

Meta has a unique identifier convention that requires careful handling: every ad account ID in the Graph API is prefixed with act_. An account with numeric ID 123456789 is referenced as act_123456789 in API calls. Blueprint uses a stripActPrefix function during ingestion to store clean numeric IDs in the database, and a withActPrefix function when making API calls back to Meta. This might seem like a small detail, but getting it wrong causes API calls to fail silently or return empty results. Blueprint handles this transparently -- you will only ever see clean account IDs in the Blueprint interface.

Select the accounts you want to track from the discovery list, and Blueprint immediately begins the initial data sync. Each Meta connection is workspace-scoped, so every team member sees the data without needing their own Facebook authorization. Only workspace Owners and Managers can add or remove Meta connections.

The Meta Token Lifecycle

Meta's authentication model is fundamentally different from Google and Microsoft, and understanding it is critical for maintaining uninterrupted data access. When you authorize Blueprint through Facebook Login, Meta issues a short-lived token that expires in approximately one hour. This token is immediately unusable for ongoing data syncs. Blueprint automatically exchanges this short-lived token for a long-lived token using Meta's token exchange endpoint, extending the validity to approximately 60 days.

Here is the critical difference: Meta does not support refresh tokens. With Google and Microsoft, Blueprint can silently refresh an expired access token using the refresh token that was issued during initial authorization, which means those connections persist indefinitely. With Meta, when the long-lived token approaches its 60-day expiration, there is no way to renew it programmatically. The token must be exchanged for a new long-lived token before it expires, or the user must go through the Facebook Login flow again.

Blueprint attempts to exchange the token before expiry when possible, but if the exchange window is missed, the token expires and syncing stops. To prevent this from catching you off guard, Blueprint tracks the expiration date for every Meta connection and surfaces an EXPIRING_SOON status when a token has 7 days or fewer remaining. You will see this warning in the Connections panel and in any relevant dashboard alerts. Click Reconnect to go through the Facebook Login flow again, and Blueprint exchanges the new short-lived token for a fresh long-lived token, resetting the 60-day clock. No data is lost during the reconnection -- Blueprint resumes syncing from where it left off.

Sync Schedules

Blueprint's Meta Ads sync follows a chained pattern similar to the other platforms, though the data hierarchy is different. Campaigns sync every 6 hours, and when the campaign sync completes, it chains into ad set syncing and daily spend record updates. Ad set syncs in turn chain into ad-level syncs, creating a cascade that keeps the entire campaign hierarchy consistent. Daily spend records sync every 6 hours using a rolling date window, ensuring that late-arriving data from Meta's reporting pipeline is captured on subsequent syncs.

Conversion actions sync every 6 hours on their own schedule, independent of the campaign chain. This ensures that attribution data stays current even if a campaign sync is delayed for any reason. The overall sync cadence means your Meta dashboards are refreshed four times per day, which provides sufficient freshness for daily monitoring and Budget Pacing calculations without hammering Meta's API rate limits.

Unlike Google and Microsoft, there are no keyword syncs, search term syncs, Quality Score snapshots, or change history syncs for Meta accounts. This means fewer background jobs per Meta connection, which translates to lower API quota consumption. Meta's rate limiting is score-based rather than quota-based -- each API call consumes points from a score that resets over a 1-hour window. Blueprint's workers are aware of this scoring system and throttle requests when the score approaches the limit, specifically watching for error codes 613 (rate limit) and 80004 (too many calls).

Meta-Specific Data Differences

Meta returns spend values as decimal dollar strings -- for example, "45.67" for a cost of $45.67. This is different from Google (micros, divide by 1,000,000) and Microsoft (dollars, multiply by 1,000,000 for normalization). Blueprint parses Meta's string values and converts them to the same normalized micros format used internally, ensuring cross-platform aggregations work correctly. Budgets in Meta are stored in cents for any write-back operations, which is another quirk that Blueprint handles transparently.

Pagination in the Meta Graph API uses cursor-based pagination rather than page tokens or offsets. Each response includes a paging.next URL with a cursor parameter that Blueprint follows until no more pages are returned. This is functionally equivalent to Google's page token approach but uses a different mechanism. Blueprint handles this transparently -- you do not need to worry about whether all records were captured.

Instagram campaigns are unified with Facebook through the Meta API. Instagram is treated as a placement within the ad set configuration, not as a separate platform. This means you do not need a separate connection for Instagram -- any ad sets configured to run on Instagram placements are automatically captured during the standard Meta sync. Campaign status mapping also requires normalization: Meta uses an ARCHIVED status that does not exist in Google or Microsoft. Blueprint maps ARCHIVED to REMOVED for consistency across the platform, so status filters work uniformly in cross-platform views.

What Meta Doesn't Support

Because Meta is a social and display advertising platform rather than a search advertising platform, several Blueprint features that depend on search-specific data are not available for Meta accounts. There is no Quality Score concept in Meta -- ad relevance is measured through different metrics (like Quality Ranking, Engagement Rate Ranking, and Conversion Rate Ranking in Ads Manager) that are not exposed through the Graph API in the same structured way. Blueprint's Quality Score tracking and trend analysis, which stores snapshots of QS components over time, only works with Google Ads and Microsoft Ads accounts.

Search terms and n-gram analysis are inherently inapplicable to Meta. Meta ads are not triggered by user search queries -- they are delivered based on targeting criteria like demographics, interests, and behaviors. There is no search term data to analyze, which means Blueprint's n-gram engine and search term management tools do not appear in Meta account views. Similarly, impression share data is a search advertising concept that Meta does not provide, so the Impression Share Erosion detector does not apply to Meta accounts.

Change history is the final gap. While Google and Microsoft expose detailed logs of every modification made to an account, Meta's Graph API does not provide an equivalent change history endpoint. This means Blueprint's Change Impact detector -- which compares 7-day pre/post performance around each change event -- cannot function for Meta accounts. If you need to track changes to Meta campaigns, you can use Blueprint's audit log, which records actions taken within Blueprint itself (such as budget target changes), though it cannot capture changes made directly in Meta Ads Manager.