meta-ads

What this skill does

# Meta Ads (Marketing API)

Pull ad performance data from Meta (Facebook, Instagram, Messenger, Click-to-WhatsApp, Threads), run analyses, and — with explicit confirmation — write changes back (pause, budget change, duplicate, full campaign creation with images and copy).

## When to consult this skill

Any question about Meta ad performance, creative health, audience/placement mix, or campaign management. If the user asks "how are my ads doing" without specifying a platform, ask whether they mean Meta or Google before defaulting.

## Three things to internalize before touching any script

**1. Where the scripts run matters.** The scripts call `graph.facebook.com` over the open internet. Some execution environments (including Claude's Linux sandbox in certain configurations) block this endpoint via proxy. If you hit a `ProxyError` / `Tunnel connection failed: 403` on the first call, run the scripts from the **user's host machine** — macOS, Windows, or Linux — using that machine's Python. Per-OS commands:
- **macOS:** `python3 scripts/auth_check.py`, deps via `python3 -m pip install --user requests`
- **Windows:** `python scripts/auth_check.py` (or `py scripts/auth_check.py` if `python` isn't on PATH), deps via `python -m pip install --user requests`
- **Linux:** `python3 scripts/auth_check.py`, deps via `python3 -m pip install --user requests` (add `--break-system-packages` on Debian/Ubuntu 22+)

The scripts themselves are pure Python with one dependency (`requests`) and no shell/OS assumptions, so they run identically everywhere once dependencies are installed.

**2. WhatsApp is not a separate ad surface.** Click-to-WhatsApp ads run on Facebook and Instagram placements. They show up in the Marketing API as regular ads with `destination_type=WHATSAPP` and conversion events under `actions` (look for `onsite_conversion.messaging_conversation_started_7d` and similar). Don't promise the user a "WhatsApp ads dashboard" — there isn't one.

**3. Read is safe, write is not.** Insights endpoints (GET) are idempotent and harmless. Pause / budget / duplicate (POST) actions touch real money. The write rules in `references/write-actions.md` are non-negotiable — read that file before any write call.

## The 37-month data wall

Meta's insights API only serves data from the last **37 months**. Any campaign older than that returns error `3018` and is effectively invisible. If the user asks "what was my best campaign ever" and their activity predates the window, the answer is "the API can't tell you — check Ads Manager's archived reports UI." Surface this before starting a query that's going to fail.

## Before anything else: check setup + discover accounts

The first three calls are always the same:

1. `python scripts/auth_check.py` — is the token alive, what identity does it resolve to, how many ad accounts does it see?
2. `python scripts/list_accounts.py --with-recent-spend` — which accounts are actually running ads right now? (Sorted by last-30-day spend, then lifetime spend.) This tells you which account to pin as `META_AD_ACCOUNT_ID`.
3. `python scripts/list_campaigns.py` — once you have the right account, what campaigns are on it?

If any of these fail, stop and walk the user through `references/setup.md`. Don't try to be clever and guess credentials.

### How to guide a user through setup (first-timers)

`references/setup.md` is written as a click-by-click walkthrough. When a user has no credentials yet:

1. **One step at a time.** Don't dump the whole document. Ask them which OS they're on, then give them the prerequisites block for that OS. Wait for them to report "done" before moving on.
2. **Confirm the path choice.** Walk through the Step 0 decision questions with them in chat. Don't assume — especially "do you boost from Instagram?" is easy to misjudge.
3. **Read back what they paste.** When they share a token, App ID, or ad account ID, echo it back (redact tokens to the first 8 chars) and confirm you have it right before you move on. This catches the #1 setup bug: pasting the System User's ID where the Ad Account ID should go.
4. **Verify before moving on.** After they fill in `.env`, run `auth_check.py` immediately. Don't let them run analysis commands until the verification returns `ok: true` — every "the report is empty" issue traces back to a half-broken `.env`.
5. **Match their OS in every command.** If they said "I'm on Windows," don't tell them to run `python3` — tell them `python` or `py`. If they said "Mac", use `python3`. The setup.md has per-OS blocks; copy the matching one into chat.

Required env vars (user provides these once during setup):
- `META_ACCESS_TOKEN` — either a long-lived user token (Path B, 60 days) or System User token (Path A, never expires). See the decision tree below.
- `META_AD_ACCOUNT_ID` — default ad account, format `act_1234567890` (scripts accept `--account-id` to override per call).
- `META_API_VERSION` — defaults to `v25.0` (current as of early 2026; v26.0 expected ~Sep 2026).

The user puts these in a `.env` file at the working directory or exports them in the shell. Scripts auto-load `.env` if present. See `assets/env.template`.

## Path A vs Path B: which token type?

This is the single most common failure mode. Get it right up front.

**Use Path A (System User token) when:**
- Ads run inside a Meta Business Manager you control.
- The ad accounts you want to analyze are owned by that BM.
- You want a token that never expires.

**Use Path B (long-lived user token) when:**
- You boost posts from the Instagram app (these often create a personal ad account outside any BM — invisible to System User tokens no matter what permissions you grant).
- Your ad account is attached to your personal Facebook profile, not a BM.
- You want to see every ad account your personal FB login can access (typically the broadest view).

**Can't tell which?** Start with Path B. It sees a strict superset of what Path A sees. Once you've identified the important accounts, you can optionally move them into a BM and switch to Path A for permanence.

Full setup steps for both paths: `references/setup.md`.

## Workflow: read operations

For any read request, follow this loop:

1. **Pick the right script.** Don't reinvent. The bundled scripts cover the common cases:
   - `auth_check.py` — verify token, list visible accounts briefly
   - `list_accounts.py` — discover all ad accounts, decode status, show lifetime + optional recent spend
   - `list_campaigns.py` — campaigns under an account, with status filters
   - `fetch_insights.py` — the workhorse. Date ranges, breakdowns (publisher_platform, age, gender, country, placement, device_platform), level (account/campaign/adset/ad), custom field lists. Read its `--help` before calling.
   - `creative_fatigue.py` — frequency + CTR decay analysis at the ad level
   - `anomaly_detect.py` — compares a date range against the prior equivalent range, flags significant changes
   - `exchange_token.py` — Path B only: swap short-lived user token for 60-day long-lived token

   Write scripts (pause/budget/duplicate/create — read `write-actions.md` first):
   - `pause_ad.py` — pause/resume a single campaign, ad set, or ad
   - `update_budget.py` — modify daily or lifetime budget with 2×-per-call safety cap
   - `duplicate_ad.py` — clone an ad, ad set, or entire campaign into a new copy
   - `create_campaign.py` — build a whole campaign (campaign + ad sets + creatives + ads) from a spec JSON. Handles image upload and interest resolution. See `references/campaign-creation.md`.
   - `rollback_creation.py` — pause or delete every object from a `create_campaign.py` run using its state file

2. **Run it, capture JSON output.** Every script outputs structured JSON to stdout. Don't try to parse human-readable text — there isn't any. Pipe to a file if the user wants to keep the raw data: `python scripts/fetch_insights.py ... > insights.json`.

3. **Analyze with the playbooks.** Once you have the data, consult `refere