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 — asset_feed_spec limits, immutable creatives](docs/04-creatives-and-dco.md) ### Ops 5. [Deprecations Timeline 2026 — what breaks when](docs/05-deprecations-2026.md) 6. [Error Codes Cheatsheet — code → fix mapping](docs/06-error-codes.md) 7. [Pitfalls — the 15 things official docs won't warn you about](docs/07-pitfalls.md) 8. [Cross-account Operations — the page/creative/audience transfer problem](docs/08-cross-account-operations.md) ### Ecosystem & strategy 9. [Ecosystem & Tools — SDK vs MCP vs ETL, which to use when](docs/09-ecosystem-and-tools.md) 10. [Cookbook — 10 end-to-end recipes](docs/10-cookbook.md) 11. [The Breakdown Effect — why your "bad" segments are actually good](docs/11-breakdown-effect.md) 12. [Related Resources — the curated ecosystem (50+ repos categorized)](docs/12-related-resources.md) 13. [Conversions API (CAPI) — recover the 30-40% lost to browser tracking](docs/13-conversions-api.md) ### Code - [`examples/backoff_and_monitor.py`](examples/backoff_and_monitor.py) — read rate-limit headers, back off proactively - [`examples/multi_id_fetch.py`](examples/multi_id_fetch.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/backoff_and_monitor.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. ```bash # 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](https://developers.facebook.com/docs/marketing-api/overview/rate-limiting/) - [Graph API Rate Limits](https://developers.facebook.com/docs/graph-api/overview/rate-limiting/) - [Insights API Best Practices](https://developers.facebook.com/docs/marketing-api/insights/best-practices/) - [Insights Breakdowns](https://developers.facebook.com/docs/marketing-api/insights/breakdowns/) - [Async and Batch Requests](https://developers.facebook.com/docs/marketing-api/asyncrequests/) - [Marketing API Changelog](https://developers.facebook.com/docs/marketing-api/marketing-api-changelog/versions/) - [v24.0 Release Notes](https://developers.facebook.com/blog/post/2025/10/08/introducing-graph-api-v24-and-marketing-api-v24/) - [Budget Limits](https://developers.facebook.com/docs/marketing-api/adset/budget-limits/) - [Dynamic Creative / asset_feed_spec](https://developers.facebook.com/docs/marketing-api/ad-creative/asset-feed-spec/) - [Copy Endpoints](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign/copies/) **SDK and tooling**: - [facebook-python-business-sdk](https://github.com/facebook/facebook-python-business-sdk) - [pipeboard-co/meta-ads-mcp](https://github.com/pipeboard-co/meta-ads-mcp) - [mathiaschu/meta-ads-analyzer](https://github.com/mathiaschu/meta-ads-analyzer) **Engineering notes**: - [Fivetran: How to reduce Facebook Ads API rate limit errors](https://fivetran.com/docs/connectors/applications/facebook-ads/troubleshooting/rate-limit) - [Supermetrics: Query optimizations](https://docs.supermetrics.com/docs/facebook-ads-query-optimizations-to-reduce-errors) - [Windsor.ai: Meta Ads API Guide](https://windsor.ai/guide-to-facebook-meta-ads-api/) - [PPC.land: Meta deprecates legacy APIs for Advantage+](https://ppc.land/meta-deprecates-legacy-campaign-apis-for-advantage-structure/)