meta-ads

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: meta-ads
description: Pull, analyze, manage, and CREATE Meta ads (Facebook, Instagram, Messenger, Threads, Click-to-WhatsApp) via the Marketing API. Use when the user mentions Meta/FB/IG ads, Ads Manager, ROAS, CPA, CPM, CTR, ad spend, campaign or ad set performance, creative fatigue, frequency, CTWA, audience/placement breakdowns, A/B ad tests, or wants to pause an ad, change a budget, duplicate a winner, or launch a new campaign from scratch. Trigger on Hebrew terms like פרסום בפייסבוק/באינסטגרם, פרסומות מטא, ביצועי קמפיין, פרסומות, צור קמפיין, השק קמפיין, A/B טסט. Trigger on questions like how are my ads doing, which creative is winning, is my ad fatigued, what's my CPA, drop a 30-day report, launch an A/B test for my course, build a campaign with these 3 angles. Trigger even if auth isn't set up — the skill walks through one-time setup. Do NOT use for organic Instagram analytics, Reels view counts on non-promoted posts, or organic Threads engagement; those need the Instagram Graph API.
---

# 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 la