The ad data for Facebook Ads is represented and accessed through several views exposed by the driver. See Data Model for more details on these views. The way that Facebook Ads works means that there are a couple of general rules, presented below, for querying these views. For any view, its page in the Data Model section will also go over any special details related to querying it.

Specifying a Target

For many views related to ads, a target must be specified when querying them in order to identify the specific ad or account object for which data should be retrieved. For example, when querying the Ads view, the Target column must be specificed as a criteria pointing to a specific ad account:

SELECT * FROM Ads WHERE Target = 'act_123456'

A Target can also be specified dynamically in a query:

SELECT * FROM Ads WHERE Target IN (SELECT ID FROM AdAccounts)

If no Target is specified in a query, and the Target connection property is not set, the AccountID connection property will be used to determine the default target for ads queries. If none of these are set, the first account id returned from Facebook Ads will be used.

Insights Views

Analytics, peformance, and reporting data for ads is accessed through the AdInsights and AdInsightsActions views. Queries to these views will require a Target as covered in the previous section, but also support more detailed query syntax for their reporting functionality.

Time Ranges

When trying to pull ad reporting and analytics, use DateStart and DateEnd or DatePreset in your query to control the time range of ads data.

SELECT DateStart, DateEnd, AdAccountId, Spend, Impressions FROM AdInsights WHERE Target = 'act_123456' AND DateStart >= '01/01/2015' AND DateEnd <= '03/31/2015'

SELECT DateStart, DateEnd, AdAccountId, Spend, Impressions FROM AdInsights WHERE Target = 'act_123456' AND DatePreset='last_90d' AND TimeIncrement='monthly'

When specifying a time range for ads data, use TimeIncrement to control the time span of ad data summarized in each result row. For example, if TimeIncrement is set to "monthly", each result row will correspond to a monthly roll-up of ad data.

Ad levels

The Target specified for a query will control what ad account ad data is retrieved for. Use Level to control what level of ad object results are reported at. Level can be set to ad, adset, campaign, or account.

Breakdowns

Facebook Ads offers a number of breakdowns for querying your ad insights data. These breakdowns are exposed and can be used through the AdInsights and AdInsightsActions views, such that each row returned for a query will correspond to the reporting data for one combination of the breakdowns specified in the query. The aggregated data returned for a breakdown combo will still be limited by the ad object target and ad object level specified in the query.

Facebook Ads does enforce restrictions on what breakdowns can be selected together, so by default the driver also enforces similar restrictions on breakdowns in queries supplied to it. If desired, this internal enforcement can be disabled through the IgnoreValidationException property. Setting this property to "True" bypasses internal enforcement of breakdown restrictions, and passes any supplied breakdown combination as-is to Facebook.

Please see Data Model for more info on breakdown combos.

Action Collections

The AdInsightsActions view also offers an ActionCollection column, which allows you to specify what sort of actions attributed to your ads you would like to look at.

Action Attributions

The AdInsightsActions view also offers an ActionAttributionWindows column, which allows you to control how Facebook Ads attributes actions to your ad object when it generates its report. ActionAttributionWindows are specified from a list of combinations that define action and time period combinations. For example, the default value for ActionAttributionWindows is "7d_click,1d_view", meaning that relevent actions taken within 7 days of clicking on your ad object or 1 day of viewing it are attributed to and reported on for the ad object.