Facebook Ads Source

Facebook is one of the most efficient ways to advertise online. Take your company’s analysis to the next level by adding Facebook Ads as a Source to Segment.

This is an Object Cloud Source which can export data from its third party tool and import it directly into your Segment warehouse.

This document was last updated on July 6, 2018. If you notice any gaps, outdated information or simply want to leave some feedback to help us improve our documentation, please let us know!

Getting Started

  1. From your workspace’s /sources page, click add source.

  2. Choose Facebook Ads.

  3. Give the source a nickname. The nickname is a label used in the Segment interface, and Segment creates a related schema name which you query against in your warehouse. The nickname can be whatever you like, but we recommend sticking to something that reflects the source itself, like Facebook Ads or Facebook Ads Prod.

  4. Click Create And Continue then Connect to OAuth into Facebook.

  5. Select which accounts you would like to sync (you may change this selection later).

  6. Click Finish.


If your Facebook user has read permissions to Facebook Ads account’s data, you should be able to use your account for the Source.



Facebook Ads has a sync component, which means we’ll make requests to their API on your behalf on a 3 hour interval to pull the latest data into Segment. In the initial sync, we’ll grab all the Facebook objects (and their corresponding properties) according to the Collections table below. The objects will be written into a separate schema, corresponding to the source instance’s schema name you designated upon creation. For example, if you went with fb_ads, the ads collection will be accessible at fb_ads.ads in SQL.

Our sync component uses an upsert API, so the data in your warehouse loaded via sync will reflect the latest state of the corresponding resource in Facebook Ads. For example, if budget from 0 to 100 between syncs, on its next sync that tickets status will be 100.

The source syncs and warehouse syncs are independent processes. Source runs pull your data into the Segment Hub, and warehouse runs flush that data to your warehouse. Sources will sync with Segment every 3 hours. Depending on your Warehouses plan, we will push the Source data to your warehouse on the interval associated with your billing plan.


Collections are the groupings of resources we pull from your source. In your warehouse, each collection gets its own table.

ad_accountsobjectAn ad account is an account used to manage ads on Facebook
ad_setsobjectAn ad set is a group of ads that share the same daily or lifetime budget, schedule, bid type, bid info, and targeting data
adsobjectAn ad object contains the data necessary to visually display an ad and associate it with a corresponding ad set.
campaignsobjectA campaign is a grouping of ad sets which are organized by the same business objective.
insightsobjectInsights contain performance statistics for an ad broken down by day.

Collection Properties

Below are tables outlining the properties included in the collections listed above.

Ad Accounts

Property NameDescription
idAd Account ID.
balanceBill amount due.
nameName of the account. If the account name is not set, the name of the first admin visible to the user will be returned.
partner_idThe ID of a Facebook Page or Facebook App.
spend_capThe maximum that can be spent by this account after which campaigns will be paused. A value of 0 signifies no spending-cap and setting a new spend cap only applies to spend AFTER the time at which you set it. Value specified in basic unit of the currency, e.g. cents for USD.

Ad Sets

Property NameDescription
idAd set ID.
account_idAd Account ID.
campaign_idCampaign ID.
configured_statusThe status set at the ad set level. It can be different from the effective status due to its parent campaign.
daily_budgetThe daily budget of the set defined in your account currency.
effective_statusThe effective status of the ad set, which can be either its own status or caused by its parent campaign.
end_timeEnd time, in UTC UNIX timestamp.
nameName of ad set.


Property NameDescription
idThe ID of this ad.
adset_idID of the ad set that contains the ad.
account_idThe ID of the ad account that this ad belongs to.
bid_amountBid amount for this ad which will be used in auction instead of the ad set bid_amount, if specified.
bid_typeBid type.
campaign_idID of the ad campaign that contains this ad.
nameName of the ad.
statusThe configured status of the ad.
url_parametersURL parameters.
utm_sourceUTM source.
utm_mediumUTM medium.
utm_campaignUTM campaign.
utm_termUTM term.
utm_contentUTM content.


Property NameDescription
idCampaign’s ID.
account_idID of the ad account that owns this campaign.
buying_typeBuying type.
effective_statusThe effective status of this campaign.
nameCampaign’s name.
spend_capA spend cap for the campaign, such that it will not spend more than this cap. Expressed as integer value of the subunit in your currency.
start_timeStart time.
stop_timeStop time.


Property NameDescription
idSegment internal ID.
ad_idThe unique ID of the ad you’re viewing in reporting.
clicksThe number of clicks on your ads.
date_startThe start date for your data.
date_stopThe end date for your data.
deeplink_clicksDeprecated by Facebook. Aliased to click_to_app_deeplink.
website_clicksDeprecated by Facebook. Aliased to click_to_website
frequencyThe average number of times each person saw your ad.
impressionsThe number of times your ads were on screen.
inline_post_engagementsThe total number of actions that people take involving your ads.
social_clicksDeprecated by Facebook. The number of clicks (all) when your ad was displayed with social information.
social_impressionsDeprecated by Facebook. The number of times your ads were viewed when displayed with social information.
social_spendThe total amount you’ve spent so far for your ads showed with social information.
spendThe estimated total amount of money you’ve spent on your campaign, ad set or ad during its schedule.
unique_clicksThe number of people who performed a click (all). This metric is estimated.
unique_impressionsDeprecated in favor of reach . You can continue to query unique_impressions for this metric, but zero-values will now be null.
unique_social_clicksDeprecated by Facebook. The number of people who performed a click (all) on your ad when it was displayed with social information.
reachThe number of people who saw your ads at least once. Reach is different from impressions, which may include multiple views of your ads by the same people.
call_to_action_clicksDeprecated by Facebook. The number of times people clicked the call-to-action button on your ad.

Adding Destinations

Currently, Warehouses are the only supported destination for object-cloud sources.

Questions? Need help? Contact us!
Can we improve this doc?
Email us: docs-feedback@segment.com!