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

# Meta Ads

> Facebook and Instagram ad accounts — the Ads agent's primary surface.

Meta Ads is the primary surface for the Ads agent. Connecting Meta unlocks campaign-level visibility, anomaly detection, creative refresh, and budget-pacing proposals across Facebook and Instagram.

## What it unlocks

* **Full Ads surface** for the connected account — spend, revenue, ROAS, campaigns, ad sets, ads, frequency, audience signals.
* **Ads-agent proposals** — pause underperforming ad sets, scale winners, refresh fatiguing creative, investigate spend anomalies.
* **The Ads-anomaly loop** — an unusual spend or ROAS swing kicks off a cross-agent investigation that may spawn Creative-refresh and Social-preview proposals.

## Scopes requested

Meta connects through standard Facebook OAuth. Mesh Pilot requests the scopes needed to read ad-account state and act on it:

* `ads_read` — read your campaigns, ad sets, ads, and insights.
* `ads_management` — write changes you approve (pause, scale, creative updates).
* `business_management` — manage assets within the Business Manager that owns the ad account.

You authorize per-brand. One brand → one Meta ad account in v1.

## Where data flows

* **Meta → cockpit:** ad-account state on an hourly poll (sometimes faster on anomaly triggers). Cached for fast surface rendering.
* **Cockpit → Meta:** only on your approval. Every approved Inbox action writes back through the Graph API and Meta is the canonical record of the change.

## Token lifetime

Meta uses short-lived (1 hour) tokens that get exchanged for long-lived (60 day) tokens at connect time. The cockpit refreshes them before expiry automatically. If a refresh fails, you'll see a "Needs reconnect" badge on the Meta card in Settings → Integrations.

<Card title="Connect Meta Ads" icon="arrow-right" href="https://meshpilot.app/dashboard/settings">
  Open Settings → Integrations.
</Card>
