meta-ads-api-field-guide

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

meta-ads-api-field-guide

(★ 14)

Claude Code + Meta Ads without disasters. A drop-in skill, 3 subagents, and safety hooks for marketers automating Facebook/Instagram campaigns. 13 field guides, 23 production pitfalls solved.

meta-ads-api-field-guide Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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/)

meta-ads-api-field-guide

meta-ads-api-field-guide Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

meta-ads-api-field-guide

meta-ads-api-field-guide Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README