Facebook Ads

This extractor allows to extract ads data from Facebook using Facebook Marketing API. The data involve Ad Account ads including adsets, campaigns and also ads insights.

Create and Initiate New Configuration

Find Facebook Ads under the Extractors section. Create a new configuration and name it. It can be renamed any time.

Screenshot - Create configuration

Authorize a Facebook account under which you have access to an Ad Account you want to extract. The authorization process asks for public_profile,ads_management permissions. To irrecoverably dissmiss the authorized account, then go to your Facebook apps tab(under settings) and remove Keboola Ads Extractor from the list.

Screenshot - Authorize configuration

Select Ad Accounts to extract from the list of fetched Ad Accounts associated with the authorized account.

Screenshot - Select Facebook Pages

Create New Query

Create a new query that specifies data to extract. You can choose from a preconfigured template and all necessary fields will fill up automatically.

Screenshot - New Query

The query is basically a description of a request that the extractor will send to the Facebook Marketing API. All options except name represent parameters of the Facebook Marketing API request, so with a good knowledge of the API it should be easy to create a query.

Name

Name option describes the query and is used to prefix tables name resulting from the query. One query can produce multiple tables. If a table name produced by the query matches the query name or its substring trimmed after the last occurrence of underscore then the output table name will not be prefixed and the query name will be used instead. E.g. if the query name is ads_insights and the produced table name is insights then the output table name will be ads_insights. If the query name is foo and the produced table name is ads then the output table name will be foo_ads.

Endpoint

Endpoint options describes significant URL part of the request made to Facebook Marketing API. The absolute URL is in form https://graph.facebook.com/<api_version>/<endpoint>. For more info see the list of supported Facebook Marketing API endpoints. Typical example could be ads. If left empty, then it refers to the data of the Facebook authorized account itself.

Fields

Fields option is required to precisely describe the data returned from the endpoint. Typically it is a comma-separated list of fields but also can be used to parametrize the fields and nest more endpoints into it. If you look at a ads endpoint it returns all created ads. Each ad can contain fields such as id, name, adset_id. The fields parameter in such case is id,name,adset_id.

  • Fields/Endpoint Nesting Ads can contain recommendations and these can be included in fields as well: id,name,adset_id,recommendations{title,code,message}. The comma separated list in between the curly brackets {} specifies fields of the “nested” field/endpoint ad-recommendation. This way more endpoints can be nested and basically there is no limit of nesting level.

  • Fields Parameterization Each field can be parameterized by a dot followed by the modifier name and value in brackets. Typical parameter could be since, until, limit or any other parameters or modifiers that the particular endpoint offers such as date_preset for ads insights endpoint. Example of parameterized fields: insights.action_breakdowns(action_type).date_preset(last_month).time_increment(1){ad_id,impressions,reach,actions,clicks,spend}

Ad Accounts

This option specifies Ad Accounts that the query will be applied to. Accounts can be chosen from a list of selected ad accounts after authorization. There is All Ad Accounts option meaning that the query will be applied to all selected ad accounts as well as None meaning that query will be applied to no Ad account. This can be useful to extract data about the authorized account itself. The Accounts option is represented by the Facebook Marketing API parameter ids that is comma separated list of ad accounts IDs.

Since and Until (Advanced tab)

Since and Until options represent the corresponding Facebook Marketing API request parameters and specify date range that will be applied to time based data retrieved by the endpoint. E.g. if the endpoint is ads then all ads created within the since-until range will be retrieved. Since or Until parameter is parsed via strtotime function and can be specified:

  • absolutely – as a unix timestamp or in yyyy-mm-dd format,
  • relatively – e.g. 14 days ago or last month.

For consistent results, specify both since and until parameters. Also, it is recommended that the time range does not exceed 6 months.

Limit (Advanced Tab)

The limit option represents the Facebook Marketing API request parameter limit and it is the maximum number of objects that may be returned in a single page of the request. Default is 25 and maximum is 100. It is useful when Facebook Marketing Api returns an error saying there are too many data requested. In such case, you can lower the limit and retry the query run.

Output Data Description

Output data represent tree where each node is an array of objects returned from Facebook Graph API. The tree is transformed into one or more CSV tables. Each row of a table represents one object. Each table has primary key auto-detected during extraction and so table data is imported incrementally. Columns of the output tables represent fields from the Fields query option. Moreover each table will always contain the following basic set of columns:

  • ex\_account\_id – Id of the ad account corresponding to the object stored in the row.
  • fb\_graph\_node – Describes the “vertical position” of the object in the resulting tree. E.g. for ads it will be page_ads, for ads insights it will be page_ads_insights.
  • parent_id – Refers to id column of a parent object represented by some other row and/or table. For example if the row is representing a insight object then its parent is ad and so parent_id is the id of the ad. The parent object type can be also determined from fb_graph_node column as a substring from the beginning until the last occurrence of underscore, e.g. page_ads_insights -> page_ads. The top parent id is an ad account id.

Facebook API Version

You can set version of Facebook Marketing API that will be applied for all request made to Facebook Markegint API by facebook extractor. Read more about Marketing API versions here.