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.	default – default value that means [“7d_click”,”1d_view”] 1d_view 7d_view 28d_view 1d_click 7d_click 28d_click dda skan_view skan_click
action_breakdowns	The option to break down action results. Supports more than one breakdowns.	action_type – default value action_device action_canvas_component_name action_carousel_card_id action_carousel_card_name action_destination action_reaction action_target_idaction_video_sound action_video_type
summary_action_breakdowns	Similar to action_breakdowns, but applies to summary.	action_type – default value action_device action_canvas_component_name action_carousel_card_id action_carousel_card_name action_destination action_reaction action_target_id action_video_sound action_video_type
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.	impression conversion mixed
breakdowns	The option to break down the result. For more than one breakdown, only certain combinations are available.	ad_format_asset age app_id body_asset call_to_action_asset country description_asset gender image_asset impression_device link_url_asset product_id region skan_conversion_id title_asset video_asset dma frequency_value hourly_stats_aggregated_by_advertiser_time_zone hourly_stats_aggregated_by_audience_time_zone place_page_idpublisher_platform platform_position device_platform
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.	last_30d – default value today yesterday this_month last_month this_quarter maximum last_3d last_7d last_14d last_28d last_90d last_week_mon_sun last_week_sun_sat last_quarter last_year this_week_mon_today this_week_sun_today this_year
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.	all_days – default value monthly (number of days from 1 to 90)
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.	false – default value true
export_columns	Optional parameter to select fields on the exporting report file.	<string>
export_format	Defines the format of the exporting report file.	xls csv
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.	ad adset campaign account
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	<string>_ascending <string>_descending
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.	false – default value true
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.	false – default value true

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

conversion_rate_ranking cost_per_unique_action_type cost_per_unique_click cost_per_unique_inline_link_click cost_per_unique_outbound_click engagement_rate_ranking frequency quality_ranking reach relevance_score social_reach spend today_spend total_unique_actions unique_actions unique_clicks unique_ctr unique_inline_link_click_ctr unique_inline_link_clicks unique_link_clicks_ctr unique_outbound_clicks unique_outbound_clicks_ctr unique_social_clicks cpp store_visit_actions cost_per_store_visit_actions total_unique_actions estimated_ad_recallers estimated_ad_recall_rate cost_per_estimated_ad_recallers unique_actions: app_custom_event.fb_mobile_achievement_unlocked app_custom_event.fb_mobile_activate_app app_custom_event.fb_mobile_add_payment_info app_custom_event.fb_mobile_add_to_cart app_custom_event.fb_mobile_add_to_wishlist app_custom_event.fb_mobile_complete_registration app_custom_event.fb_mobile_content_view app_custom_event.fb_mobile_initiated_checkout app_custom_event.fb_mobile_level_achieved app_custom_event.fb_mobile_purchaseapp_custom_event.fb_mobile_rate app_custom_event.fb_mobile_search app_custom_event.fb_mobile_spent_credits app_custom_event.fb_mobile_tutorial_completion link_click landing_page_view cost_per_unique_action_types: link_click landing_page_view

/{business-video-id}/insights/impressions /{business-video-id}/insights/inline_link_clicks /{business-video-id}/insights/video_play_actions /{business-image-id}/impressions /{business-image-id}/inline_link_clicks /{business-image-id}/video_play_actions estimated_ad_recallers estimated_ad_recall_rate cost_per_estimated_ad_recallers landing_page_view cost_per_action_type:landing_page_view store_visits cost_per_store_visit

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.

Note: Facebook Ads integration in Coupler.io is currently in its beta stage. If you’d like to become a beta tester and start exporting Facebook Ads, please reach out to our friendly support team first.

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: Google Sheets, Excel, or BigQuery. Connect your account based on the chosen app.
• 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!

Back to Blog