In this tutorial, you will learn the basics of the Facebook Marketing API: getting performance data via the Insights API and making changes to your adsets via the Graph API.
Feel free to follow along via video (sorry for the slight audio/video mismatch) or go at your own pace with the text-only version below.
We designed this tutorial to make it fun for you to play around with Facebook Marketing API. It consists of 11 different exercises through which you will learn the basics. Then, go through the tutorial step by step. Sometimes we introduce a new topic through a specific use case.
I. Create a Facebook App
II. Get an access token for your Facebook App
III. Working with the Marketing API: Objects, edges
IV. Your first Facebook Marketing API Call
V. Get your Facebook ad accounts
VI. Retrieve Facebook performance data (called "insights")
VII. Retrieve campaigns and adsets of an ad account
VIII. Retrieve and change budgets
IX. Retrieve ads of an adset
X. Get an ad's creative and more
XI. Retrieve information with a browser instead of the Graph API Explorer
Please note that this is not an official Marketing API tutorial. For more details on the Marketing API, refer to the official documentation.
First, to access Facebook programmatically via the Marketing API, you need to create a Facebook (or should we call it "Meta") app. This will allow you to generate an access token that is your authentication when calling the API. We'll tackle that right after getting our app. After that, there are just a few simple steps, and all you require is an existing Facebook account.
1. Go to developers.facebook.com
2. Log into your Facebook account
3. Go to My Apps —> Create app. Choose Business as an app type.
4. Give it a name and contact email.
5. Click on Create App
6. In the list of products provided by Facebook, choose Marketing API and click on Set Up. After you click, Marketing API will appear on the left side of your app menu.
An access token identifies the user (like an email and password) used to authenticate your API calls. That way, Facebook knows whether you have access to the ad account for which you are requesting data. A user access token is used for precisely this purpose, to prove that you are authorized to look at any data and make any changes you'd usually be able to do via Ads Manager.
There are two ways to get your user access token.
via Developer Tools (quick and easy):
1. Click on Tools under the Marketing API on the left side. Choose Access Token Tool.
2. Select the permissions that you need:
ads_management (make changes in selected ad accounts)
ads_read(readout ads data)
read_insights(read out performance insights)
2. Click on Get Token
via Graph API Explorer (more granular permission management):
1. Go to Tools —> Graph API Explorer
2. Choose the right app on the right side
3. Choose Get User Token on the section User or Page
4. You will be redirected to do the standard Facebook login flow.
5. Add the permissions that you will need. In our case, we choose
6. Click on Generate Access Token.
Note: Either of these methods will generate a short-lived access token that expires fairly soon. You can follow the official documentation to get a long-lived access token that lasts up to 60 days, or if you know what you are doing, request a System User access token that doesn't expire.
You will need to understand a few other core concepts to navigate the Facebook Marketing and Graph API successfully.
The goal of this introduction is not just for you to follow along but to understand how you might retrieve other important information via the API or make changes to existing ad objects.
Every element or item with an ID in Facebook Business Manager is an object.
- Ad Accounts
We can request more information about an object by calling its ID and adding any fields or connections (called "edges") we want to learn more about. For example, for an adset, we can ask for: (parent) campaign, (child) ads, targeting, start date, daily budget, etc.
Each ID is unique - so there's no way Facebook would mistake an adset id for something else.
We access each object through its unique identifier by simply calling it with the base URL and a
Edges are "connections" to other related objects. For example, an ad account has a campaigns edge, meaning that we can request the ids of all campaigns located in the ad account. The opposite is true as well - any campaign has an ad account edge as well as adsets and ads edge. In Facebook Marketing API, the edges are called with a
/ symbol, for example:
Parameters define what data Facebook returns to you (when reading out data) or how and what attributes you are changing (when you create or update an existing object). For our purpose, these are the most important parameters when accessing the Marketing API:
- limit: limits the number of objects pulled when requesting multiple items via an edge
The above request returns five ads belonging to the specified adset. But since we didn't set any fields, Facebook will only return the ads' ids.
- fields: define what attributes of the specified object are returned
We can, of course, also combine these with an
Now let's get you to make your first API call in the Graph API Explorer.
1. Choose GET request. We use a GET request whenever we want to retrieve information from the Facebook Marketing API. If we wanted to change or create something new, we would use a POST request.
2. Then, add the following path:
3. Click Submit. You should see your name and Facebook user id.
Congratulations on your first API call.
On the left side, you can choose additional data fields to get more information about your Facebook id.
4. On the left side, choose the
adaccounts field or add
adaccounts in the URL path and submit. If the run is successful, you will see all of the accounts you have access to.
Note that we have now added an edge as a field to our request. This can be useful when we want to get information about ourselves AND the ad accounts we have access to. In most cases you would simply use
me/adaccountsto get the desired ad accounts and add any further information the way we learned above:
5. Facebook Marketing API, by default, uses pagination - it will give you only 25 elements back. If you want more, include the following limit parameter.
6. If you want to add the name of the accounts, add the name field:
As you can see, where are also able to add limits and fields on fields in a nested structure.
1. Choose an account id, which you know had some ad spend in the last 90 days.
2. All account ids have act_ in front of the actual account id. To fetch your account, make sure to add it.
3. Click on docs, and scroll until Facebook Marketing API. Next, click Reference on the left side. In Reference, you will find all relevant information about possible edges and parameters available for any object.
4. Click on Ad Account on the left side. You will see which type of information is available for which object. You will see all possible calls for that object on the right-hand side.
5. Go back to Graph Explorer. Input the following path:
6. In return, you will get the standard information which includes
spend, impressions, account id, and
dates in the last 30 days.
7. To preset the date range, use the following parameter:
We can use
maximum, and many more.
8. Then, to add another parameter, use the ampersand
&. For example, if you want to break down the data by some timeframe, add a time increment using the following structure:
Valid values are any numbers from
monthly. By default, it is set to
all_days - so there is no time breakdown.
9. To get more than 25 insight objects, use the limit parameter (max 5000):
Your entire path should look as follows:
1. To access all campaign objects on your ad account via Facebook Marketing API, input the following path:
2. To add a parameter, add a
? and the names of the desired
fields - we'll start with the
After hitting "Submit" you should see a list of campaigns. Per default, Facebook will show the last 25 created campaigns here.
3. Click on one of the campaign ids. This should enter the campaign id into the path. You are on now accessing data on a campaign level.
4. Ask for the campaign
Note: Facebook will only return any field or attribute when it exists. A daily budget only exists when the budget is set on a campaign level and is a daily, not lifetime budget type.
5. To access the performance data, add the insights edge. You can choose any fields and set the parameters you want to. For example, we will be retrieving spend, impression, CPM, and CPC over the campaign's entire lifetime. To get conversion events data, add the
1. First, let's get all adsets belonging to our specified campaign, using the
2. Click on one of the adsets from the previous step or input a new adset id.
3. To retrieve an adset's daily budget, use
Note that budget or bid information always shows as cents (if your account's currency is set to EUR/USD) or pence (for GBP accounts)!
4. Add some of the additional suggested fields you are interested in to retrieve the adset data.
5. Change GET to POST.
POST requests are used when we want to create a new or make changes to an existing ad object.
6. To change the budget, use the desired value in cents by adding it after the
daily_budget parameter. You still have to specify which fields Facebook should return on its response.
If successful, Facebook will return the newly updated daily budget.
Congrats! This is the first change that you have made via the Facebook Ads API!
1. Get ads of your adset by calling the
2. Add name and id fields to understand better which ads you retrieve.
3. Click on an ad id. Ask for
insights to get performance data for the specified ad:
4. To retrieve the URL or any other user-facing parts of your ad, retrieve the
adcreatives edge. Ad creatives is the edge that allows you to read any creative data inside of the ads.
Note: You can achieve the same by adding that creative field:
5. Click on the ad creative id. Each ad has exactly one ad creative. Next, add
asset_feed_spec to retrieve data from body texts, titles, and descriptions.
Note that depending on the ad format and whether you're using dynamic elements, the creative's information may be stored in different places.
asset_feed_spec may not exist for your particular ad. If so, follow the next steps.
call_to_action_type to read out the CTA type used. Of course, to the end-user, this is always localized.
7. Now add
object_story_spec field. This is an important field when retrieving creative information. Inside
object_story_spec, you will find the
instagram_actor_id. Depending on your ad format, you may also find
1. Every GET request we do with a Graph API Explorer can also be made with a simple browser. You have to add the first bit yourself:
3. Put your ads_read access token at the end of the link with
4. You will now see the JSON response right in your browser.
And that concludes the Practical Introduction to the Facebook Marketing API.
If you are looking for more video tutorials, head to our Youtube page.
If you want to dive right into building cool automations with the Facebook Marketing API without worrying about managing your access token and dealing with code yourself, check out the Kitchn.io product demo or get in touch at https://www.kitchn.io/start