Meta Ads Field Guide for Claude Code

Claude Code + Meta Ads without disasters. A drop-in skill, 3 subagents, and safety hooks that let marketers run Facebook/Instagram campaign automation safely — built on 4,800+ lines of battle-tested Meta Marketing API field notes.

Marketers are using Claude Code to automate Meta Ads work: creating campaigns, pulling insights, scaling budgets, analyzing creatives. But the LLM doesn't know that:

• Changing a budget by more than 20% silently resets your Learning Phase
• The same image hash from another ad account will render as a placeholder (no error)
• CONVERSIONS and LINK_CLICKS objectives are deprecated — new campaigns need OUTCOME_*
• Editing 5+ budgets in an hour locks the ad set for 60 minutes
• Most MCP servers let you create ads with status: "ACTIVE" by default

So Claude makes confident, expensive mistakes.

This repo fixes that. Copy one folder into your project and Claude Code suddenly:

• Blocks any API call that would create non-PAUSED ads (via PreToolUse hook)
• Follows a Research → Synthesis → Implementation → Verification workflow with a user-approval gate
• Loads the right field guide page for the current task (rate limits, insights, budgets, creatives, etc.)
• Knows the 23 production pitfalls that Meta's official docs don't warn you about
• Enforces v24-compliant fields so you don't ship deprecated code

Last verified for: Marketing API v24.0 (October 2025) · Planning for v25.0 (Q1 2026).

---

Who this is for

Primarily:

• 🎯 Marketers using Claude Code who want to safely scale their Meta Ads work without learning the API internals
• 🧠 Growth / performance marketers running multiple accounts who need parallel audits, creative analysis, bulk campaign launches
• 🛠️ Marketing ops teams wanting to codify their RSIV workflow as hooks + skills, not prompt discipline

Also useful for:

• 👩‍💻 Developers building internal Meta Ads tools
• 📊 Data / ETL engineers shipping Meta Ads → warehouse pipelines
• 🤖 Anyone using Cursor, ChatGPT, or custom agents that need Meta API context

Not for: "what is a Facebook Pixel" tutorials, Ads Manager UI walkthroughs, or generic CRO strategy advice.

---

What's missing in the ecosystem (and why this exists)

Search GitHub for "Meta Ads" and you'll find:

• SDKs (Python, PHP, Node, Java, Ruby) — handle syntax, not strategy
• MCP servers (Pipeboard, mikusnuz, Konquest, Armavita) — let the LLM call the API, but assume you already know what to ask
• ETL vendors (Fivetran, Supermetrics, Funnel, Windsor) — hide the API behind a paywall
• Tutorials — stop at "hello world" + happy path

What's missing: a Claude Code integration that turns house rules ("always PAUSED", "attribution from donor", "incremental > rebuild") into enforced guardrails — paired with the production knowledge about why those rules exist. That's this repo.

---

Table of contents

Core mechanics

1. Rate Limits — the formula, the headers, the scoring
2. Insights API — unique metrics, breakdowns, attribution windows
3. Budgets & Learning Phase — the 4/hour rule and what resets learning
4. Creatives & DCO — asset_feed_spec limits, immutable creatives

Ops

5. Deprecations Timeline 2026 — what breaks when
6. Error Codes Cheatsheet — code → fix mapping
7. Pitfalls — the 15 things official docs won't warn you about
8. Cross-account Operations — the page/creative/audience transfer problem

Ecosystem & strategy

9. Ecosystem & Tools — SDK vs MCP vs ETL, which to use when
10. Cookbook — 10 end-to-end recipes
11. The Breakdown Effect — why your "bad" segments are actually good
12. Related Resources — the curated ecosystem (50+ repos categorized)
13. Conversions API (CAPI) — recover the 30-40% lost to browser tracking

Code

• examples/backoff_and_monitor.py — read rate-limit headers, back off proactively
• examples/multi_id_fetch.py — fetch N objects in one call
• examples/async_insights.py — the report_run_id polling workflow
• examples/batch_jsonpath.py — chain batch requests with JSONPath references

Checklists

• Pre-campaign creation (v24-compliant)
• Mass operations (70+ API calls)
• Cross-account copy

---

The 10 most useful non-obvious facts

1. Your hourly rate limit is a formula: 300 + 40 × active_ads (Standard access). 50 active ads → 2,300 calls/hour. Details
2. There are three parallel limits — call count, CPU time, total time. Any at 100% = throttle. Details
3. You can read X-Business-Use-Case-Usage from every response to back off before you hit 100%. Most code doesn't. Example code
4. Budget can be changed max 4×/hour per ad set. Error subcode 1487225 blocks for an hour. Details
5. Unique metrics (reach, frequency) + date range > 28 days = high failure rate. Query them separately with short windows. Details
6. Changing budget by > 20% resets the learning phase. So does swapping creative, audience, or bid strategy. Duplicate the ad set instead. Details
7. Creatives are immutable and shareable — one creative_id → N ads across campaigns. Don't re-upload, reference. Details
8. ASC/AAC legacy campaigns are dying in Q1 2026 (v25.0). Migrate via migrate_to_advantage_plus. Timeline
9. Cursor auto-pagination in the official Python SDK silently triggers rate limits at ~25 pages. Use manual pagination. Details
10. The segment with worst breakdown CPA is probably your BEST spend. It's called the Breakdown Effect. Details

---

Quick decision guide

"I just need to pull data into a warehouse" → Use an ETL vendor (Fivetran / Supermetrics / Funnel / Windsor). See Ecosystem guide.

"I want to automate campaign creation" → Write raw HTTP with the patterns in this guide. Official SDKs have known pagination issues. See Pitfall 10.

"I want AI to manage ads via chat" → Use an MCP server (pipeboard-co/meta-ads-mcp is the most mature). Pair with this guide so the LLM knows the failure modes.

"Claude Code / Cursor keeps making up API parameters" → Drop this repo into your project as context/ and reference it in your system prompt. The LLM will stop hallucinating deprecated fields.

"Something broke, I don't know what" → Start with Error Codes. If the code isn't there, check Pitfalls.

---

🚀 Claude Code drop-in integration

This repo includes a ready-to-copy Claude Code template — skill, subagents, hooks, MCP config — so you can go from zero to production-safe Meta Ads automation in 2 minutes.

# From your project root:
git clone https://github.com/YOUR-USERNAME/meta-ads-api-field-guide.git
cp -r meta-ads-api-field-guide/.claude-template .claude
mv .claude/settings.json.example .claude/settings.json
mv .claude/mcp.json.example .mcp.json
chmod +x .claude/hooks/*.sh .claude/hooks/*.py

What you get:

• meta-ads skill — auto-loads on Meta Ads tasks, enforces 10 hard rules, progressive doc loading
• 3 specialized subagents:
  • meta-ads-auditor — read-only account health (run in parallel per account)
  • meta-ads-creative-analyst — rank creatives, detect fatigue, find winning concepts
  • meta-ads-campaign-architect — plans campaigns, stops at user approval gate
• enforce-paused.py hook — blocks any API create with status != PAUSED at the tool-call layer
• log-api-write.sh hook — audit trail for every write
• 4 MCP server configs — pick Pipeboard (most mature), mikusnuz (135 tools), Konquest (safety-first), or Pipeboard local

Full setup guide: claude-integration/README.md

With Cursor, ChatGPT, or custom agents

The skill and subagents are portable — Cursor reads .claude/skills/ natively. For ChatGPT / other agents, drop the docs into context:

@meta-ads-api-field-guide/docs/01-rate-limits.md
@meta-ads-api-field-guide/docs/07-pitfalls.md

Or use in your system prompt:

"When working with the Meta Marketing API, reference the field guide at ./meta-ads-api-field-guide/. Load specific doc pages on demand based on the task (e.g., 02-insights-api.md for insights queries). Before any write, check 07-pitfalls.md and follow the RSIV workflow defined in the meta-ads skill."

---

How this guide is organized

Each doc page follows the same pattern:

1. The rule — what Meta enforces
2. The numbers — concrete limits, not vibes
3. The gotcha — what breaks in production
4. The workaround — what actually works at scale

Every claim is cited — GitHub SDK issue, Meta blog post, official docs, or ETL vendor engineering notes.

---

Contributing

Hit a failure mode not covered here? Open an issue or PR with:

• Error code + subcode
• Minimal reproduction
• Meta API version when reproduced

We version lessons by quarter. Things break. See CONTRIBUTING.md.

---

Changelog

See CHANGELOG.md.

---

License

MIT — use freely, attribution appreciated but not required.

---

Sources

Primary references cited throughout the docs:

Official Meta docs:

• Marketing API Rate Limiting
• Graph API Rate Limits
• Insights API Best Practices
• Insights Breakdowns
• Async and Batch Requests
• Marketing API Changelog
• v24.0 Release Notes
• Budget Limits
• Dynamic Creative / asset_feed_spec
• Copy Endpoints

SDK and tooling:

• facebook-python-business-sdk
• pipeboard-co/meta-ads-mcp
• mathiaschu/meta-ads-analyzer

Engineering notes:

• Fivetran: How to reduce Facebook Ads API rate limit errors
• Supermetrics: Query optimizations
• Windsor.ai: Meta Ads API Guide
• PPC.land: Meta deprecates legacy APIs for Advantage+