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
| Nodes | Edges | Data entity |
|---|---|---|
/{ad-account-user-id} | /adaccounts | All Ad accounts associated with the user. |
/accounts | All pages and places that someone is an admin of. | |
/promotable_events | All promotable events or promotable page events that belong to pages the user is an admin of. | |
/act_{ad-account-id} | /adsets | Data about Ads that share the same budget, schedule, bid, and targeting. |
/ads | Data for an Ad, such as creative elements and measurement information. | |
/adcreatives | Ad’s appearance and content. | |
/adimages | Library of images to use in Ad creatives. | |
/advideos | Library of videos to use in Ad creatives. | |
/campaigns | Data about campaigns’ objective and Ad sets. | |
/customaudiences | Custom audiences | |
/users | List of people associated with the account. | |
/insights | Insights on your advertising performance. | |
/{ad-id} | /adcreatives | Ad’s appearance and content. |
/insights | Insights on your advertising performance. | |
/leads | Any leads associated with a Lead Ad. | |
/previews | Generate ad previews from an existing ad. | |
/{ad-campaign-id} | /adsets | Ads that share the same budget, schedule, bid, and targeting. |
/ads | Data necessary for an Ad. | |
/insights | Insights on your advertising performance. | |
/{ad-set-id} | /ads | Data necessary for an Ad. |
/adcreatives | Ad’s content and appearance. | |
/activities | Log of actions taken on the Ad set. | |
/insights | Insights on your advertising performance. | |
/{ad-creative-id} | /previews | Generate ad previews from the existing Ad creative object. |
Learn more about how to use API for data analytics.
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:
| Parameter | Description | Available values |
|---|---|---|
action_attribution_windows | The attribution window for the actions. For example, with 7d_click, you’ll return all actions that happened 7 days after the click on the ad. | |
action_breakdowns | The option to break down action results. Supports more than one breakdowns. | |
summary_action_breakdowns | Similar to action_breakdowns, but applies to summary. | |
action_report_time | Determines the report time of action stats. For example, if a person saw the ad on Aug, 3 but converted on Aug 4, you’ll get different results: action_report_time=impression will return a conversion on Aug, 3.action_report_time=conversion will return a conversion on Aug, 4. | |
breakdowns | The option to break down the result. For more than one breakdown, only certain combinations are available. | |
product_id_limit | Defines the maximum number of product ids to be returned for each ad when breakdown by product_id. | <integer> |
date_preset | Represents a relative time range. This field is ignored if time_range or time_ranges is specified. | |
time_range | A single time range object. This param is ignored if time_ranges is provided. | since:YYYY-MM-DD,until:YYYY-MM-DD |
time_increment | Allows you to choose to have results for smaller time slices after you pick a reporting period by using time_range or date_preset. If time_increment=monthly is used, you will get one result set for each calendar month in the given period. This param is ignored if time_ranges is specified. | |
time_ranges | Array of time range objects. Time ranges can overlap, for example to return cumulative insights. Each time range will have one result set. If time_ranges is specified, date_preset, time_range and time_increment are ignored. | since:YYYY-MM-DD,until:YYYY-MM-DD |
default_summary | Determines whether to return a summary. | |
export_columns | Optional parameter to select fields on the exporting report file. | <string> |
export_format | Defines the format of the exporting report file. | |
export_name | Defines the file name of the exporting report. | <string> |
fields | Defines the fields to be retrieved. Default behavior is to return impressions and spend. | <string> |
filtering | Filters on the report data. This parameter is an array of filter objects. | <string> |
level | Represents the level of result. | |
sort | Defines the field to sort the result by and direction of sorting (ascending is by default). For example, sort=reach_descendingYou can also sort by action type using the following syntax: actions:<action_type>_<direction>For example, sort=actions:link_click_ascending | |
summary | Includes a summary section with the fields listed in this param. | <string> |
use_account_attribution_setting | Enabling this parameter will return your ads results using the attribution settings defined for the ad account. | |
use_unified_attribution_setting | Enabling this parameter will return your ads results using unified attribution settings defined at ad set level. The parameter use_account_attribution_setting will be ignored. |
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:
| Estimated metrics | In-development metrics |
|---|---|
|
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_readpermission (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.
Facebook Ads Insights API – How to use it without coding
Coupler.io is a reporting automation platform that lets you turn raw data from business apps into meaningful reports. You can use it to load Facebook Ads insights to spreadsheets, data warehouses, and BI tools.
Try it yourself right away. In the form below, select the desired destination app and click Proceed. You’ll be offered to create a Coupler.io account for free without any credit card required.
After that, complete the following steps.
1. Collect Facebook Ads data
Authorize your Facebook Ads account, then specify the Ad accounts from where you’d like to load data and Reports and insights as the Report type. Then, select the Report period and the Metrics and dimensions to include in your report.
2. Organize data
At the next step, you’ll see a preview of your Facebook Ads data and will be able to make it analysis-ready using the following options:
- Edit, rearrange, hide, or add columns.
- Filter and sort data in the preferred order.
- Create new columns with custom formulas.
- Combine data from different Facebook Ads accounts or apps.
3. Load data and schedule refresh
Once your Facebook Ads report is ready, follow the in-app instructions to load it to the chosen destination.
After that, enable the Automatic data refresh and configure the schedule you want.
Where can you load insights from Facebook Ads?
Coupler.io supports the following destinations:
- Spreadsheet apps: Google Sheets and Microsoft Excel.
- Data warehouses: BigQuery, PostgreSQL, and Redshift.
- Business intelligence (BI) tools: Tableau, Looker Studio, Power BI, and Qlik Sense.
- Other destinations: You can export Facebook Ads as an online JSON file or load insights to Monday.com.
Reporting templates based on Facebook Ads API
If your next step is visualizing Facebook Ads data in the destinations, these ready-made templates will make it easier. You can build different Facebook reports like ad performance tracking, ecommerce conversions, and lead breakdowns in minutes by following a few simple steps. This saves you time and effort by eliminating the need to build reports from scratch. Check out a few Facebook Ads dashboard examples available as free templates.
Facebook Ads dashboard
The Facebook Ads dashboard provides a clear view of your campaign performance by showing key metrics like impressions, ad spend, link clicks, and CTR in one place. It pulls data from different campaigns and displays it in one place. It shows metrics like CPM, CPC, and frequency, so you can quickly see how your ads are performing.
You can use this dashboard to compare ad sets, track spending over time, and find areas where your campaigns might be falling short. It also highlights changes in performance, like a drop in impressions or an increase in CPC, making it easier to adjust your strategy.
This template is also available in Looker Studio, Power BI, and Google Sheets. To use it, connect your Facebook Ads account with Coupler.io, select the required data fields, and the dashboard will be populated automatically.
Facebook Ads dashboard template in Looker Studio
Effectively manage and optimize your Facebook advertising campaigns, reaching your target audience in a data-driven way.
Facebook Ads dashboard template in Power BI
Get a detailed overview of your advertising campaigns’ performance using a dynamic Power BI dashboard template equipped with a no-code Facebook Ads connector
Facebook Ads dashboard template in Google Sheets
Monitor the performance of your advertising campaigns in Facebook and identify top assets to spend your budget wisely.
Facebook Ads performance for mobile apps dashboard
The Facebook Ads performance for mobile apps dashboard tracks mobile app campaigns by comparing ad spend with app installs and in-app purchases. It highlights ROAS to show how well campaigns generate revenue.
This dashboard maps the user journey from impressions to purchases so that you can spot where users drop off. It monitors costs like CPI, CPC, and CPP to show where your budget is going. You can also identify which campaigns perform best and which need adjustments.
Instead of manually analyzing ad data, this dashboard organizes all campaign metrics in one place. It shows performance trends clearly and tracks how spending affects user acquisition and revenue. You can see how ad spend drives installs, conversions, and purchase behavior with ease.
To create this dashboard with your own data, connect your Facebook Ads account to Looker Studio using Coupler.io, select your mobile app campaigns, and set up a data refresh schedule.
Facebook Ads ecommerce performance dashboard
The Facebook Ads ecommerce performance dashboard tracks key metrics like add-to-cart actions, checkouts, and purchases. It shows ROAS and other important numbers to help you understand how your campaigns generate revenue.
The dashboard outlines the conversion funnel, starting from impressions to purchases. You can identify campaigns with high clicks but low purchases and compare their performance across ad sets. It also highlights how changes in ad spend affect purchases and tracks costs like CPC and cost per purchase.
It breaks down purchase trends across different customer segments to see which audiences contribute the most to revenue. You can analyze patterns in user behavior to adjust targeting and improve campaign performance.
To get started, connect your Facebook Ads account to Looker Studio using Coupler.io. Select your ecommerce campaigns, and the dashboard will populate with real-time data.
Facebook Ads leads breakdown dashboard
The Facebook Ads leads breakdown dashboard tracks the performance of Facebook lead ads. It focuses on key metrics like impressions, clicks, leads, cost per lead, and lead value. The dashboard also displays the journey from impressions to clicks and leads through a performance funnel.
It provides a clear breakdown of lead volume and value, making it easier to compare campaign performance. You can also analyze audience and location data to see which segments drive the most leads. With these insights, adjusting targeting and optimizing ad spend becomes more effective. The dashboard also provides filters to focus on specific date ranges, demographics, or locations to analyze your lead ads in detail.
To build this dashboard with your data, connect your Facebook Ads account to Looker Studio through Coupler.io. After setup, the dashboard updates automatically to keep metrics up to date.
Facebook Ads purchases breakdown dashboard
The Facebook Ads purchases breakdown dashboard helps marketers analyze how ad spend converts into actual purchases. It displays key metrics like clicks, CPC, and purchase events in a user-friendly format.
You can track spending, spot purchase trends, and compare campaign performance across different audiences or locations. The dashboard allows you to analyze the conversion journey by breaking it into stages, from impressions to purchases and highlights key patterns. The demographic and geographic data show which audiences or regions drive revenue.
By connecting to your Facebook Ads account using Coupler.io, you can build your own self-updating dashboard from this Looker Studio template.
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:
- Confirm your identity and location
- Create a Facebook app in your developer account
- 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, select the needed destination app in the form below and click Proceed. It will create a new JSON importer to connect the API.
- 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.
The next steps, transformation and destination, are the same as for the Facebook Ads integration that we introduced above. Once you’ve set them up, run the importer. Here is what the results may look like in Google Sheets:
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 connectors by Coupler.io. 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 Facebook Ads reporting tool. Good luck with your data!
Automate Facebook data exports with Coupler.io
Get started for free