Meta Ads API review: what the Marketing API docs do not warn you about

This is an operator review, not a docs summary. I have run campaigns through this API for years, and most of what follows is the part the documentation does not warn you about: which objects refuse to change after publish, which reporting field quietly double counts, and which token expires without telling you. Verdict first, then the detail.

Verdict: RUNNING. In one line: paid social under full agent control.

What is the Meta Ads API?

The Meta Ads API is the programmatic interface to Meta advertising, officially the Marketing API, served over the Graph API. It exposes the same objects as Ads Manager: campaigns, ad sets, ads, creatives, audiences, budgets, and reporting. Anything you can click, you can call.

The object model is a hierarchy: a campaign holds the objective, an ad set holds targeting, budget, schedule, and the conversion event, and an ad pairs an ad set with a creative. Reporting comes from the insights edge, which returns spend, delivery, and results for any level of that tree.

Access runs through a Business Manager app and an access token. The API is versioned, so you pin a version and migrate when Meta deprecates it. Nothing here is exotic. What makes it demanding is the rules underneath.

Why the Meta Ads API is RUNNING in my stack

Because it does the whole job, and because the alternative does not scale past a few campaigns.

Full scope is the headline. Not a reporting window with a write API bolted on. I create campaigns, build ad sets, upload creatives, build audiences, move budgets, and pull numbers, all from the same surface. Work that is a long afternoon of clicking is a short script, and the script is repeatable.

The second reason is control over the reporting. Ads Manager decides which numbers to show you and how to round them. The API hands you the raw breakdown, so I can join it against my own tracking and see where the two disagree. When a platform number and my own number diverge, I want to know by how much, not be told a single blended figure.

The third reason is the guardrail I can build into it. Every campaign my automation creates is created paused. Spend gets activated by a person, deliberately, after looking at it. An API that can spend money is only safe if the approval step is structural rather than a habit.

What the docs do not warn you about

Everything below cost me either budget or hours before it turned into a rule.

Creatives are immutable

You can edit a creative's name, status, and ad labels. Everything else is frozen. Change the copy, the image, the call to action, or the URL tags and you get error subcode 1815573, which reads like a permissions problem and is not. The fix is to create a new creative and point the ad at it. The Ads Manager edit button does exactly this underneath, which is why the change feels seamless in the UI and fails in your script. Build automation around recreate and swap from day one.

Two more fields freeze after publish

A campaign objective cannot change once the campaign has an ad set (1885073). An ad set conversion event cannot change once the ad set is published. Both mean the same thing in practice: a pivot is a new object, not an edit. Decide the objective and the conversion event before you create, because changing your mind later means rebuilding the branch and cleaning up the old one.

Structural edits reset the learning phase

Adding new ads to a live ad set counts as a significant edit, and Meta restarts learning: conversion counters go back to zero and the delivery model relearns who to show the ads to. I did this to a set of ad sets that were days into learning and lost all of that signal at once, then paid an inflated cost per result for several days while they relearned. Pausing does not undo it. The safe pattern is a new ad set for new creatives, which also gives you a clean comparison.

The reporting field you pick changes the answer

This one is the most expensive to get wrong, because nothing errors. The actions field collapses every custom pixel event into one bucket, so a pixel with two custom events reports a single number that is the sum of both. I once read that number as one event and was off by nearly half. The conversions field breaks results out per event name, which is what Ads Manager shows in its results column.

The same trap has a second half: the API returns one conversion under several action types at once, including omni prefixed variants. They describe the same event counted with different attribution, so adding them together inflates your result. Pick one type and stay with it. Before you report a number to anyone, check it against Ads Manager. OpenAI built the same trap into ChatGPT Ads, one Conversions column that sums every event until you add the per-event columns, which I go through in ChatGPT Ads.

Token failure is silent

Page and user tokens expire. When one does, campaigns keep running, ads keep delivering, and your server side calls start failing with an OAuth error nobody is watching. I lost most of a day of conversion data that way, and the first visible symptom was a gap between platform numbers and my own tracking, not an alert. Use a System User token from a Business Manager app for anything unattended. Do not guess what a token is allowed to do either: the debug_token endpoint tells you the scopes and the account level tasks, and it has corrected my assumptions more than once.

App review status blocks writes you already had

An app in development mode can read fine and then refuse to create creatives (1885183) once the platform tightens a policy. That is exactly how it arrived for me: the same call worked one week and failed the next, with no change on my side. Whatever your automation depends on, know which app it runs under and what review state that app is in.

Errors mislead before they help

A missing access token in a POST body comes back as code 100, subcode 33, described as the object not existing or you lacking permission. You will go hunting for a permissions problem that is not there. Once you learn to read them, though, Meta's errors are precise and point at the exact field, which is more than many ad platforms manage.

Fields get deprecated under live objects

Copying a working object and posting it back is the obvious way to clone, and it breaks quietly. Older creatives still return fields in GET that new POST requests now reject, so a clone of a live object fails while the original keeps serving. Read responses also contain read only fields that cannot be posted back. Whitelist what you send instead of echoing what you received.

Automated rules outlive the campaign

Rules created in Ads Manager on a weekly schedule keep firing every week. Turning off ads does not stop them. I had a stopped campaign restart itself and spend real money because a rule from the previous week flipped the ads back on. Stopping a campaign means the campaign, the ad set, the ads, and every rule attached to them.

Verify on the account, not from memory

For any campaign type you have not run before, do a dry run: create the object paused, GET it back to see whether Meta stored exactly what you sent or quietly normalized it, then delete it. This takes minutes and it is the difference between knowing and assuming. Two other small things in the same spirit: read the account currency from the account rather than assuming a symbol, and check whether the audience automation flags force targeting ranges wider than you asked for.

Who the Meta Marketing API is best for

Automating Meta campaigns end to end. The API earns its keep when campaign operations are repetitive and structured: nightly reporting joined against your own data, bulk creation across many ad sets, budget moves on a schedule, or an agent that proposes changes for a human to approve. The more accounts and objects you run, the more the manual path collapses.

When to skip the API and stay in Ads Manager

You run one campaign and edit it by hand. One campaign that you adjust by hand every few days does not need any of this. Ads Manager is genuinely good at that, and the API adds an object model, a token to maintain, and version migrations. Reach for it when the clicking becomes the bottleneck, not before.

How much does the Meta Ads API cost?

The API is free. You pay for ad spend, not for calls. The real cost is engineering time, and most of it goes on the rules above rather than on the endpoints themselves.

How to get started with the Meta Marketing API

1. Create an app in Business Manager and a System User with access to the ad account you will manage.
2. Confirm what the token can actually do with the debug_token endpoint before writing any logic around it.
3. Read before you write. Pull the insights for a live campaign and reconcile the numbers with Ads Manager until they agree.
4. Do your first write as a dry run: create something paused, read it back, delete it.
5. Only then automate, and keep creation paused by default so spend stays a human decision.

Where the Meta Ads API fits with agents and MCP

In my stack the API is the hands and Claude Code is the operator: it reads the numbers, drafts the structure, and writes the calls, while I keep the approval. Meta also ships an official MCP endpoint for ads, which fits the pattern described in MCP servers and is useful for analysis and diagnostics from a chat window. Note that it authenticates as a human in a browser and rejects System User tokens, so it complements an unattended pipeline rather than replacing it.

For anything that is not exposed by the API, browser automation with Playwright covers the gap, but I treat that as a last resort. An API call that Meta supports will outlive a selector that Meta redesigns.

If you run paid search as well, the Google Ads API is the other half of this job, and it is a different animal: harder to get into because of the developer token approval, more predictable once you are inside. Expect two separate integrations rather than one abstraction covering both.

Meta Ads API FAQ