<pectus.ai/>
./pectus.ai — builder framework · self-hosted · MIT

For end users

Meta Marketing API integration

Connects Pectus to a Meta Business Manager so it can pull Facebook + Instagram ad performance — daily spend, impressions, clicks, conversions per campaign.

Approval delay: none for Development-mode access against ad accounts the Business Manager owns. Standard access (which lets the app read accounts outside the BM) requires app review and takes 2–6 weeks. For most installs, Development access is sufficient.

Env vars set by this flow:

META_APP_ID=
META_APP_SECRET=
META_ACCESS_TOKEN=
META_AD_ACCOUNT_ID=

Prerequisite: the user installing Pectus must have admin access to their Meta Business Manager. Only an admin can mint a System User token.

1. Create a Meta Developer App

  1. Go to https://developers.facebook.com/apps
  2. Click Create app
  3. Use case: Other → Business
  4. App name: e.g. Pectus Marketing API
  5. Business Manager: pick the user’s BM
  6. Click Create app

You’ll land on the app dashboard.

2. Add the Marketing API product

  1. From the app dashboard, scroll to Add products to your app (or click Products in the left nav)
  2. Find Marketing API in the list
  3. Click Set up

Marketing API now appears in the left sidebar.

3. Grab the App ID + App Secret

  1. Left sidebar → App settings → Basic
  2. App ID is at the top — copy it → META_APP_ID
  3. App secret is below — click Show, copy it → META_APP_SECRET

4. Create a System User in Business Manager

System User tokens don’t expire (unlike User tokens, which expire in 60 days). This is the right pattern for server-side integrations.

  1. Go to https://business.facebook.com
  2. Click the gear icon (top right) — Business settings
  3. Left nav → Users → System users
  4. Click Add (top right)
  5. Name: Pectus API Reader (or similar)
  6. Role: Employee (NOT Admin — we only need read access)
  7. Click Create system user

The “no permissions available” error in the next step is usually because the app isn’t linked to the BM. Do this preemptively.

  1. Business Settings → Accounts → Apps
  2. If the app you created isn’t listed, click Add → Add an app and paste the App ID
  3. Save

6. Assign the Ad Account to the System User

  1. Business Settings → Users → System users → [the user you created]
  2. Click Add assets
  3. Choose Ad accounts
  4. Tick the ad account(s) Pectus should read
  5. Permission: tick View performance (read-only). Leave Manage campaigns OFF.
  6. Save

7. Assign the App to the System User

  1. Same System User → Add assets
  2. Choose Apps this time
  3. Tick the Pectus app you created
  4. Toggle Develop app on
  5. Save

8. Generate the access token

  1. Same System User → Generate new token
  2. App: pick the Pectus app
  3. Token expiration: Never
  4. Available scopes — tick:
    • ads_read
    • business_management
  5. Click Generate token

You’ll see the token once. Copy it → META_ACCESS_TOKEN.

If ads_read isn’t shown in the available scopes, the app isn’t linked to the System User properly. Go back to step 7.

9. Get the Ad Account ID

The Ad Account ID has the prefix act_ when used in API calls. You can find it in the Ads Manager URL:

https://adsmanager.facebook.com/adsmanager/manage/...?act=123456789012345

The number after act= is the Ad Account ID. Save it as META_AD_ACCOUNT_ID=act_123456789012345 (with the act_ prefix).

10. Verify

Once your credentials are saved, open the per-app page in the CMS at /apps/meta and click Test connection. Pectus runs a small probe call against the API and surfaces the response inline.

Common errors

(#100) Tried accessing nonexisting field "..." — the API version specified in the SDK is no longer supported. Meta deprecates major versions on a rolling basis. Update the SDK and the version pinned in apps/meta/client.ts.

(#10) Application does not have permission for this action — the System User doesn’t have the app assigned with develop permission, OR the app doesn’t have the Marketing API product enabled. Check steps 2 and 7.

Invalid OAuth access token — token was revoked. System User tokens can be revoked if the user is removed from the BM, the app is unlinked, or someone explicitly invalidates it. Re-do step 8.

Empty response with no error — usually means the System User doesn’t have access to the ad account you’re querying. Re-check step 6 and the act_ prefix on the ad account ID.

Why Development-mode access is fine for most users

Meta apps in Development mode can read any ad account that the Business Manager owns or has been granted access to. The “Standard Access” review tier is only needed if the app needs to read ad accounts that aren’t in the user’s BM (e.g. a SaaS product that connects multiple customers’ BMs through one Meta app). Pectus is self-hosted, so each install only needs to read its own BM.