Facebook Ads - User Tip Sheet

*Note*: this is created 2015-04-30 by marcus.wong@keboola.com

I don’t claim for this to be a good wiki … it’s just what I do and I haven’t had it all figured out yet.

*Note*: this is edited on 2015-10-28 by vokurka@keboola.com

Mainly because of the new version of FB Ads API

*Note*: this is edited on 2015-11-02 by tomas.ferko@keboola.com

Cleaning up the convoluted structure of the document.

*Note*: this is edited on 2016-04-25 by vokurka@keboola.com
Adding notes on upgrading from older API (naming of the endpoints)

Developer & API Documentation

---> http://docs.facebookadsextractor.apiary.io/#introduction/config-table/data

---> https://developers.facebook.com/docs/marketing-apis

---> https://developers.facebook.com/docs/marketing-api/insights/v2.4

Part 1:

  • create new sys bucket -> sys.c-ex-fb-ads

  • create new table with columns within that bucket: “endpoint”,”params”,”dataType”,”dataField”,”recursionParams”,”rowId”

with primary key on “rowId”. (so basically this: sys.c-ex-fb-ads.<<insert client name or configname>>)

  • the user with access to advertising data has to authorise KBC using this link:

https://syrup.keboola.com/ex-fb-ads/oauth?token=<SAPI TOKEN HERE>&config=<config table name here>

                **NOTE**:         the config table name should not include the bucket bucket prefix, so in case your 
                                            config table name is "sys.c-ex-fb-ads.myconfig" the config table name should be only "myconfig"

                **NOTE**:        if you want to limit the token authorisation of the used token you need to create the extractor 
                                            in bucket beforehand, and then create the token with limited permissions to use in the authorisation process. 
                                            the syntax for the name of the bucket is always according to this standard pattern in.c-ex-fb-ads-<config table name>

  • the authorisation process will not work if you don’t register the component first

  • you’ll know you have done it right when you see that the Facebook token and expiry have been added to the attributes of the config table

**NOTE**:            the token expires every 2 months and needs to be regenerated.

                             the orchestrator will fail and the attribute will disappear from the config table if you don't reauthorise.

                            --- NO LONGER TRUE - TOKENS NOW DO NOT EXPIRE ---

to make the config work you will also need the “Ad Account Number” (NOT the business manager id) which your client should be able to provide from https://business.facebook.com 


For API v2.6

"endpoint","params","dataType","dataField","recursionParams","rowId" "act_<ad_account_number>/campaigns","{""fields"":""id,name,account_id""}","campaigns","data","","1" "act_<ad_account_number>/adsets","{""fields"":""id,name""}","adsets","data","","2" "act_<ad_account_number>/ads","{""fields"":""id,name""}","ads","data","","3" "{3:id}/insights","{""fields"":""ad_id,impressions,actions,clicks,spend"",""date_preset"": ""last_7_days"",""time_increment"":""1""}","ads_insights","data","","4"

Old API version




"{2:id}/insights","{""fields"":""impressions,clicks,spend,actions"",""action_breakdowns"":""action_type,action_video_type"",""date_preset"": ""last_7_days"",""time_increment"":""1""}","adgroups_insights","data","","3"


  • replace the account numbers on each row in the endpoint to the corresponding account number that you are trying to extract from

  • on the first run, the extractor will create a new metadata bucket and table, do not delete it

  • endpoints - pretty self-explanatory

  • fields - you can add there all the fields you want to download from API, list of fields can be found in documentation

  • date_preset - describes for how long in history you want to download data

  • time_increment - segmentation by days - can 1 to 90 - 1 means 1 row per day (**NOTE** THIS does not mean incremental writing into SAPI!) 

  • by using {2:id} you can actually use parameters downloaded in other queries. The integer is ID of the row (rowID), then there is a field name. This means that for every id from query on row 2 download data.

  • action_breakdowns - list of parameters on which you want to do group by

  • **NOTE** FB Ads API apparently has a "feature" of not sending empty data. So in case you have no records for a given day it means there is nothing to show. I know, it sucks.

  • For upgrading from older API to the new, you have to rename some of the endpoints. Very simple help is like this:

    • Change /adcampaign_groups to /campaigns
    • Change /adcampaigns to /adsets
    • Change /adgroups to /ads
    • In the write path, change campaign_group_status, campaign_status, adgroup_status tostatus

    Source: https://developers.facebook.com/docs/apps/changelog

  • Also, do not forget to change field names as described here: https://developers.facebook.com/docs/marketing-api/reference/v2.5_rename/v2.5 

That is basically how you extract the data.  Hope it works out for you.