Meta Ads Api Field Guide

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](docs/01-rate-limits.md)
2. [Insights API — unique metrics, breakdowns, attribution windows](docs/02-insights-api.md)
3. [Budgets & Learning Phase — the 4/hour rule and what resets learning](docs/03-budgets-and-learning-phase.md)
4. [Creatives & DCO — assetfeedspec limits, immutable creatives](docs/04-creatives-and-dco.md)

Ops

1. [Deprecations Timeline 2026 — what breaks when](docs/05-deprecations-2026.md)
2. [Error Codes Cheatsheet — code → fix mapping](docs/06-error-codes.md)
3. [Pitfalls — the 15 things official docs won't warn you about](docs/07-pitfalls.md)
4. [Cross-account Operations — the page/creative/audience transfer problem](docs/08-cross-account-operations.md)

Ecosystem & strategy

1. [Ecosystem & Tools — SDK vs MCP vs ETL, which to use when](docs/09-ecosystem-and-tools.md)
2. [Cookbook — 10 end-to-end recipes](docs/10-cookbook.md)
3. [The Breakdown Effect — why your "bad" segments are actually good](docs/11-breakdown-effect.md)
4. [Related Resources — the curated ecosystem (50+ repos categorized)](docs/12-related-resources.md)
5. [Conversions API (CAPI) — recover the 30-40% lost to browser tracking](docs/13-conversions-api.md)

Code

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

Checklists

• [Pre-campaign creation (v24-compliant)](checklists/pre-campaign-v24.md)
• [Mass operations (70+ API calls)](checklists/mass-operation-70plus-calls.md)
• [Cross-account copy](checklists/cross-account.md)

---

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](docs/01-rate-limits.md#the-quota-formula)
2. There are three parallel limits — call count, CPU time, total time. Any at 100% = throttle. [Details](docs/01-rate-limits.md#the-three-parallel-limits)
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](examples/backoffandmonitor.py)
4. Budget can be changed max 4×/hour per ad set. Error subcode 1487225 blocks for an hour. [Details](docs/03-budgets-and-learning-phase.md#the-4hour-budget-change-limit)
5. Unique metrics (reach, frequency) + date range > 28 days = high failure rate. Query them separately with short windows. [Details](docs/02-insights-api.md#unique-metrics-are-expensive)
6. Changing budget by > 20% resets the learning phase. So does swapping creative, audience, or bid strategy. Duplicate the ad set instead. [Details](docs/03-budgets-and-learning-phase.md#what-resets-the-learning-phase)
7. Creatives are immutable and shareable — one creative_id → N ads across campaigns. Don't re-upload, reference. [Details](docs/04-creatives-and-dco.md#creatives-are-immutable-and-shareable)
8. ASC/AAC legacy campaigns are dying in Q1 2026 (v25.0). Migrate via migrate_to_advantage_plus. [Timeline](docs/05-deprecations-2026.md)
9. Cursor auto-pagination in the official Python SDK silently triggers rate limits at ~25 pages. Use manual pagination. [Details](docs/07-pitfalls.md#pitfall-10-sdk-cursor-auto-pagination)
10. The segment with worst breakdown CPA is probably your BEST spend. It's called the Breakdown Effect. [Details](docs/11-breakdown-effect.md)

---

Quick decision guide

"I just need to pull data into a warehouse" → Use an ETL vendor (Fivetran / Supermetrics / Funnel / Windsor). See [Ecosystem guide](docs/09-ecosystem-and-tools.md).

"I want to automate campaign creation" → Write raw HTTP with the patterns in this guide. Official SDKs have known pagination issues. See [Pitfall 10](docs/07-pitfalls.md#pitfall-10-sdk-cursor-auto-pagination).

"I want AI to manage ads via chat" → Use an [MCP server](docs/09-ecosystem-and-tools.md#mcp-servers-for-ai-agents-layer-4) (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](docs/06-error-codes.md). If the code isn't there, check [Pitfalls](docs/07-pitfalls.md).

---

🚀 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](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](CONTRIBUTING.md).

---

Changelog

See [CHANGELOG.md](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 / assetfeed_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+

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: YSY-99
• Source: YSY-99/meta-ads-api-field-guide
• License: MIT

Install and usage instructions live in the source repository linked above.