Running Meta ads for clients

What is the Meta Marketing API and how does an agency get access?

The Marketing API is the programmatic route to Ads Manager data. An agency needs a Meta app, ads_read access to the client ad account and a server token.

Published

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

PieceWhat it isWho owns it
Meta appthe registration that holds the permissions and the tokenthe agency
Business portfoliothe container that holds the app, the system user and the client relationshipthe agency, with the client’s portfolio alongside
Asset access on the ad accountthe client grants the agency’s portfolio access to the ad accountthe client
Access tokenthe credential the calls carry, tied to a user or to a system userthe agency
Permissionads_read to read, ads_management to change somethinggranted 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

  1. Create a Meta app in the App Dashboard for developers and add the Marketing API product to it.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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 partWhat it decides
levelwhether rows are accounts, campaigns, ad sets or ads
fieldsspend, impressions, clicks and the action types you care about
breakdownsthe split you want, such as by ad ID or by placement
time rangethe 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.

Questions on this topic

All questions on this topic →

FAQ

Is the Meta Marketing API free?+

Yes. Meta does not charge for API calls, so the only cost is your own infrastructure and the ad spend itself. There is no paid tier that lifts rate limits, which is why an efficient request pattern matters more than a budget.

Do I need App Review to read a client ad account?+

You need the permission and the asset access. In development mode an app works with a small set of accounts tied to it, so App Review and business verification are what an agency does before it runs the integration for clients at scale. Ask for the narrowest permission that does the job.

Can the API replace Ads Manager for an agency?+

It replaces the reading, and it can write campaigns, ad sets and ads. It does not replace judgement about creative, offers and follow-up. Most agencies use it for reporting, alerts and bulk changes, while campaign decisions stay with a person.

Why do my API numbers differ from the Ads Manager screenshot?+

Attribution settings, the date range time zone and the level of the request all change the total. Conversions also carry Meta attribution rules, so a lead counted in the API is a lead Meta attributed, not a lead your CRM received. Read spend from the API and leads from your own system.

Ready to find out what
converts, for real?

Free to start.

Start free →