Facebook Ads API Guide for Your Cutting-Edge Reporting

Facebook Ads API allows you to create and manage your ads programmatically without the Ads Manager UI. Another benefit is that you can use API to retrieve data about your Facebook ads to make custom reports, build dashboards and analyze the performance of your ads in different ways. 

This is exactly what we’re going to focus on in this article – how you can do reporting and analytics with Facebook Ads Insights APIs. The best part is that you can get Facebook Ads reporting data without any coding! 

Intro to the Facebook Ads API

Underneath the Facebook API there lies the Graph API. It’s an HTTP-based API to push data to and pull data from Facebook…or should we say Meta? 😏

The Graph API works with any language that has an HTTP library, such as cURL and urllib. Almost all requests are passed to; 

https://graph.facebook.com

The Graph API is composed of nodes, edges, and fields.

• Nodes are individual objects with a unique ID. They include Pages, Users, Campaigns, Ads, and so on. For example,

https://graph.facebook.com/{user-ID}

• Edges or endpoints are collections of objects on a single object (node). For example, the node Ad Campaign has the Insights edge.

https://graph.facebook.com/{api-version}/{ad-campaign-ID}/insights

• Fields are node properties used to get data about a single object or each object in a collection. For example,

https://graph.facebook.com/{user-ID}?fields=id,name,email

Facebook Ads manager API 

In order to programmatically advertise on Facebook, you’ll need the Marketing API (this is the name for what you may call the Facebook Ads Manager API). It’s a collection of specific Graph API endpoints (nodes + edges). 

Both Graph API and Marketing API calls require an access token to be passed as a parameter in each API call. Standard Access ads_read and ads_management permissions are sufficient for managing your ad account. To manage other ad accounts, you’ll need Advanced Access permissions. 

Marketing API rate limiting logic

You can make a limited number of requests to the Marketing API. The limitation is based on the call count – the number of calls during a rolling one-hour window. Here is how you can calculate those:

Calls within one hour = 60 + 400 * Number of Active ads – 0.001 * User Errors

• Number of Active ads – the number of ads currently running per ad account.
• User Errors – the number of errors received when calling the API.

Note: To get a higher rate limit, you can apply for the Ads Management Standard Access feature.

Nodes and edges for the Facebook Ads Reporting API

What is the Facebook Insights API?

Facebook Insights API is an edge or endpoint dedicated to reporting within the Marketing API. It allows you to retrieve performance data from Facebook marketing campaigns, i.e. get metrics and statistics about ads, ad sets, and campaigns. Here is the Insights API cURL syntax:

https://graph.facebook.com/{api_version}/{ads_object}/insights

The Insights API is available as an edge on the following objects (nodes):

• /act_{ad-account-id}/insights
• /{ad-id}/insights
• /{ad-campaign-id}/insights
• /{ad-set-id}/insights

Facebook Ads Insights Graph API parameters

You can customize your queries to the Facebook reporting API using the following parameters: 

Facebook Ads Insights API fields

More than 70 fields are available with FB Ads Insights API. If you don’t need all of them for your report, ensure to use the fields parameter, which allows you to specify the exact field to return. For example, 

fields=account_currency,ad_id,ad_name,clicks,cost_per_conversion

You can learn the full list of available fields in the Facebook Marketing API documentation.

Facebook API Insights metrics

Some of the fields you can export using the Insights API are estimated or in-development metrics. 

• Estimated metrics are derived through statistical sampling or modeling, rather than a straight count. They can provide directional insights for outcomes that are difficult to calculate precisely.
• In-development metrics are the metrics that are under testing. 

Here are the metrics that you can get:

Facebook API Ads management

Okay, so let’s retrieve some analytics from the Facebook Ads reporting API. You can do this using a command-line tool or a programming language, such as Python. For this, you’ll need to get an access token first. 

As we mentioned above, each API call must contain an access token passed as a parameter. To get one, you’ll need to create a Facebook Business App.

Create a Facebook App

Log in to your Facebook account. Go to https://developers.facebook.com/ and select My Apps.

Click Create App and select Business app type. Click Next in the bottom right corner.

In the open window, fill out the following fields:

• Display name – enter the name you like. In your app name, you can’t use trademarks or brand elements including FB, Face, Book, Insta, Gram, and Rift, or any confusingly similar terms.
• App Contact Email – specify the contact email address
• Business Account – optionally you can select your business account from the drop-down list.  

Click Create App and complete the security check.

The app is now created! You can now get an access token for the Facebook Ads API.

Generate an Access Token

Go to Tools => Graph API Explorer.

Select the following parameters:

• Facebook App – choose your created app.
• User or Page – choose Get User Access Token
• Add a Permission – add ads_read permission (you’ll find it in Events Groups Pages) and other permissions you may need.

Click Generate Access Token to link your app to Facebook and obtain the API token. By default, the access token only lasts for one hour, but you can increase the expiration time to about 3 months.

How to extend the Facebook API access token

• Click on the blue icon located next to the token. Then click Open in Access Token Tool.

• Click Extend Access Token.

• Welcome a long-lived access token that will expire in about 3 months.

• Click Debug => This will get you back to the Access Token Debugger where you can copy your access token.

What’s next? Now you can send requests to the Facebook Ads Insights API to retrieve the data you need. Let’s now look at how this works.

Facebook Ads Insights API example

As an example, we’ll get the statistics of an ads campaign for the last year. And here is a list of fields we will extract:

• account_id
• account_name
• campaign_id
• campaign_name
• account_currency
• reach
• impressions
• clicks
• cpc
• spend

Here is a cURL that will let us get the required data from the Facebook Ads API:

https://graph.facebook.com/v12.0/23849295425920086/insights?date_preset=last_year&fields=account_id,account_name,campaign_id,campaign_name,account_currency,reach,impressions,clicks,cpc,spend&access_token={access_token_string}

This is how the result looks in the Postman app that we used:

Python Facebook Ads API

Naturally, you can send requests to the API use code, for example written in Python. For this, you’ll need to install facebook-sdk and import the important libraries — urllib3, facebook, and requests. And here is how the same request will look if we use Python to retrieve ads insights data:

from facebook_business.objects import AdCampaign

campaign = AdCampaign('23849295425920086')
access_token = 'your_access_token'

params = {
    'date_preset': 'last_year',
}
fields = [
    'account_id',
    'account_name',
    'campaign_id',
    'campaign_name',
    'account_currency',
    'reach',
    'impressions',
    'clicks',
    'cpc',
    'spend'
]

insights = campaign.get_insights(params=params)
print insights

Can I get stats about dynamic ads with Facebook Ads Insights Rest API?

Facebook dynamic ads driven by ML algorithms automatically deliver relevant offerings to users based on their interests, intent, and actions. With Marketing API, you can create and deliver ads for your products. To get insights on your dynamic ads performance, you’ll need the Ads Insights API as described above.

Also what if I tell you that you can export data from Facebook Ads Insights API to your spreadsheet without literally any code line? No need to create a Facebook app to get a token – just a few clicks and you can create your report and share it with stakeholders. Moreover, you will be able to automate exports on a custom schedule! Let me show you how this can be done.

Facebook Ads Insights API – How to use it without coding

We will use Coupler.io to load Facebook Ads insights to a spreadsheet app. Coupler.io is a solution for exporting data from multiple sources, including Facebook Ads, to Google Sheets, Excel, or BigQuery. The ELT flow is very simple.

Facebook Ads integration by Coupler.io allows you to export different stats about your ads and automate exports on a custom schedule, for example, every hour.

Sign up to Coupler.io with your Google or Microsoft account. Click Add new importer, name it as you wish, and complete the following steps:

Set up source

• Select Facebook Ads as a source application. Click Continue.

• Connect your Facebook Ads account. Click Continue. 

• Select data entity to export from Facebook Ads: Insights, Ad sets, Campaigns, Ads, or Ad accounts. Also select one or several Ad accounts from where you want to extract data. Click Continue.

• Select a Facebook Ads object to group data by: Account, Campaign, Ad set or Ad. Specify the From and To dates. Optionally you can also split data by periods. Then click Continue.

• Select fields to include in your Facebook Ads report. Click Continue.

Optionally you can apply a custom Ad Rule filter using the Graph API syntax. After that, you can Jump to Destination Settings.

Set up destination

• Select a destination app and connect your account based on the chosen app. You can use the following destinations:
  • Facebook Ads to Google Sheets
  • Facebook Ads to Excel
  • Facebook Ads to BigQuery
• If you selected Google Sheets, or Excel, you’ll need to select a spreadsheet, as well as the sheet to import Facebook Ads data to. For BigQuery, you’ll need to enter the name of the dataset and table where to load data.
• Optionally you can change the first cell for your data and the import mode. Read the Coupler.io documentation for more details.

Here is how the destination setup looks for Facebook Ads to Google Sheets.

Note: Check out more about the ready to use integrations:

– Facebook Ads to Excel 

– Facebook Ads to BigQuery

You can Save and Run the Facebook Ads integration right away. However, if you want to automate exports, then you need to complete another step.

Set up schedule

Toggle on Automatic data refresh and configure the schedule you want.

Eventually, you can save and run the integration to load your Facebook Ads data. After the successful import, you can check out the results in your destination by clicking the View Results button.

Here is how the Facebook Ads Insights look in Google Sheets:

Did you enjoy it? Then try out Coupler.io for free!

Bonus: Facebook Ads Library API

The Facebook Ads Library API is a separate interface that you can use to search and export data for all active and inactive ads about social issues, elections or politics. To use it, you’ll need to complete three steps:

1. Confirm your identity and location
2. Create a Facebook app in your developer account
3. Get an access token

We’ve already explained steps 2 and 3 above, whereas step 1 requires you to submit your government-issued ID, such as passport, driver license, national ID card, etc. Go to Facebook.com/ID and follow the instructions. It usually takes up to 2 days to complete the ID confirmation. Eventually, you’ll get this confirmation:

Now you should have access to the Ads Library API. To work with it, we’ll use Coupler.io again, but create an API integration this time. For this, add a new importer and complete the following setup:

Set up source

• Select JSON as the source application. Then click Continue.
• In the JSON URL field, enter the following API URL and click Continue:

https://graph.facebook.com/v12.0/ads_archive

• In the URL query parameters field, you need to specify two required parameters:

access_token: {your-access-token}
ad_reached_countries: {iso-county-code}

Here is an example of the URL query parameters:

The optional parameters that will help you make your query more refined include:

• limit: {integer} – The default value is 25 rows per request. The maximum row limit is 2,000.
• media_type: {value} – Search for ads based on whether they contain a specific type of media: ALL, IMAGE, MEME, VIDEO, NONE.
• search_terms: {string} – Search for a specific term in your query. 

Check out the full list of the parameters for your ad search query here.

The next steps, destination and schedule, are the same as for the Facebook Ads integration that we introduced above. Once you’ve set them up, click Save and Run and view the results:

Facebook Ads Insights API vs. Coupler.io Facebook Ads importer

In the article, we introduced how you can work with the Facebook Ads reporting API using CLI tools, coding, and no-code solution. Ultimately, it’s up to you to decide which method works best for your purposes. Nevertheless, keep in mind how much time you can spend on building custom integrations or how much time you can save using the ready-to-use one. Good luck with your data!