Connect Meta Ads
Two ways to authenticate
The deployment's Meta auth config decides which one you see (Composio setup):
| Mode | When | What you do |
|---|---|---|
OAuth (own Meta app with ads_read advanced access) | self-serve tenants | click Connect, sign in with Facebook, allow access |
| System-user token (API-key mode) | your own business, works without Meta app review | create a system user in Business Manager, assign the ad accounts (and the pixel, for conversion uploads), generate a token with ads_read (+ ads_management only if you upload conversions through Composio) and paste it |
System-user tokens do not expire unless you choose an expiry. Personal OAuth tokens expire after about 60 days; 3x shows Reconnect when that happens.
Connect
- Dashboard → Settings → Integrations → Meta Ads → Connect.
- Authenticate (OAuth or token).
- Select the ad accounts (
act_…) of this project. Currency and time zone come from the account. - A 90-day backfill starts in 30-day chunks.
What is imported
| Data | Notes |
|---|---|
| Campaigns, ad sets, ads | names, status and the ad's URL parameters (url_tags) – used for URL-tag matching |
| Daily insights per ad | spend, impressions, clicks (link clicks), leads/purchases and their value |
Meta reports conversions with an attribution window; 3x requests and stores
7d_click + 1d_view so platform numbers are stable and comparable over time. These platform
conversions are shown next to 3x's own leads and conversions – never added to them.
Numbers arrive as strings from the API and are normalized; amounts are in the account currency and converted to the project currency with daily ECB rates.
Recommended URL settings
Put the UTM template into every ad's Tracking → URL parameters
(it uses Meta's dynamic {{campaign.id}}, {{adset.id}}, {{ad.id}} macros). Meta appends
fbclid itself; 3x keeps it complete for conversion uploads.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Error code 17 / 80000 in the sync log | Meta rate limit for the ad account | nothing – the run is retried automatically after the advertised wait |
| Ads without URL parameters stay unmatched | no utm_* on the ad | add the template or create a mapping rule |
| Spend differs for "today" | Meta finalizes the day later | compare closed days |
(#200) Permissions error | token lacks access to the ad account | assign the account to the system user / reconnect |