Back to Blog

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

NodesEdgesData entity
/{ad-account-user-id}/adaccountsAll Ad accounts associated with the user.
/accountsAll pages and places that someone is an admin of.
/promotable_eventsAll promotable events or promotable page events that belong to pages the user is an admin of.
/act_{ad-account-id}/adsetsData about Ads that share the same budget, schedule, bid, and targeting.
/adsData for an Ad, such as creative elements and measurement information.
/adcreativesAd’s appearance and content.
/adimagesLibrary of images to use in Ad creatives.
/advideosLibrary of videos to use in Ad creatives.
/campaignsData about campaigns’ objective and Ad sets.
/customaudiencesCustom audiences
/usersList of people associated with the account.
/insightsInsights on your advertising performance.
/{ad-id}/adcreativesAd’s appearance and content.
/insightsInsights on your advertising performance.
/leadsAny leads associated with a Lead Ad.
/previewsGenerate ad previews from an existing ad.
/{ad-campaign-id}/adsetsAds that share the same budget, schedule, bid, and targeting.
/adsData necessary for an Ad.
/insightsInsights on your advertising performance.
/{ad-set-id}/adsData necessary for an Ad.
/adcreativesAd’s content and appearance.
/activitiesLog of actions taken on the Ad set.
/insightsInsights on your advertising performance.
/{ad-creative-id}/previewsGenerate 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: 

ParameterDescriptionAvailable values
action_attribution_windowsThe 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_breakdownsThe 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_breakdownsSimilar 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_timeDetermines 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
  • breakdownsThe 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_limitDefines the maximum number of product ids to be returned for each ad when breakdown by product_id.<integer>
    date_presetRepresents 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_rangeA single time range object. This param is ignored if time_ranges is provided.since:YYYY-MM-DD,until:YYYY-MM-DD
    time_incrementAllows 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_rangesArray 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_summaryDetermines whether to return a summary.
  • false – default value
  • true
  • export_columnsOptional parameter to select fields on the exporting report file.<string>
    export_formatDefines the format of the exporting report file. 
  • xls
  • csv
  • export_nameDefines the file name of the exporting report.<string>
    fieldsDefines the fields to be retrieved. Default behavior is to return impressions and spend.<string>
    filteringFilters on the report data. This parameter is an array of filter objects.<string>
    levelRepresents the level of result.
  • ad
  • adset
  • campaign
  • account
  • sortDefines 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
  • summaryIncludes a summary section with the fields listed in this param.<string>
    use_account_attribution_settingEnabling this parameter will return your ads results using the attribution settings defined for the ad account.
  • false – default value
  • true
  • use_unified_attribution_settingEnabling 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 metricsIn-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.

    1 my apps

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

    2 business app type

    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.  
    3 create app

    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.

    4 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.
    5 parameters to get token

    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.
    6 open access token tool
    • Click Extend Access Token.
    7 extend acess token
    • Welcome a long-lived access token that will expire in about 3 months.
    8 extended access token
    • 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:

    9 facebook insights api example

    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.
    10 facebook ads as source
    • Connect your Facebook Ads account. Click Continue
    11 connect facebook ads account
    • 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.
    12 select data and accounts
    • 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.
    13 group data by
    • Select fields to include in your Facebook Ads report. Click Continue.
    14 columns

    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.

    15 destination

    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.

    8 airtable export schedule

    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.

    16 view results

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

    17 results fb ads insights

    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:

    18 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
    19 json url
    • 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:

    19 url query parameters ads library example

    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:

    20 ads library results 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 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

    Comments are closed.

    Access your data
    in a simple format for free!

    Start Free