> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abundly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Meta Ads

> Read campaign, ad set, and ad performance data from Facebook and Instagram ads

Connect your agent to Meta's Marketing API to analyse paid Facebook and Instagram advertising — ad accounts, campaigns, ad sets, ads, creatives, and insights. The agent can call any Marketing API endpoint, so anything you can pull from Ads Manager, the agent can pull too.

## How to enable

Go to **Settings → Capabilities** and enable **Meta Ads**, then link a workspace secret containing your Meta **App ID**, **App Secret**, and **system user access token**. The same secret can be reused across agents and teams. Abundly refreshes 60-day tokens automatically and saves the new token back to your workspace secret so it survives platform restarts.

## Example use cases

* **Daily performance summary** — "Every weekday at 8am, post yesterday's spend, impressions, clicks, and CTR for each active campaign to the #marketing Slack channel"
* **Anomaly watch** — "If any active ad set's CPA jumps more than 50% week-over-week, email me the breakdown by ad and creative"
* **Weekly review** — "Every Monday, generate a PDF report of last week's performance broken down by campaign objective and country"
* **Creative comparison** — "Compare the top 5 ads by ROAS across all active campaigns this month and summarise the patterns"
* **Account hygiene** — "List ad sets that have spent more than \$500 with fewer than 100 link clicks and flag them for review"

## How to create a Meta connection

The Marketing API authenticates with a **system user access token**. Store it together with your Meta app's **App ID** and **App Secret** so Abundly can refresh the token before it expires (Meta's recommended 60-day system user tokens).

<Steps>
  <Step title="Open Meta Business Settings">
    Go to [business.facebook.com/settings](https://business.facebook.com/settings) and select the Business that owns the ad accounts you want the agent to access.
  </Step>

  <Step title="Create a system user">
    Under **Users → System Users**, click **Add**. Give it a name (e.g. "Abundly Agent") and choose the **Employee** role. Confirm to create it.
  </Step>

  <Step title="Assign ad accounts">
    With the new system user selected, click **Assign Assets** and pick the ad accounts the agent should access. Grant **View performance** for read-only access, or **Manage campaigns** if the agent should also create or edit campaigns. Save.
  </Step>

  <Step title="Create or locate your Meta app">
    The token must be tied to a Meta app. If your Business doesn't already have one, create a free app at [developers.facebook.com/apps](https://developers.facebook.com/apps) (type **Business**) and associate it with your Business.

    From the app's **Settings → Basic**, copy the **App ID** and **App Secret**. No public review is required for first-party usage — the system user token only works against ad accounts you've explicitly assigned.
  </Step>

  <Step title="Generate the system user token">
    Back in Business Settings, with the system user selected, click **Generate New Token**. Pick the app from step 4, then choose the scopes:

    * **`ads_read`** — required for reading campaigns, ad sets, ads, and insights
    * **`ads_management`** — only needed if the agent should create or modify campaigns
    * **`business_management`** — only needed if the agent should manage Business assets

    Meta may require a 60-day expiring token — that is fine; Abundly refreshes it automatically. Copy the token immediately — Meta will not show it again.
  </Step>

  <Step title="Configure in Abundly">
    Go to **Settings → Capabilities**, enable **Meta Ads**, and create a workspace secret of type **Meta Ads** with three fields:

    * **App ID** — from your Meta app
    * **App Secret** — from your Meta app
    * **System user access token** — from step 5

    Select that secret on the capability card and save. Abundly refreshes the token before it expires and updates the **System user access token** field in your secret automatically — you only paste a new token manually if refresh fails (e.g. the token was fully expired before the next refresh).
  </Step>
</Steps>

<Note>
  You need to be an admin of the Business in Meta Business Settings to create system users and generate tokens. If a token is fully expired and refresh fails, generate a new system user token in Meta and update the **System user access token** field in your workspace secret. See [Meta's system user documentation](https://developers.facebook.com/docs/marketing-api/system-users) for more details.
</Note>

## API version

The agent uses the current default Marketing API version automatically. If you need to test against a different version (e.g. when Meta releases a new one), just tell the agent — it can target any version your Meta app supports.

## What this covers

This integration is scoped to **paid advertising** on Facebook and Instagram via the Marketing API. It does not include organic page posts, Instagram content, Messenger conversations, or WhatsApp messaging — those use different parts of Meta's Graph API and aren't enabled by this capability.