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)
CONVERSIONSandLINK_CLICKSobjectives are deprecated — new campaigns needOUTCOME_*- 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
PreToolUsehook) - 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
- Rate Limits — the formula, the headers, the scoring
- Insights API — unique metrics, breakdowns, attribution windows
- Budgets & Learning Phase — the 4/hour rule and what resets learning
- Creatives & DCO — asset_feed_spec limits, immutable creatives
Ops
- Deprecations Timeline 2026 — what breaks when
- Error Codes Cheatsheet — code → fix mapping
- Pitfalls — the 15 things official docs won't warn you about
- Cross-account Operations — the page/creative/audience transfer problem
Ecosystem & strategy
- Ecosystem & Tools — SDK vs MCP vs ETL, which to use when
- Cookbook — 10 end-to-end recipes
- The Breakdown Effect — why your "bad" segments are actually good
- Related Resources — the curated ecosystem (50+ repos categorized)
- Conversions API (CAPI) — recover the 30-40% lost to browser tracking
Code
examples/backoff_and_monitor.py— read rate-limit headers, back off proactivelyexamples/multi_id_fetch.py— fetch N objects in one callexamples/async_insights.py— thereport_run_idpolling workflowexamples/batch_jsonpath.py— chain batch requests with JSONPath references
Checklists
The 10 most useful non-obvious facts
- Your hourly rate limit is a formula:
300 + 40 × active_ads(Standard access). 50 active ads → 2,300 calls/hour. Details - There are three parallel limits — call count, CPU time, total time. Any at 100% = throttle. Details
- You can read
X-Business-Use-Case-Usagefrom every response to back off before you hit 100%. Most code doesn't. Example code - Budget can be changed max 4×/hour per ad set. Error subcode
1487225blocks for an hour. Details - Unique metrics (reach, frequency) + date range > 28 days = high failure rate. Query them separately with short windows. Details
- Changing budget by > 20% resets the learning phase. So does swapping creative, audience, or bid strategy. Duplicate the ad set instead. Details
- Creatives are immutable and shareable — one
creative_id→ N ads across campaigns. Don't re-upload, reference. Details - ASC/AAC legacy campaigns are dying in Q1 2026 (v25.0). Migrate via
migrate_to_advantage_plus. Timeline - Cursor auto-pagination in the official Python SDK silently triggers rate limits at ~25 pages. Use manual pagination. Details
- The segment with worst breakdown CPA is probably your BEST spend. It's called the Breakdown Effect.
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-adsskill — 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 conceptsmeta-ads-campaign-architect— plans campaigns, stops at user approval gate
enforce-paused.pyhook — blocks any API create withstatus != PAUSEDat the tool-call layerlog-api-write.shhook — 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.mdfor insights queries). Before any write, check07-pitfalls.mdand follow the RSIV workflow defined in themeta-adsskill."
How this guide is organized
Each doc page follows the same pattern:
- The rule — what Meta enforces
- The numbers — concrete limits, not vibes
- The gotcha — what breaks in production
- 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:
Engineering notes: