Version 0.3.1


Checkout theΒ Facebook Ad Insights API docs for more information

Set up

To set up the source you just need a Facebook username and password for a user which has been added to the business account from which you would like to retrieve data. You will also need your account ID.

To find your account ID:

  1. Go to you Ads Manager Account
  2. Head to the drop down at the top of the screen next to the Campaigns title
  3. Copy the Ad Account ID for the account you wish to pull data from.

If you don't supply and Ad Account ID, the extracts will by default get data from all Ad Accounts.



Facebook authentication can expire for a number of reasons, including the following:

  • The user’s password changes
  • The user revokes permissions

If this occurs you will receive a 401 authorization error and you will have to re-authenticate the source by clicking edit -> reset.


Backfillβœ…3 months by default, up to 18 months (not recommended)
Incrementalβœ…Incremental is supported on all reports indicated with an incremental key below.
Custom backfill❌
API reliability🟠Unreliable. Will occasionally throw 500 errors.


Async Errors

The Facebook API sometimes returns an Async error, see below. We handle these errors by retrying 5 times. if this error still occurs then please retry the extract.

This error is more likely to occur with larger data volumes.

  "source-type": "facebook-oauth-jumper",
  "message": "Async request for 23849864184600169 failed"

Reports detail

⬇️ ReportπŸ”‘ Incremental keyπŸ”‘ Primary keyπŸ“„ Link to API endpoint
PagesN/AIDGet Pages
Page Insightsend_timeIDGet Page Insights
Page Video Ad Breaksend_timeIDVideo Ad Breaks
Page Custom LabelsN/AIDGet Page Custom Labels
Post Insightsend_timeIDPost Insights
Post Video Ad Breaksend_timeIDVideo Ad Breaks
Video Custom LabelsN/AIDVideo Custom Labels
Instagram Business DiscoveryN/AIDBusiness Discovery
Instagram Media InsightsN/AIDMedia Insights
Instagram Business Account InsightsN/AIDBusiness Accout Insights
Instagram Business Account Insights (demographic metrics)N/AIDBusiness Accout Insights
Instagram Business Account Insights (new metrics)N/AIDBusiness Accout Insights
Instagram Business Account Insights (custom)N/AIDBusiness Accout Insights




As data within the Facebook platform is always updating, the connector will fetch again all data from at least the last 7 days, to ensure you have the most up-to-date data in your warehouse.

This will cause duplicate entries for some days, and you will need to deduplicate, whilst keeping the rows that have the most recent _KLEENE_EXTRACT_DATE


Page Video Ad Breaks report

Here in the Extract setup you have the option to give an individual page id for which to extract data or a comma separated list of ids for multiple pages.

In case you do not include ids, the extract will run through all the pages linked to the facebook account you authenticated with.

In case you want to specify ids: a page ID can either be taken from the destination table of the pages insights report or:

New Pages experience

  1. To find your Page ID:
  2. Log in to Facebook, then click your profile photo in the top right.
  3. Click See all profiles, then select the Page that you want to switch into.
  4. Click your Page's name in the left menu to go to it.
  5. Click the About tab below your Page's cover photo, then click Page transparency.
  6. Click See all, then click Go to Ad Library.
  7. Find view_all_page_id= in the address bar of your browser. Your Page ID is the number immediately following this.

This is your Facebook Page ID.


Instagram Media Insights

Media posted on your account prior to its conversion from a personal to a business account will not appear in report results and will be excluded


error_subcode 99 (need to re-run report)

Instagram Graph API and Facebook Graph API occasionally will fail and throw an error "{:error_subcode 99, :code 1, :message \"An unknown error occurred\"}" which you will see in the Kleene app logs for your extract on a failure.

Please re-run your extract.