Meta Ads

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 references/analysis-playbooks.md for the relevant pattern (fatigue, funnel, audience mix, anomalies). The playbook tells you what thresholds matter and what to recommend.

4. Present in the user's preferred language. If the user writes in Hebrew, respond in Hebrew. Keep metric names in English (CTR, CPA, ROAS) so they cross-reference cleanly with Ads Manager. If asked for a doc/dashboard, follow whatever design system skill they've set up.

Workflow: write operations (pause, budget, duplicate)

These are the dangerous ones. Follow this protocol every time, no shortcuts:

1. Surface the action and the impact in plain language before calling. Example: "Pause ad Campaign_v3 (ID 120214...). This ad spent ₪47 in the last 7 days with 0.8% CTR. Confirm?" 2. Wait for explicit `yes` / `confirm` / the user's language equivalent in chat. A previous "go ahead" in the conversation does not carry over. Each write needs its own confirmation. 3. One action at a time by default. If the user wants to bulk-pause 12 ads, present a numbered list and confirm the whole batch in one explicit message ("pause all 12") — but log each call separately. 4. Always do a dry-run first when the script supports it (--dry-run flag prints what would change without calling the API). 5. Never auto-shift budgets above +50% in one call. If the user wants a 3x increase, do it in steps with confirmation each time. Meta's learning phase resets on big budget changes anyway.

Full rules and edge cases in references/write-actions.md. Read it before calling any of: pause_ad.py, update_budget.py, duplicate_ad.py, create_campaign.py.

Workflow: creating a campaign from scratch

Use create_campaign.py to build a full campaign tree (campaign → ad sets → creatives → ads) in one shot from a spec JSON. Good for A/B flights where you want the exact same structure with disciplined naming and auditable creation history.

Before you touch the script:

1. Check if the user has a pixel. No pixel → force objective: OUTCOME_TRAFFIC and optimization_goal: LINK_CLICKS. Don't build a conversions campaign against an account that can't measure conversions; you'd be paying Meta to optimize toward an event it never sees. Surface this to the user and let them decide whether to wait for pixel install or launch blind on traffic. 2. Check the account balance. Status code 3 (UNSETTLED) on the ad account means objects can be created but nothing will deliver until balance clears. Don't block creation, but tell the user before they expect spend. 3. Discover the right page + Instagram identity. Users often own multiple pages. Query /me/accounts and /act_.../promote_pages and match against which page ran their historical winning ads (fetch a handful of recent ads, pull creative.effective_object_story_id to see the page ID in the prefix). 4. Default everything to PAUSED. The campaign, ad sets, and ads should all be PAUSED at creation. The user flips ACTIVE themselves in Ads Manager once they've eyeballed the creative. This is the last safety net. 5. Dry-run first, always. create_campaign.py --spec foo.json --dry-run prints the full plan with resolved interest IDs, currency-corrected budgets, and targeting summary. Walk the dry-run back to the user in plain language before asking for --confirm.

Per write-actions.md, a fresh explicit confirmation is required for --confirm even if the user approved the plan earlier in the same session. That confirmation must name the action (e.g. "confirm create", "בצע יצירה") — not a generic "ok".

Full spec format, field reference, currency handling, interest resolution, state file and rollback details: references/campaign-creation.md.

When NOT to use create_campaign.py

• Single ad addition to existing ad set — just call the ads endpoint directly or use the UI. Overkill to spec-and-run for one ad.
• Duplicating a winner — duplicate_ad.py is faster and preserves learning signals.
• Dynamic creative, catalog ads, collection ads — not supported in v1. The script only handles single-image link ads via link_data. Extend it or build a sibling script if needed.

Gotchas the scripts already handle for you

• Currency minor units. amount_spent, balance, spend_cap, daily_budget, lifetime_budget are returned by Meta as strings of minor units (agorot/cents/pence). list_accounts.py and list_campaigns.py convert these to major units in a _major or plain decimal field. Zero-decimal currencies (JPY, KRW, VND, ISK, TWD, etc.) are not divided.
• Account status codes. Scripts decode 1→ACTIVE, 2→DISABLED, 3→UNSETTLED, 7→PENDING_RISK_REVIEW, etc.
• Pagination. All scripts auto-paginate via meta_client.paginate().
• Rate limits. meta_client._request() backs off on subcodes 1487742 / 2446079 / 1487390 and retries.
• Async insights. fetch_insights.py auto-falls-back to async jobs when sync queries would time out (or you can force with --async).
• DELETED campaigns. Meta's campaigns endpoint returns error 1815001 when you request DELETED. The script's --status choices deliberately exclude DELETED. To see deleted campaigns, use Ads Manager UI.

What the bundled scripts don't handle

• Initial auth / token generation (manual, see references/setup.md).
• Pixel / Conversions API event ingestion (separate API).
• Dynamic creative / catalog / collection ad formats (only single-image link ads).
• Custom Audience creation (you can reference existing audiences, but not build new ones from here).
• Editing an already-live creative in place (you create new creatives via create_campaign.py; editing an existing one is a different API shape).

If the user needs something the scripts don't cover, extend the skill in a writeable copy and re-package — see references/campaign-creation.md for the pattern create_campaign.py establishes for write scripts. Don't fork separate one-off scripts in the user's working directory; consolidate into the skill so the next run benefits.

Reference files

Read these on demand, not all upfront.

• references/setup.md — One-time setup: decision tree Path A vs Path B, how to create the app, get tokens, find account IDs. Read this when the user has no credentials, or when auth_check.py fails.
• references/insights-fields.md — Field glossary, breakdown options, common metric definitions, gotchas (attribution windows, action_attribution, deduplication). Read this when constructing a custom insights query.
• references/analysis-playbooks.md — Patterns for creative fatigue, audience analysis, funnel diagnosis, anomaly response. Read this when the user asks for analysis, not just data.
• references/write-actions.md — Mandatory before any write call. Confirmation flow, safety thresholds, rollback patterns — including the campaign-creation section before using create_campaign.py.
• references/campaign-creation.md — Spec format, field reference, currency handling, interest resolution, state file and rollback details for create_campaign.py. Read this when the user asks to launch a campaign, A/B test, or new ad flight from scratch.
• references/troubleshooting.md — Common failure modes (sandbox proxy, IG boost invisible to SU tokens, missing requests module, encoding issues, 37-month cap, etc.). Read this when any script returns ok: false or something unexpected.

Scaling beyond personal use

This skill is built for one user, one set of credentials, a handful of ad accounts. Multi-tenant / client-agency use (one operator managing dozens of client BMs) is a different build:

• Per-client credential storage (not everyone's tokens in one .env).
• Each client issues their own System User token from their own BM.
• Audit log of every write action, who triggered it, against which account.

Don't try to retrofit the personal skill for multi-tenant use. Tell the user it's a different build.

Analysis Playbooks

Read this when the user wants analysis, not just data. Each playbook is a recipe: what to query, how to interpret it, what to recommend. Don't just dump numbers — synthesize.

Universal rule: always ground recommendations in the user's actual numbers

Generic advice is worthless. Don't say "consider refreshing your creative" — say "ad Summer_Launch_v3 has frequency 4.2 and CTR fell 38% in the second half of last 28d while CPM rose 22%. Pause it; the duplicate Summer_Launch_v4 is already taking over delivery." Pull names, IDs, and exact numbers from the script outputs.

Playbook 1: Time-range performance report

Trigger: "How are my ads doing this week?", "Give me a 30-day report", "What's my ROAS lately?"

Query:

python scripts/fetch_insights.py --level campaign --date-preset last_30d
python scripts/fetch_insights.py --level account --date-preset last_30d
python scripts/fetch_insights.py --level account --date-preset last_30d --time-increment 1

Interpret:

• Account-level totals → overall health
• Campaign-level rows → where the money went, sorted by spend
• Daily time series → trend (climbing, steady, or declining)

Recommend:

• If ROAS dropped vs. last period → run anomaly_detect.py to localize
• If one campaign eats 80% of budget but has worse ROAS than others → suggest reallocating
• If CPM climbed steadily → audience saturation or auction competition; suggest creative refresh + audience expansion

Output format: A clean prose summary with 3–5 numbered insights. Append a small table with per-campaign spend / ROAS / CPA for quick scanning. Match the user's working language, but keep metric names in English (CTR, CPA, ROAS, CPM) so they cross-reference cleanly with Ads Manager.

Playbook 2: Creative fatigue diagnosis

Trigger: "Is my ad fatigued?", "Why is CTR dropping?", "Should I refresh creative?"

Query:

python scripts/creative_fatigue.py --date-preset last_28d

Interpret the script's output:

• fatigued_ads[] is sorted by severity. Top of list = most urgent.
• A single flag (frequency only, or CTR decay only) is mild.
• Two flags (frequency + CTR decay) is real fatigue.
• Three flags (frequency + CTR decay + CPM rising) is severe — Meta is now actively penalizing delivery.

Recommend per ad:

• Mild fatigue, low spend: monitor; don't act
• Real fatigue, ad still profitable: duplicate the ad (duplicate_ad.py --type ad), then pause the original after the duplicate enters learning. This buys you a fresh learning phase without losing the working setup.
• Severe fatigue: pause immediately. Meta's penalty (rising CPM) means you're paying more for less. Replace with new creative, not a duplicate.
• Whole audience saturated (multiple ads in the same ad set all fatigued): the audience is the problem, not the creative. Expand targeting or move to a lookalike.

Playbook 3: Audience / placement breakdown

Trigger: "Where are my ads working?", "Which platform performs best?", "Should I split my budget by placement?"

Query:

# Platform breakdown
python scripts/fetch_insights.py --level campaign --date-preset last_30d \
  --breakdowns publisher_platform

# Placement detail (where on each platform)
python scripts/fetch_insights.py --level campaign --date-preset last_30d \
  --breakdowns publisher_platform platform_position

# Demographic
python scripts/fetch_insights.py --level campaign --date-preset last_30d \
  --breakdowns age gender

# Geographic
python scripts/fetch_insights.py --level campaign --date-preset last_30d \
  --breakdowns country

Interpret:

• Compute CPA or ROAS per breakdown row. Don't just look at CTR — high CTR can hide bad conversion rates downstream.
• Identify cells with sufficient volume to trust (≥30 conversions, or ≥$50 spend — fewer than that and you're staring at noise).
• Compare CPA across cells. A 2x difference in CPA between Instagram Reels and Facebook Feed is meaningful; a 20% difference probably isn't.

Recommend:

• If one placement has CPA <50% of the worst → consider isolating it in a new campaign with full budget
• If a demographic segment massively outperforms → tighten targeting (but warn: Meta's algorithm is usually better at finding people than we are at telling it where to look)
• For CTWA campaigns: Instagram Stories often dominates because it's a low-friction tap-to-message UI. If FB Feed is winning instead, that's unusual and worth investigating

Playbook 4: Conversion funnel analysis (with CTWA support)

Trigger: "Where are people dropping off?", "Why aren't my course ads converting?", "Are people clicking but not buying?"

Query for standard web conversion funnel (landing page → purchase / sign-up):

python scripts/fetch_insights.py --level campaign --date-preset last_30d \
  --fields spend impressions actions action_values cost_per_action_type

Then in the response, count action types:

• link_click — they clicked
• landing_page_view — Pixel confirms page loaded (drop here = slow page or misconfigured Pixel)
• view_content — they engaged with content
• add_to_cart / initiate_checkout — moved toward purchase (if e-commerce)
• purchase / complete_registration — converted

Compute drop-off ratios:

• LPV / link_clicks → site speed / pixel issues if low (<70%)
• view_content / LPV → page quality
• purchase / view_content → offer / pricing / trust

For CTWA funnel:

• link_click (or omit — Meta uses different signals) → onsite_conversion.messaging_conversation_started_7d → onsite_conversion.messaging_first_reply → eventual sale (tracked outside Meta)

Recommend:

• Drop-off between click and LPV → landing page issue (speed, Pixel firing, broken link)
• Drop-off between LPV and view_content → page doesn't deliver on the ad's promise
• Drop-off between view_content and purchase → offer/pricing problem, not an ad problem. The skill should say so directly: "Your ads are working. The conversion problem is on your landing page."

Playbook 5: Anomaly response

Trigger: "Something's off", "My CPA spiked", "Why did spend drop?", "Did something break overnight?"

Query:

python scripts/anomaly_detect.py --window-days 7

For shorter horizons:

python scripts/anomaly_detect.py --window-days 3 --pct-threshold 0.20

Interpret the output: The script returns a sorted list of campaigns where metrics moved significantly. Look at:

• status field: stopped_spending, started_spending, or active_change
• anomalies array: which metric moved and by how much

Common patterns and what they mean:

Recommend cautiously: anomalies have lots of false positives. Don't pause a campaign because one day looked weird — wait 2–3 days unless the issue is clearly catastrophic (like zero conversions for a converting campaign).

Playbook 6: Click-to-WhatsApp specific analysis

Trigger: "How are my CTWA ads doing?", "Cost per WhatsApp conversation?", "Should I run more CTWA?"

Why this needs its own playbook: CTWA campaigns optimize for messaging_conversations_started, not website conversions. The funnel is different (ad → tap → WhatsApp opens → first business message → reply → eventual sale). Analyzing them with web-conversion frameworks gives garbage answers.

Query:

python scripts/fetch_insights.py --level adset --date-preset last_30d \
  --fields spend impressions actions cost_per_action_type \
  --filtering '[{"field":"adset.optimization_goal","operator":"EQUAL","value":"CONVERSATIONS"}]'

Key metrics:

• Cost per conversation started (cost_per_action_type where action_type = onsite_conversion.messaging_conversation_started_7d)
• Reply rate: messaging_first_reply / messaging_conversation_started_7d — high reply rate means real intent; low means accidental taps or low-quality leads
• Cost per reply (cost per conversation × inverse reply rate) — the "real" cost of a usable lead

Recommend:

• Compare cost per conversation across creatives and audiences — wide spread (>2x) means easy optimization
• Low reply rate (<40%) suggests the ad creative oversells; refine the hook
• If reply rate is good but no sales materialize, the bottleneck is your WhatsApp follow-up sequence, not the ads

Cross-playbook: when to escalate

If the user wants ongoing monitoring (daily anomaly checks, weekly reports without asking), tell them this skill is on-demand only — scheduled runs belong in a cron job, a scheduled-tasks integration, or whatever automation layer the user already has. Don't try to fake persistence inside the skill.

If a third party (an agency client, a different team's account) wants this type of analysis, tell the user this skill assumes single-tenant credentials and the multi-tenant version is a different build. Don't run other people's analyses with personal credentials — each owner should set up their own app and token.

Creating campaigns from scratch

scripts/create_campaign.py builds an entire campaign tree (campaign → ad sets → creatives → ads) in one call from a spec JSON. This is a write operation — read write-actions.md first; the "Campaign creation" section at the bottom of that file is mandatory before you call --confirm for the first time in a session.

The workflow

1. Write a spec JSON that describes the campaign you want. 2. Run --dry-run. This reads the spec, queries Meta for account currency, resolves interest names to IDs, and prints the plan — no writes. 3. Walk the plan back to the user. They name the change to confirm. 4. Run --confirm. The script creates everything PAUSED by default and writes a state JSON with every ID. 5. If the user wants to activate: they toggle ACTIVE in Ads Manager (or via the API). Never flip ACTIVE programmatically as part of creation — that removes the final checkpoint.

Spec format (minimum viable)

{
  "campaign_name": "My Campaign - Q2 Flight",
  "objective": "OUTCOME_TRAFFIC",
  "status": "PAUSED",
  "special_ad_categories": [],
  "identity": {
    "page_id": "1234567890",
    "instagram_user_id": "17841400000000000"
  },
  "landing_url": "https://example.com",
  "ad_sets": [
    {
      "name": "Angle A — Broad",
      "daily_budget": 50.00,
      "optimization_goal": "LINK_CLICKS",
      "billing_event": "LINK_CLICKS",
      "targeting": {
        "countries": ["IL"],
        "age_min": 25,
        "age_max": 45,
        "interests": ["Artificial intelligence", "Productivity"],
        "publisher_platforms": ["instagram"],
        "instagram_positions": ["stream", "story", "reels"]
      },
      "image_path": "./creative/angle_a.png",
      "ads": [
        {
          "name": "A1_Direct",
          "message": "Primary body copy — can be multi-line.",
          "headline": "Short punchy headline",
          "description": "Optional secondary line",
          "cta": "LEARN_MORE"
        }
      ]
    }
  ]
}

Field reference

Top level

Ad set level

Ad level

Each ad inside an ad set uses the ad set's image.

Currency handling

The script queries /act_.../?fields=currency once at the start and converts daily_budget / lifetime_budget / bid_amount from major units to whatever minor unit the account uses:

• ILS / USD / EUR / GBP etc. → × 100 (agorot, cents, pence)
• JPY / KRW / VND / ISK / TWD / XAF / XOF / CLP → × 1 (no minor unit)

Write budgets in major units only. Never try to pre-convert.

Interest resolution

targeting.interests names are resolved via Meta's /search?type=adinterest endpoint. The script takes the top-ranked hit per name. This is convenient for readable specs but has two caveats:

1. The search ranking can change. A spec that resolved to "Productivity" today might resolve to "Productivity (software category)" tomorrow. 2. Search can return no match. Those names are dropped with a [warn] log.

For specs you'll re-run months later and want identical targeting, do one dry-run, copy the resolved_interests IDs into interest_ids, and delete interests. Now the targeting is frozen.

State file and rollback

Every --confirm run writes <spec>_state_<timestamp>.json with every object ID:

{
  "ok": true,
  "campaign_id": "120...",
  "ad_sets": [
    {"adset_id": "120...", "image_hash": "...", "ads": [{"ad_id": "120...", "creative_id": "120..."}]}
  ],
  "objects": [{"type": "campaign", "id": "120...", "name": "..."}, ...]
}

scripts/rollback_creation.py --state <file> --pause pauses everything. --delete permanently deletes in reverse order (ads → creatives are orphaned → adsets → campaign). Prefer --pause unless you really want the objects gone from Ads Manager history.

Common errors and how to handle them

`error_subcode 1885036` — Ad account is unsettled. The campaign objects get created fine but nothing will deliver until the account balance is paid. Don't block on this at creation time; surface it to the user and continue.

`The ad creative spec is invalid`. Usually missing page_id or a malformed call_to_action value. Double-check the cta is in VALID_CTAS and the landing URL is fully qualified (https://...).

`Invalid parameter` on `flexible_spec`. Means an interest ID is stale. Re-run the dry-run so search re-resolves names, or remove the offending interest.

`special_ad_categories` mismatch. If your ad is in a regulated vertical and you forgot to mark it, Meta rejects the whole ad set. Reviewable in the ad set's delivery_info in Ads Manager.

Account not admin of page. The ad account owner must have advertiser-or-higher role on the Facebook Page. Fix in Business Settings → Pages → assign.

Instagram identity missing. If instagram_user_id is omitted, ads still run on Instagram placements but show "Sponsored by <Page Name>" instead of your IG handle. Almost always you want to set it.

When to NOT use this script

• You only want to duplicate an existing ad. Use scripts/duplicate_ad.py — it copies targeting, creative, and settings in one shot and is one API call instead of six.
• You're iterating on creative for an existing ad set. Creating a new campaign per iteration pollutes Ads Manager. Add new ads to the existing ad set via a partial spec or do it in the UI.
• You want dynamic creative / catalog ads / collection ads. Those have different creative shapes (asset_feed_spec, product_set_id, template_data). This script only handles single-image link ads. Extend it or build a sibling script.

Insights Fields, Breakdowns & Gotchas

Read this when constructing a custom insights query (anything beyond the defaults in fetch_insights.py). It's a reference, not a tutorial — skim for what you need.

Standard fields you'll use most

The actions array — the most important and most confusing field

actions is a list like:

[
  {"action_type": "link_click", "value": "234"},
  {"action_type": "post_engagement", "value": "1240"},
  {"action_type": "onsite_conversion.messaging_conversation_started_7d", "value": "12"},
  {"action_type": "purchase", "value": "8"},
  {"action_type": "omni_purchase", "value": "8"}
]

Common action_type values you'll grep for:

• link_click — outbound link clicks (the meaningful CTR numerator for traffic objectives)
• post_engagement — likes/comments/shares/clicks combined
• landing_page_view — pixel fired LPV (more reliable signal than link_click, requires Pixel)
• purchase — conversion via Pixel/CAPI
• omni_purchase — purchase across all surfaces (web + app + offline) — usually what you want
• lead — lead form submission
• complete_registration — sign-up event
• onsite_conversion.messaging_conversation_started_7d — this is your CTWA conversion
• onsite_conversion.messaging_first_reply — first business reply in WhatsApp
• view_content, add_to_cart, initiate_checkout — funnel steps if Pixel is configured

For Click-to-WhatsApp specifically, look for action types prefixed with onsite_conversion.messaging_*. If they're missing, the campaign isn't a CTWA campaign or the pixel mapping isn't set up correctly.

purchase_roas shape

[
  {"action_type": "omni_purchase", "value": "3.42"},
  {"action_type": "purchase", "value": "3.18"}
]

Use omni_purchase as the headline ROAS unless you have a reason to scope to web-only.

Breakdowns — what you can split data by

Pass to --breakdowns (one or more, but not all combinations are legal):

Action breakdowns are different — they split the actions array, not the rows:

Date presets

Use these via --date-preset:

today, yesterday, last_3d, last_7d, last_14d, last_28d, last_30d, last_90d, this_week_mon_today, this_week_sun_today, last_week_mon_sun, last_week_sun_sat, this_month, last_month, this_quarter, last_quarter, this_year, last_year, maximum.

For custom ranges, use --since YYYY-MM-DD --until YYYY-MM-DD.

Time series via --time-increment

• 1 = daily (one row per day per object)
• 7 = weekly (Mon–Sun)
• monthly = one row per calendar month
• omitted = single row covering the whole period

Attribution windows — the confusion zone

By default, Meta returns numbers using your account's default attribution setting (usually 7-day click). To request specific windows, pass --action-attribution-windows:

• 1d_view — viewed ad, converted within 1 day, no click
• 7d_view — same but 7 days
• 1d_click — clicked, converted within 1 day
• 7d_click — clicked, converted within 7 days (most common default)
• 28d_click — clicked, converted within 28 days (deprecated for some objectives)

Important: the value in each action object is bound to one window — if you request multiple windows, each row gets per-window subkeys. This trips up everyone the first time.

Things Meta won't let you do (that you might try)

• Combine `breakdowns: age` with `breakdowns: country` AND a third dimension — usually fails with "Cannot have action breakdowns ... with the breakdowns".
• Request `reach` at the ad level over a long period broken down by demographic — Meta refuses on privacy grounds. Aggregate higher (campaign or account level) instead.
• Get hourly data older than 35 days.
• Get per-day rows for ranges over 90 days synchronously — falls back to async automatically in our fetch_insights.py, but be patient.
• Mix `purchase_roas` with `breakdowns=product_id` — known to silently return zeros. Use action_values + product_id breakdown instead.

When numbers don't match Ads Manager

This happens constantly. Usual causes: 1. Different attribution window. Ads Manager defaults can differ from API defaults. 2. Time zone. Ad account uses one TZ; you might be querying in another. 3. Currency conversion. spend is in the account currency. If the account is multi-currency, the rate at query time may differ from when the ad ran. 4. Late-arriving data. The current day is incomplete; conversions can take 24–72 hours to fully attribute. 5. Data freshness for "last 7d" — Meta sometimes lags 1–2 hours on hot data.

If a number is more than 5% off from Ads Manager, check attribution window first. If still off, query at a more granular level and sum — sometimes Meta's aggregate roll-up has reporting discrepancies.

Useful field combinations

Link CTR (the one that actually matters):

fields: impressions, actions[action_type=link_click]
formula: link_clicks / impressions

True CPA for an event:

fields: spend, actions[action_type=purchase]
formula: spend / purchase count

Or just request cost_per_action_type and read the right one from the array.

CTWA cost per conversation:

fields: spend, actions
filter actions for action_type = onsite_conversion.messaging_conversation_started_7d
formula: spend / count

One-time Meta API setup — step by step

This is the only manual part of the skill. Meta's developer console involves real web-UI clicks and decisions only you can make, so we'll go slowly. Expect 15–25 minutes end to end, mostly waiting for Meta's UI to load.

Works on macOS, Windows, and Linux. Per-OS command blocks are shown side by side. You only need to run the commands for the OS you're on.

If anything on screen looks different from what's described below, don't panic — Meta redesigns this console regularly. Look for the same text labels even if colors or positions have shifted. If you get truly stuck, jump to references/troubleshooting.md.

---

Before you start: prerequisites

1. Python 3 installed on your machine

You need Python 3.8 or newer. Check which version you have:

macOS (Terminal):

/usr/bin/python3 --version

If you see Python 3.x.x you're good. If you see "command not found", install Python:

# Easiest: install Homebrew-managed Python
brew install python
# Or download the installer from https://www.python.org/downloads/macos/

Windows (PowerShell or cmd):

python --version

If that fails, try py --version. If neither works, download the installer from https://www.python.org/downloads/windows/ and tick the "Add python.exe to PATH" checkbox on the first screen of the installer — without it, python won't work from the terminal. After install, close and reopen your terminal.

Linux (Bash):

python3 --version

If missing: sudo apt install python3 python3-pip (Debian/Ubuntu) or your distro's equivalent.

2. The requests Python library

All scripts use one library: requests. Install it once:

macOS:

python3 -m pip install --user requests

Windows (PowerShell or cmd):

python -m pip install --user requests

If python isn't recognized, try py -m pip install --user requests.

Linux (if you hit "externally-managed-environment"):

python3 -m pip install --user --break-system-packages requests

Verify it installed:

python3 -c "import requests; print(requests.__version__)"   # macOS / Linux
python -c "import requests; print(requests.__version__)"    # Windows

You should see a version number like 2.31.0 print out.

3. A terminal open in the skill's directory

You'll be running scripts from inside the skills/meta-ads/ folder. Open a terminal there now so you don't have to re-navigate every time:

macOS (Terminal):

cd /path/to/skills/meta-ads

Windows (PowerShell):

cd C:\path\to\skills\meta-ads

Every subsequent command in this guide assumes you're in that directory.

---

Step 0: Which path should you use?

Meta has two token types. Pick one by answering three yes/no questions:

1. Do you boost Instagram posts directly from the Instagram app? If yes → Path B. 2. Is the ad account you care about owned by a Meta Business Manager you created? If no → Path B. 3. Do you want a token that never expires, with all ads running from a single BM? If yes → Path A.

Still unsure? Pick Path B. A Path B (user) token sees everything a Path A (System User) token sees plus personal ad accounts created by Instagram boosts. You can always switch to Path A later.

Both paths share Steps 1 and 2 below. Do those first, then follow your chosen path.

---

Step 1: Create a Meta developer app (both paths)

1.1 Open the developer console

Open your browser and go to https://developers.facebook.com/apps. Log in with the Facebook account that has access to your ads. If this is your first time there, Meta may ask you to register as a developer — agree to the terms.

1.2 Start a new app

Look for a green or blue "Create App" button, usually in the top-right corner of the page. Click it.

1.3 Choose the use case

You'll land on a page titled "What do you want your app to do?" with several tile options. Select "Other" (usually in the bottom row). Click "Next" at the bottom.

1.4 Choose the app type

On the "Select an app type" page, pick "Business". Click "Next".

1.5 Fill in app details

• Display name: something descriptive for you only — e.g., my-meta-ads-skill. Nobody else will see this.
• App contact email: your email.
• Business Account (optional): if you already have a Business Manager, select it from the dropdown. If not, skip — you can attach one later (or never, if you go Path B).

Click "Create app". Meta may ask for your password to confirm.

1.6 Land on the app dashboard

After creation you'll be taken to your app's dashboard — a page showing the app name at the top and a list of available products in the main panel. Keep this tab open; you'll come back to it.

---

Step 2: Add the Marketing API product (both paths)

2.1 Find the product list

Still on the app dashboard, scroll down to a section titled "Add products to your app" or look in the left-hand sidebar for "Add product".

2.2 Add Marketing API

Find the "Marketing API" tile. Click "Set up" on it. The page reloads and Marketing API appears in the left sidebar.

2.3 Note your App ID and App Secret

In the left sidebar, click "Settings" → "Basic". You'll see:

• App ID — a 15-digit number at the top.
• App Secret — hidden behind a "Show" button. Click it; you may need to re-enter your password.

Copy both to a password manager or a scratch file. You'll need the App ID in both paths, and the App Secret only if you're going Path B.

---

Path A: System User token (recommended if your ads are in a Business Manager)

Use this path only if you confidently answered "yes" to question 3 in Step 0. If you're unsure, skip down to Path B instead.

A.1 Make sure your ad account lives inside a Business Manager

1. Go to https://business.facebook.com/settings and log in. 2. If you've never created a Business Manager (BM), click "Create Account" at https://business.facebook.com. Pick a name for the BM, enter your name and email, click "Submit". 3. In the left sidebar: "Accounts" → "Ad Accounts". You should see the ad account listed under "Ad Accounts I Own". If it's listed under "Ad Accounts I Have Access To" instead, you don't own it and can't create a System User against it — you'll need to transfer ownership (through the account owner) or switch to Path B. 4. If the ad account isn't listed at all: click "Add" (top of the list) → "Add an ad account" → enter the ad account ID (format: 1234567890, the number from Ads Manager's URL). 5. Note your Business ID — visible at the top-right of the Business Settings page or in the URL (business_id=XXXXX).

A.2 Create a System User

1. Still in Business Settings, left sidebar: "Users" → "System Users". 2. Click "Add" (top-right of the system users list). 3. Name: something like meta-skill-system-user. Role: "Admin" (required for writes; pick "Employee" only if you want read-only). Click "Create System User". 4. You now see the new system user's detail page.

A.3 Grant the System User access to your ad accounts and app

1. On the system user's detail page, click "Add Assets" (usually top-right). 2. A panel opens with tabs: Pages, Ad Accounts, Apps, Catalogs, Pixels, …. 3. Ad Accounts tab: tick each ad account you want the skill to read/write. Under "Permissions", check "Manage campaigns" (gives read + write). For read-only, check "Read performance" only. Click "Save Changes". 4. Apps tab: tick the app you created in Step 1. Under "Permissions", check "Manage app" (or "Develop app" — both work). Click "Save Changes".

A.4 Generate the System User token

1. Still on the system user's page, click "Generate New Token". 2. Select App: the one you created in Step 1. 3. Permissions: tick ads_read, ads_management, and business_management. 4. Token expiration: "Never". (This is the whole point of a System User token.) 5. Click "Generate Token". 6. The token appears once — a long string starting with EAAB... or EAA.... Copy it immediately into a password manager. If you close this dialog without copying, you'll have to regenerate.

A.5 Find your ad account ID

Open Ads Manager in another tab (https://adsmanager.facebook.com). The URL contains act=1234567890. That 1234567890 is your ad account ID. The format the API expects is with an act_ prefix: `act_1234567890`.

A.6 Write the .env file

Inside the skills/meta-ads/ folder, copy the template:

macOS / Linux:

cp assets/env.template .env

Windows (PowerShell):

Copy-Item assets\env.template .env

Windows (cmd.exe):

copy assets\env.template .env

Now open .env in your editor (TextEdit / Notepad / VS Code / whatever) and fill in:

META_ACCESS_TOKEN=EAAB...your_system_user_token...
META_AD_ACCOUNT_ID=act_1234567890
META_API_VERSION=v25.0

You can leave META_APP_ID and META_APP_SECRET blank for Path A. Save the file.

A.7 Verify everything works

macOS / Linux:

python3 scripts/auth_check.py
python3 scripts/list_accounts.py --with-recent-spend

Windows:

python scripts/auth_check.py
python scripts/list_accounts.py --with-recent-spend

Expected output:

• auth_check.py prints "ok": true, your identity as the System User, and at least one ad account.
• list_accounts.py lists the accounts the System User can reach, sorted by recent spend. Find yours in the list and confirm it's the one you want.

If ok: false or no accounts appear, see the "Ad account discovery problems" section in references/troubleshooting.md.

You're done with Path A. Skip ahead to "What to put in your password manager".

---

Path B: Long-lived user token (for personal ad accounts or Instagram-app boosts)

B.1 Get a short-lived user token from Graph Explorer

1. In your browser, go to https://developers.facebook.com/tools/explorer. Make sure you're logged into the personal Facebook account that owns the ads or Instagram account you want to analyze. 2. Top-right, find the "Meta App" dropdown. Click it and select the app you created in Step 1. 3. Next dropdown, "User or Page": pick "User Token". 4. Click the "Permissions" dropdown/button. A popup opens with a long list of scopes. Tick:

• ads_read
• ads_management
• business_management
• pages_show_list (needed if any boosted content came from a Page)

Close the permissions popup. 5. Click "Generate Access Token". A Facebook OAuth popup appears asking you to confirm. If it lists specific Pages, pick the ones associated with your Instagram account. Click "Continue" through the prompts. 6. The token now appears in the big text field at the top of Graph Explorer (long string starting with EAAB...). Copy it somewhere safe — a scratch file is fine.

This token only lasts ~1–2 hours. You're about to swap it for a 60-day one in step B.2. Don't dawdle.

B.2 Exchange for a 60-day long-lived token

1. First, fill in your App ID and App Secret (from Step 2.3) in .env. If .env doesn't exist yet, copy it:

macOS / Linux:

   cp assets/env.template .env

Windows (PowerShell):

   Copy-Item assets\env.template .env

Windows (cmd.exe):

   copy assets\env.template .env

Open .env and set:

   META_APP_ID=1234567890
   META_APP_SECRET=abcdef1234567890abcdef1234567890

Save.

2. Now run the exchange script. It will prompt you for the short-lived token and write the resulting 60-day token into .env automatically.

macOS / Linux:

   python3 scripts/exchange_token.py --write-env

Windows:

   python scripts/exchange_token.py --write-env

3. When prompted, paste the short-lived token from step B.1 and press Enter. Your input is hidden (no dots or characters appear) — that's intentional, paste and press Enter.

4. On success you'll see "ok": true, the expiration (~59.5 days in seconds), and META_ACCESS_TOKEN will be set in your .env.

5. The short-lived token is now useless — delete it from wherever you pasted it.

B.3 Discover your ad accounts

macOS / Linux:

python3 scripts/auth_check.py
python3 scripts/list_accounts.py --with-recent-spend

Windows:

python scripts/auth_check.py
python scripts/list_accounts.py --with-recent-spend

list_accounts.py returns every ad account your Facebook user can see, sorted by last-30-day spend. Find the one with the activity you care about and copy its id value (format act_1234567890).

B.4 Pin the default ad account

Open .env and add or update:

META_AD_ACCOUNT_ID=act_1234567890

Save. Now every script will default to this account without needing --account-id each time.

B.5 Re-verify

Run auth_check.py one more time:

macOS / Linux: python3 scripts/auth_check.py Windows: python scripts/auth_check.py

It should print "ok": true with your identity (your Facebook display name) and a list of visible accounts.

B.6 The 60-day rotation

Long-lived user tokens expire after ~60 days. Meta emails you a warning ~10 days out, but don't rely on it — set a calendar reminder for 55 days from now. When the token expires: 1. Repeat step B.1 (get a fresh short-lived token from Graph Explorer). 2. Run exchange_token.py --write-env again. Same flow, same outcome.

Your App ID and App Secret don't change, so .env just needs the new META_ACCESS_TOKEN.

---

App Review (you probably don't need this)

Your app will stay in "Development mode" — that's fine. Development mode means only you (and anyone you explicitly added as admin/developer of the app) can use the token to hit the API. For a personal-use skill, that's exactly what you want.

App Review is only required if you want other Meta users (not you, not your System User) to sign into your app and use it against their accounts. If that's your use case, this skill isn't the right shape — each user should run their own setup with their own app.

---

What to put in your password manager

Save these somewhere safe (1Password, Bitwarden, iCloud Keychain, etc.):

• App ID
• App Secret (only if you went Path B)
• Access token (System User token for Path A, 60-day user token for Path B)
• Business Manager ID (Path A only)
• Ad Account ID(s) (act_… format)

These are the keys to your ad kingdom. Anyone with your token can spend money on your ads and read your ad data — treat the token like a credit card number.

Do not commit `.env` to git. If you're copying this skill into a repo of your own, add .env to your .gitignore before your first commit.

---

Troubleshooting

If any step failed or produced unexpected output, head to `references/troubleshooting.md` for the real-world failure modes we've already seen. The top ones:

• auth_check.py returns ok: true but ad_accounts_visible: 0 — token works but sees nothing. Fix in troubleshooting.md.
• (#3018) start date cannot be beyond 37 months — Meta only serves data from the last 37 months. Older campaigns are invisible via API; check Ads Manager's archived reports UI instead.
• ProxyError: Tunnel connection failed: 403 — your environment can't reach graph.facebook.com. Run the scripts on your own machine instead of a sandbox.
• ModuleNotFoundError: No module named 'requests' — install it with the command from the "prerequisites" section above.
• (#200) Permissions error on a write call — your token doesn't have ads_management scope (Path B) or the System User doesn't have "Manage campaigns" (Path A).

If none of those match, share the full JSON output of the failing script with the assistant — the error messages Meta returns are usually actionable.

Troubleshooting

Real failure modes observed when running this skill. Read the section that matches your symptom.

If none of these match, re-run python scripts/auth_check.py and share the full JSON output with the user — it's usually the fastest path to the root cause.

---

Auth / token problems

auth_check.py returns ok: true but ad_accounts_visible: 0

The token is valid, but the identity it resolves to can't see any ad accounts. Two causes:

Path A (System User token): the System User hasn't been granted access to any ad accounts yet. Go to Business Settings → Users → System Users → click the user → Add Assets → Ad Accounts tab → tick each account → grant "Manage campaigns" or "Read performance" → Save. Re-run auth_check.py.

Path B (user token): the FB user who generated the token at Graph Explorer doesn't own or have been granted access to any ad accounts. Two sub-causes:

• You were logged into the wrong FB account in Graph Explorer when you generated the token. Log out, log into the right one, repeat B.1.
• The OAuth popup during B.1 didn't include ads_read / ads_management / business_management scopes. Regenerate with those permissions checked.

auth_check.py returns ok: false with code 190

The token is expired or revoked. For Path B: tokens expire after ~60 days — repeat B.1 then B.2 in setup.md to get a fresh one. For Path A: System User tokens don't expire, so if you see 190 on one, either it was explicitly revoked in Business Settings or the System User itself was deleted. Regenerate.

auth_check.py returns ok: false with code 102 or 4

Session expired / app restriction. Almost always means the App Secret was regenerated or the app was put into "Live" mode without App Review. For personal use, the app should stay in "Development mode" — check App Dashboard → App Mode toggle.

exchange_token.py fails with (#100) Invalid OAuth access token

The short-lived token you pasted is already expired (they last ~1–2 hours) or mistyped. Go back to Graph Explorer, click "Generate Access Token" again, paste the fresh one immediately.

exchange_token.py fails with (#1) Unknown error or (#101) Missing client_id parameter

META_APP_ID and/or META_APP_SECRET are missing or wrong in .env. Re-copy both from your Meta developer app → Settings → Basic. The App Secret needs to be revealed via the "Show" button — make sure you copied the actual secret, not the placeholder dots.

(#200) Permissions error when calling a write endpoint

The token has ads_read but not ads_management. User tokens inherit only the scopes granted at OAuth time — regenerate with ads_management checked. System User tokens need the "Manage campaigns" role on the specific ad account (not just "Read performance").

---

Network / environment problems

requests.exceptions.ProxyError: Tunnel connection failed: 403 Forbidden

Your execution environment can't reach graph.facebook.com. This happens with Claude's Linux sandbox in some configurations — the outbound proxy blocks Meta's Graph domain.

Fix: run the scripts from the user's host machine (their Mac/Windows/Linux) instead of the sandbox. On macOS use /usr/bin/python3. Install deps on the host first:

/usr/bin/python3 -m pip install --user requests

Then run each script with the host Python:

/usr/bin/python3 /path/to/skills/meta-ads/scripts/auth_check.py

Don't try curl / wget / a different HTTP library — the block is at the proxy layer, not in requests.

ModuleNotFoundError: No module named 'requests'

Python doesn't have requests installed. Pick the command that matches your OS:

# macOS
python3 -m pip install --user requests

# Windows (PowerShell or cmd)
python -m pip install --user requests
# or if that fails:
py -m pip install --user requests

# Linux (normal case)
python3 -m pip install --user requests

# Linux with PEP 668 enforcement (Debian/Ubuntu 22+)
python3 -m pip install --user --break-system-packages requests

If you installed it but still see the error, you probably have multiple Python versions on your machine. Install against the same interpreter you're running the script with — find it with:

• macOS / Linux: which python3 then python3 -m pip show requests
• Windows: where python then python -m pip show requests

SSLError / certificate verification failed

Either the host clock is badly wrong (check date on macOS/Linux or Get-Date in PowerShell) or a corporate proxy is intercepting TLS. For corporate networks, set REQUESTS_CA_BUNDLE to point at your org's CA bundle, or run on a personal machine.

---

Windows-specific issues

python is not recognized as an internal or external command

Python isn't on your PATH. Two fixes:

1. Re-run the Python installer from <https://www.python.org/downloads/windows/> and on the first screen tick "Add python.exe to PATH". Close and reopen your terminal after installing. 2. Use `py` instead. The Python launcher py is installed separately and usually works even when python doesn't:

   py --version
   py scripts/auth_check.py
   py -m pip install --user requests

Hebrew, Arabic, or other non-Latin characters show as ? or garbled in cmd.exe

cmd.exe's default code page is Windows-1252, which can't display Unicode. Switch to UTF-8 for the current session:

chcp 65001

Then re-run your script. To make UTF-8 the default permanently, set the system locale in Region settings → Administrative → "Beta: Use Unicode UTF-8 for worldwide language support" (requires a reboot).

PowerShell and Windows Terminal usually handle UTF-8 correctly without changes.

Scripts run but .env values aren't being picked up

Windows line endings (CRLF) can break the .env parser on older tooling, though meta_client.py's loader handles CRLF correctly. If you suspect it's the issue, open .env in VS Code and check the bottom-right — if it says "CRLF" click to change to "LF" and save.

Copy-Item : Cannot find path in PowerShell when copying .env

You're not in the skill's directory, or the template name is different. Verify:

Get-Location           # should end in \skills\meta-ads
Get-ChildItem assets   # should list env.template

PowerShell execution policy prevents running scripts

You shouldn't hit this because the skill only uses .py files (not PowerShell scripts), but if you add a .ps1 wrapper and get "running scripts is disabled on this system", run:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Long path errors when running scripts from deep directories

Windows has a legacy 260-character path limit. If your skill folder is nested very deep (e.g., C:\Users\you\OneDrive\Documents\Projects\whatever\ai-agents-skills\skills\meta-ads\…) and you see "file name too long" errors, either move the folder closer to the drive root or enable long paths in Windows:

# Run as admin
Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1

Then reboot.

---

Ad account discovery problems

list_accounts.py shows an account with account_status: 3 / UNSETTLED

The account has an unpaid balance. Meta still returns it and insights still work, but new campaigns can't be created until payment is resolved. Head to Ads Manager → Billing to clear it. This is not a bug in the script.

list_accounts.py shows account_status: 7 / PENDING_RISK_REVIEW

Meta has flagged the account for manual review. Read-only insights usually still work; writes don't. Appeal via Ads Manager → Account Quality. No API workaround.

I boosted a post from the Instagram app but list_accounts.py doesn't show its ad account

Two possibilities:

1. You're on a Path A (System User) token. IG-app boosts typically create a personal ad account attached to your FB profile, not inside any Business Manager — and System User tokens can only see BM-owned accounts. No amount of permissions fixes this because the account is structurally outside the BM. Switch to Path B (user token) and you'll see it. 2. The boost ran under a different FB account than the one you used at Graph Explorer. Check which FB login owns the Instagram account that did the boost.

"I added the ad account to the Business Manager, why doesn't the SU token see it?"

Two missing steps, in order: 1. BM owns the ad account → Business Settings → Accounts → Ad Accounts → it should be listed under "Ad Accounts I Own", not "Ad Accounts I Have Access To". If it's the latter, you don't have write access — contact the account owner to transfer it. 2. System User has been granted the ad account as an asset → Business Settings → Users → System Users → click the user → Add Assets → tick the account → save.

After both, regenerate the System User token (the old one's scope is cached at generation time).

Wrong ID pasted into META_AD_ACCOUNT_ID

Common mixup: in Business Settings the System User page shows the System User's ID prominently (a 15-digit number). People sometimes paste that into META_AD_ACCOUNT_ID. It's not an ad account ID.

Ad Account IDs come from Ads Manager's URL (act=<digits>) or from list_accounts.py output. The format the API expects is act_<digits>.

---

Insights / data problems

(#3018) The start date of the time range cannot be beyond 37 months from the current date

Meta's insights API only serves data from the last 37 months. Any campaign older than that is invisible to the API. If the user asks about a 2019 campaign in 2026, the answer is literally "the API can't tell you."

Workaround: open Ads Manager → Reports → Archived Reports, run the report in the UI, export CSV. Do not try to construct clever date ranges to sneak past the cap — Meta checks each range's start date against the 37-month wall.

(#1815001) Cannot Request for Deleted Objects

You tried to request effective_status values that include DELETED on the campaigns endpoint. Meta's campaigns edge doesn't support filtering on DELETED — it returns 1815001 rather than empty. list_campaigns.py already excludes DELETED from --status choices for this reason.

If you really need to see deleted campaigns, use Ads Manager's UI with the "Deleted" filter. There's no API path.

fetch_insights.py times out on a long date range

Switch to async mode: add --async or let the script auto-fall-back. Async insights jobs can run up to 30 minutes server-side; sync calls time out at ~60s.

If --async also fails with "Job Failed", your query is likely too broad for Meta's async quota too. Split the date range (e.g., one month at a time) or reduce breakdowns.

Insights return spend: "0" but Ads Manager shows spend

Three common causes: 1. Attribution window mismatch. Ads Manager defaults to 7-day-click + 1-day-view. API defaults to a narrower window depending on version. Pass action_attribution_windows=['7d_click','1d_view'] explicitly in the insights query. 2. Level mismatch. You queried level=account but the campaign is on a sub-account. Check the account_id on the campaign. 3. Currency confusion. spend is returned in the account's currency (as a decimal string in major units for insights — unlike amount_spent on the account object, which is minor units). Don't confuse the two.

Click numbers seem too high

clicks includes every click anywhere on the ad — reactions, "See more" expansions, profile clicks. For outbound link clicks only, use inline_link_clicks. For the metric Ads Manager calls "Link clicks", it's actions where action_type = link_click.

---

Display / encoding problems

Hebrew / Arabic / Chinese campaign names show as \u05d2\u05dd... in output

JSON escaping. Scripts output ensure_ascii=False so this shouldn't happen when you run them directly. If you see escaped Unicode, you're probably viewing the output through a pipe that doesn't handle UTF-8 — on Windows cmd.exe, run chcp 65001 first; on macOS/Linux it usually Just Works unless LANG is set to C.

amount_spent is a weirdly large number like 1691697

That's minor units (agorot / cents / pence). Divide by 100 for most currencies. For zero-decimal currencies (JPY, KRW, VND, CLP, ISK, UGX, XAF, XOF, TWD) don't divide. list_accounts.py already does this conversion and exposes it as amount_spent_major. The raw amount_spent field is preserved for anyone who needs it.

---

Write action problems

pause_ad.py or update_budget.py returns ok: true but the change didn't happen in Ads Manager

Ads Manager's UI caches state for 30–60 seconds. Refresh the browser. If it's still wrong after a minute, pull the ad back via the API — the truth is what the API returns, not the cached UI.

Budget change rejected with (#100) Invalid parameter

Either the new budget is below Meta's minimum for the currency, or above the account's spend_cap, or you passed it in the wrong units. Budgets on write are passed in minor units (same as amount_spent) — the scripts convert for you, but if you're calling the API directly, pass daily_budget=500 for ₪5.00, not daily_budget=5.

"I wanted to duplicate an ad, why did the copy show up paused?"

Meta always creates copies in PAUSED status by default — this is intentional so you don't immediately spend money on an unverified copy. Unpause via pause_ad.py --unpause <new_ad_id> after reviewing the copy in Ads Manager.

---

When in doubt

1. Run auth_check.py — does the token even work? 2. Run list_accounts.py --with-recent-spend — do you see the account you expect? 3. Run list_campaigns.py --account-id act_xxx — does the campaign list match Ads Manager? 4. If 1–3 all look right but insights are wrong, run the same query in Ads Manager UI and compare — API vs UI discrepancies almost always come down to attribution windows or date ranges.

If you're still stuck, share the full JSON output of whichever script is misbehaving — the errors from Meta are reasonably informative once you can see them.

Write Actions: Safety Protocol

This file is mandatory reading before calling pause_ad.py, update_budget.py, duplicate_ad.py, or create_campaign.py. These scripts touch real money. A misread analysis or a confidently-wrong recommendation can pause a winning ad, 10x a losing budget, duplicate the wrong creative, or launch a campaign against the wrong landing page. There's no "undo" button — Meta will execute the change instantly and you'll be reconstructing the previous state from effective_status history if it goes wrong.

The five non-negotiable rules

1. Explicit confirmation in chat for every single write

A previous "go ahead" or "yes do whatever you think" in the conversation does NOT count. Each individual write call needs its own confirmation message. The user has to actively re-affirm. This is friction by design — the friction is the safety feature.

What confirmation looks like, minimally:

• The user explicitly names the action (yes pause it, confirm, כן תשנה, בצע)
• It's the user's most recent message before the write call
• It's not just "ok" or "👍" in response to something else — it has to be unambiguous about the specific action

If you're unsure whether a message is a confirmation, treat it as not. Ask again.

2. Surface the impact before asking

Don't just say "should I pause ad 12345?" Say:

Pause ad `Summer_Launch_v3` (ID 120214567890)?

- Spent ₪47.20 over the last 7 days

- 0.8% CTR (vs your account avg 1.4%)

- 12 link clicks, 0 conversions

- Ad set still has 3 other ads delivering, so the ad set won't go dark

>

Confirm with yes to proceed.

The user can only consent to what they understand. If you can't explain the impact in 3-5 lines, you don't understand it well enough to recommend the action.

3. One action per confirmation, by default

If the analysis suggests pausing 12 ads, don't bundle them into one mega-confirmation. Either:

• Walk through them one at a time (slower but safest), OR
• Present a numbered list of all 12 and explicitly ask for "pause all 12" or "pause #1, #3, #7" — accept partial selections

Never assume a previous batch confirmation extends to a new batch. If the user said "pause those 3 fatigued ads" and you found 5 more later in the conversation, the new 5 need their own confirmation.

4. Always dry-run when the script supports it

Every write script accepts --dry-run. Use it first when:

• This is the first write of the session
• The change is large (>50% budget swing, bulk pause, deep_copy duplications)
• You're acting on data you fetched more than 30 minutes ago (it might be stale)
• The user is testing the skill and hasn't done a write before

The dry-run output shows exactly what would change. Read it back to the user and ask for the real confirmation.

5. Never chain writes without intermediate verification

If the plan is "duplicate the winning ad, then pause the original" — don't run both as a single batch. Run the duplicate, fetch the new ID, confirm to the user that the duplicate is created and in the expected state, then ask to pause the original. Mid-chain failures are the worst kind: you can end up with the original paused and the duplicate broken, leaving the ad set with nothing delivering.

Per-script safety notes

pause_ad.py

• Status PAUSED stops delivery immediately. Spending stops within minutes (not seconds — there's a small in-flight auction tail).
• Status ACTIVE resumes. The ad re-enters the learning phase if it had been paused for >7 days.
• Pausing a campaign also stops all ad sets and ads under it; pausing an ad set stops only its ads.
• A paused ad in an active ad set with active sibling ads has no effect on overall delivery — Meta just shifts spend to the siblings. This is usually desirable.
• A paused ad in an ad set where it was the only active ad means the ad set goes dark. Surface this to the user before pausing.

update_budget.py

• The 2x cap per call is a hard rule. To go from ₪50/day to ₪200/day, do it in steps: ₪50 → ₪100 → ₪175 → ₪200, with confirmations between. Override with --allow-large-increase only if the user explicitly says "yes I understand the risk, do the full 4x".
• Any change >20% triggers Meta's learning-phase reset. The script's output includes a warning field when this applies. Mention it to the user — they should expect 3-7 days of unstable performance after a big budget move.
• Decreases >50% can drive Meta to pause the ad set automatically because the budget is "too low to deliver". Watch for effective_status: CAMPAIGN_PAUSED in subsequent fetches.
• Lifetime budgets and daily budgets are mutually exclusive on a given object. The script auto-detects which is set; if both or neither are returned, it refuses to act.
• For campaign budget optimization (CBO) campaigns, budget lives at the campaign level, not the ad set. The script handles this correctly because it queries the object first, but be aware: passing an ad set ID for a CBO campaign will fail with a clear error.

duplicate_ad.py

• Default --status PAUSED is the right default. Only override if the user explicitly wants the duplicate to go live immediately.
• deep_copy=true (used for campaigns) duplicates the entire tree — campaign, ad sets, ads, creatives. For a campaign with 5 ad sets and 20 ads, that's 26 new objects. Tell the user the count before duplicating.
• Duplicating an ad set into a different campaign (--target-parent-id) requires the target campaign to have a compatible objective. Mismatched objectives → API error.
• Naming: Meta's default suffix is " - Copy". Use --rename to keep the account organized — naming chaos compounds fast across iterations.
• Duplicate ≠ fresh creative. A duplicated ad is the same ad, just a new ID. It enters its own learning phase but the creative is identical. If the original is fatigued because of creative burnout, duplicating won't help — only new creative will.

create_campaign.py

This is the newest and highest-blast-radius write. One --confirm run produces a campaign plus N ad sets plus M creatives plus M ads — typically 5-10+ new objects from a single command. Get it wrong and you're rolling back a tree of objects spread across Ads Manager.

• Dry-run is not optional. Before the first --confirm of any spec, run --dry-run and walk the full plan back to the user: campaign name, objective, identity (page + IG), every ad set's targeting and budget, every ad's headline and CTA. Only ask for confirmation after the user has seen this.
• All objects default to PAUSED. Don't override status: ACTIVE on creation unless the user has explicitly typed "create ACTIVE" or the equivalent in their language. The PAUSED default is a checkpoint — the user flips to ACTIVE in Ads Manager once they've eyeballed the creative, which catches problems the API can't (wrong image, weird Hebrew rendering, headline that looks fine at 40 chars in a spec but truncates ugly on mobile).
• Never launch a conversions campaign against an account with no pixel. Even if the user asks for objective: OUTCOME_SALES, if /me/pixels returns empty or no Purchase events have fired in 30+ days, refuse and explain why: Meta has nothing to optimize toward, spend will go to random clicks, and the campaign will look broken by week 2. Offer OUTCOME_TRAFFIC as the interim path. Document this decision to the user before proceeding.
• Watch for `UNSETTLED` on the ad account. list_accounts.py reports account status. If the account is unsettled, objects get created but nothing delivers. That's fine — surface it, don't block. Users typically want the structure in place while they clear the balance.
• `special_ad_categories` matters. If the campaign is for housing, employment, credit, or political/social issues, the spec MUST set the right category. Wrong category = total campaign rejection on review, with a Meta penalty counter. If the user's copy mentions loans, interest rates, job listings, or political figures, confirm the category before --confirm.
• Creative review expects accurate claims. Social proof numbers ("10,000+ enrolled"), ranking claims ("#1 in Israel"), guarantee language, celebrity endorsements — all get reviewed. Before --confirm, surface every numeric or superlative claim baked into the image or copy and ask the user whether it's truthful and provable. Fabricated social proof isn't just ethically bad — it gets the whole creative banned.
• State file is the rollback surface. Every --confirm writes <spec>_state_<timestamp>.json with every object ID in creation order. Keep it. If anything's wrong after creation, rollback_creation.py --state <file> --pause soft-stops everything in one call.
• One campaign at a time. Don't batch multiple --confirm calls. Each campaign is a separate spec, separate dry-run, separate explicit confirmation. This limits blast radius if the spec is broken.
• Never chain create → activate. If the user wants the campaign live immediately, that's a separate subsequent confirmation: create (PAUSED), verify the objects look right by fetching them back and reading creative previews, then call the activation as its own write.

When something goes wrong

If you executed a write and the user wants to undo it:

• Pause → Active rollback: call pause_ad.py --status ACTIVE on the same ID. Note: if the ad was paused for >7 days, it re-enters learning.
• Budget rollback: call update_budget.py with the previous value. Each script's success output includes the previous value (status_before, before_minor) — capture these into the conversation context immediately so they're available for rollback.
• Duplicate rollback: the duplicate has a new ID returned in the output. To "undo," delete or pause the new copy. Deleting requires delete() on the meta_client — there's no bundled script because permanent deletion is risky; do it via the Meta UI unless the user really wants programmatic delete.

What this skill will NOT help with

• Bulk operations across accounts. Each call is scoped to one ad account at a time. Multi-account bulk = multi-tenant work, wrong skill.
• Editing existing creatives. You can CREATE new creatives via create_campaign.py (link_data with image upload). Modifying the image or copy on an already-live creative is a different shape — Meta requires a new creative object and swap on the ad. Out of scope for v1.
• Dynamic creative, catalog ads, collection ads. create_campaign.py handles single-image link ads only. Those other formats use asset_feed_spec, product_set_id, or template_data — extend the script or write a sibling for them.
• Custom Audience creation or modification. You can USE existing Custom Audience IDs in targeting.custom_audiences, but building a new audience (from pixel events, customer lists, IG engagers, etc.) is a separate API surface and out of scope for v1.
• Pixel / CAPI event manipulation. Different API entirely (Conversions API), different auth, different mental model.
• Scheduled writes. This skill is on-demand. If the user wants "pause all ads with frequency >4 every Monday morning," that belongs in a scheduler (cron, a scheduled-tasks integration, etc.), not inside this skill.

Scope note: personal-scale vs. agency / enterprise

This skill is built for personal-scale ad management — one operator, one set of credentials, a handful of ad accounts. At that scale individual writes matter and confirmations are easy.

If this ever gets pointed at multi-tenant use (an agency managing dozens of client Business Managers, or an in-house team acting on shared client accounts), the rules in this file are insufficient. You'd need per-client credential storage, an audit log of every write with operator identity, role-based access, and probably a four-eyes approval flow for anything above a threshold. Don't try to retrofit this skill — build a separate multi-tenant version. Each account owner should run their own setup with their own Meta app and their own System User token.