Connect Meta Ads

1What you'll need

• Admin access to the Meta Business Manager that owns the ad account. Not employee access — only an admin can create a system user and generate its token.
• An app registered in that same Business Manager. Check Business Settings → Accounts → Apps. If the list is empty you must add one first — there is no “default business app” to fall back on, and without an app the token screen has no permissions to offer. Create one at developers.facebook.com (type Business), then add it here by its App ID.
• Your Ad Account ID — the numeric id (e.g. 1234567890) shown in the Ads Manager URL as act=<id>, or under Business Settings → Accounts → Ad accounts.

2Create the system user

picoask reads via a Business Manager system user — a non-human identity whose token keeps working when an employee leaves or changes their password.

• In Business Settings → Users → System users, choose Add and give it a name (e.g. picoask).
• Employee is the right role for the system user itself. (The person doing this setup still has to be a Business Manager admin.)

3Assign the app and the ad account

This is the step most setups miss, and it is why the token screen can come back empty. A system user’s token derives its permissions from an app, so without a role on one there is nothing to grant.

With your system user selected, choose Add assets and assign both:

• Apps → tick your app → enable Develop app. This is what makes ads_read appear on the next screen.
• Ad accounts → tick the account picoask should read → enable View performance. This decides which accounts the token can reach.

Both matter, and they fail differently. Skip the app and you get “No permissions available — assign an app role to the system user” and cannot continue. Skip the ad account and the token generates perfectly, then returns no data — which looks like a broken connector rather than a missing grant.

4Generate the token

• On the system user, choose Generate new token and select your app.
• For expiry, choose Never. Meta also offers a 60-day token and marks it as the more secure option, but picoask cannot refresh a Meta token — a 60-day token will stop the connector in two months with no warning.
• Tick ads_read only. That is everything picoask needs: it reads reporting data and never creates, edits, pauses or manages campaigns, ad sets, ads or budgets. Do not grant ads_management (write access), business_management, or any catalog / commerce scope — picoask does not use them, and a leaked token carrying them could alter live campaigns.
• Copy the token — Meta shows it only once. If you lose it, generate a new one.

5Connect in picoask

In your project's Integrations tab, choose Meta Ads → Connect and fill in exactly two things:

• Ad Account ID — the numeric id from step 1 (no act_ prefix).
• System-user access token — the ads_read token from step 4.

picoask validates the credentials against the Meta API before saving. Credentials are stored encrypted and used only by the sync worker.

6What happens next

• picoask backfills your campaign history, then keeps the data synced on a regular cadence with a lookback window so late-arriving conversions are corrected.
• Meta data lands in your picoask warehouse in a unified ad-reporting model, so questions like "which channel drove CAC up?" compare Meta, Google Ads, and GA4 side by side — CPC, CTR, ROAS, and CAC are pre-defined.

7Troubleshooting

• "Invalid OAuth access token" — the token was truncated when pasting, or has expired. Generate a new system-user token and reconnect.
• "(#200) permission denied" — the system user isn't assigned to this ad account, or the token is missing the ads_read scope. Fix the assignment in Business Settings and generate a fresh token.
• “No permissions available” on the token screen — the system user has no role on an app. Go back to step 3 and assign the app with Develop app. If Business Settings → Accounts → Apps is empty, create an app first.
• Token works but no data arrives — the ad account was never assigned to the system user. Add it under Add assets → Ad accounts with View performance; the existing token then starts working, with no need to regenerate.
• The connector stops after about two months — a 60-day token was chosen. Generate a new one with expiry set to Never and reconnect.
• Account not found — double-check the numeric id; use the ad account's id, not the Business Manager id.