Skip to main content

Setup Meta/Facebook source

Updated

Pulls Facebook ad insights, page and post data, videos, Instagram insights and content monetization earnings by signing in with a Facebook user attached to your business account.

Setup at a glance

  1. 01KleeneAdd Source
  2. 02FacebookSSO & Auth
  3. 03KleeneComplete Setup
  4. Connected
  • Connector type API
  • Auth method Sign in with Facebook + Account ID

Before you start

  • A Facebook user which has been added to the business account you want to retrieve data from
  • Optional: the Ad Account ID you want to pull from — copy it from the drop-down next to Campaigns in Ads Manager

Connect Facebook to Kleene

  1. Add the source in Kleene

    1. In the Kleene app, go to Add a source.
    2. Scroll down or search for Facebook.
    3. Click Connect.

  2. Sign in at Facebook

    1. Click Sign in with Facebook and log in as a user attached to the business account.

  3. Finish the setup in Kleene

    • Account IDLeave blank to pull all Ad Accounts

    The new source now appears on the Sources screen.

Good to know

Authentication expires — re-authenticate with reset

Facebook authentication can expire for a number of reasons, including the user's password changing or the user revoking permissions. If this happens you'll receive a 401 authorization error and will have to re-authenticate the source by clicking edit → reset.

Before you extract — Facebook limits and report notes

This guide covers source setup only. When you move on to creating extracts, these are the connector-specific things to know.

Connector capabilities

Backfill Yes — 3 months by default, up to 18 months (not recommended)
Incremental Yes — supported on all reports indicated with an incremental key. Custom backfill is not supported
API reliability Unreliable — will occasionally throw 500 errors

Available reports

24 reports covering ad insights at Campaign, Ad Set and Ad level, Pages and Posts, Page and Post Insights, Videos, Video and Page custom labels, six Instagram reports, and Content Monetization Earnings. See the full Facebook report list on docs.kleene.ai for every report with its incremental and primary keys.

Extract notes

  • For the Page Video Ad Breaks report you can supply an individual page ID, or a comma-separated list of IDs for multiple pages. If you don't include IDs, the extract runs through all pages linked to the Facebook account you authenticated with. A page ID can be taken from the destination table of the Pages Insights report, or found in Facebook: click your profile photo → See all profiles → select the Page → click the Page's name in the left menu → About → Page transparency → See all → Go to Ad Library, then read the number after view_all_page_id= in the address bar.

Limits and gotchas

You will get duplicates for the last 7 days

Because data within the Facebook platform is always updating, the connector re-fetches all data from at least the last 7 days to keep your warehouse current. This causes duplicate entries for some days. You'll need to deduplicate, keeping the rows with the most recent _KLEENE_EXTRACT_DATE.

Async errors on large volumes

The Facebook API sometimes returns an async error (Async request for … failed). Kleene handles these by retrying 5 times. If the error still occurs, please retry the extract. It's more likely with larger data volumes.

error_subcode 99 — re-run the extract

The Instagram Graph API and Facebook Graph API occasionally fail and throw {:error_subcode 99, :code 1, :message "An unknown error occurred"}, which you'll see in the Kleene app logs on a failure. Please re-run your extract.

Limitations

  • Page Media View Insights — the underlying API endpoint behaves unstably and often results in consecutive errors on longer backfills. Adjust the backfill to 12 months or shorter using Advanced Options.
  • Instagram Media Insights — media posted on your account before its conversion from a personal to a business account will not appear in report results and is excluded.
  • Rate limits and retrying — running many long backfill reports simultaneously may hit API rate limits. Kleene catches these errors and automatically sleeps and retries the affected requests, which may lead to longer overall run times.

Vendor reference: Facebook Ad Insights API docs

Related to

Powered by Zendesk