The Meta Marketing API is the programmatic interface to Ads Manager: a set of Graph API endpoints that read and write campaigns, ad sets, ads, creatives, audiences and results. An agency gets access by creating a Meta app, asking for the ads permissions, having the client share the ad account with the agency’s business portfolio, and calling the API with an access token. Access itself is free.
What the API gives you that Ads Manager does not
Ads Manager shows one account at a time, in a view someone has to open. The API returns the same objects as data, which changes what an agency can do with them.
- Reporting on every client account on the same morning, with the same fields and the same date range.
- Results joined to your own data, such as the leads a CRM received per ad ID.
- Alerts that fire without anyone watching a screen: spend pacing, an ad that stopped delivering, a creative whose cost per lead doubled.
- Bulk changes across accounts, applied the same way every time instead of by hand.
The objects are the same ones you know from the interface, and the naming follows the interface: campaign, ad set, ad, creative, custom conversion, audience. What the API adds is a stable structure, versioned endpoints and the ability to ask for exactly one field.
What an agency needs before the first call
| Piece | What it is | Who owns it |
|---|---|---|
| Meta app | the registration that holds the permissions and the token | the agency |
| Business portfolio | the container that holds the app, the system user and the client relationship | the agency, with the client’s portfolio alongside |
| Asset access on the ad account | the client grants the agency’s portfolio access to the ad account | the client |
| Access token | the credential the calls carry, tied to a user or to a system user | the agency |
| Permission | ads_read to read, ads_management to change something | granted per app, reviewed by Meta |
Two of those rows cause most of the trouble. Asset access is granted by the client, so a token that works in your own account returns an error on theirs. And the permission is attached to the app, not to the person who clicked through a login screen.
How to get access, step by step
- Create a Meta app in the App Dashboard for developers and add the Marketing API product to it.
- Create or connect the agency’s business portfolio, then ask the client to add it to their ad account as a partner with the access level you need.
- Generate a token. For a one-off look, a user token from the Graph API Explorer is enough. For a reporting service, create a system user in the agency portfolio and use its token, since it does not depend on one person’s login.
- Request ads_read, and ads_management only if the integration changes campaigns, budgets or creatives. Every extra permission is reviewed and has to be justified.
- Go through App Review and business verification before the integration serves clients at scale. In development mode the app works with a limited set of accounts tied to it, which is enough to build and test.
- Make the first call against the ad account ID, with the
act_prefix, and read a field you can check by hand in Ads Manager.
Meta’s own reference for each endpoint lists the permissions it needs, and that list is the shortest path when an error says the token lacks access.
The permission that does the reporting work
For an agency that reports on client accounts, ads_read is the whole job. It covers the insights edge and the objects behind it: campaigns, ad sets, ads and their spend.
A typical report request asks one account for a level, a set of fields and a date range, and returns the rows in the same shape whatever the account. That is what makes one template work for fifteen clients:
| Request part | What it decides |
|---|---|
level | whether rows are accounts, campaigns, ad sets or ads |
| fields | spend, impressions, clicks and the action types you care about |
| breakdowns | the split you want, such as by ad ID or by placement |
| time range | the reporting window, in the ad account’s time zone |
Two practical notes. Ask for the ad level when the report has to say which creative and which landing page produced the leads, because a campaign row is an average of ads that behave in opposite ways. And on large accounts, use an asynchronous job instead of waiting on one long request, then download the result when Meta has finished building it.
The limits that show up in production
- Rate limits apply per app and per ad account, and they are not raised by paying. Batch several reads into one request, cache what does not change every minute, and keep the polling frequency of a dashboard well below what a human would notice.
- Tokens expire or get revoked when the person behind them leaves. A system user token is the fix, and it belongs in a secret store rather than in a script.
- Versions are retired. Pin the version in the request path, read the changelog before a deadline, and keep the version number in one place in the code.
- Numbers follow Meta’s rules. The API reports what Meta attributed under the ad set’s attribution setting, in the account’s time zone. Spend is the number that matches an invoice, so read spend here and read leads from the system that received them.
- Some fields are simply absent. Custom conversions return no unique action counts through the insights edge, which is another reason to count leads in your own data.
What to build on top of it
The reporting work does not change because the data arrives through an endpoint. A client report still answers four questions in order: what was spent, what was received, which creative and which landing page produced it, and what changes next. The API makes the join between spend and lead possible at ad level, and the structure that holds that report together is set out in Facebook ads reporting for clients.
One more reason to care about the join: an agency that can show spend per ad next to the leads that ad produced is answering the question clients actually ask, which is whether the cheap leads were worth calling. That is a different report from an export of thirty columns.
DropCPL closes the other half of the loop: spend per ad arrives from the Meta Ads API, and every lead is counted on the landing page that received it, tied to the ad, the creative and the landing page, with the standard Lead event sent back through the Conversions API. The other questions agencies ask about client accounts, from pricing to proving results, are collected in running Meta ads for clients.
If your team already sends events to Meta itself, the server half is worth reading next: how to set up the Meta Conversions API for lead generation.