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
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. |
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_descending You 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_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:
- 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:
- 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, 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!
Back to Blog