Facebook Ads Query example configurations
This reference guide provides example configurations that demonstrate how the Facebook Ads Query component can be set up to collect data.
The Facebook API follows a hierarchical structure that mirrors how your accounts, campaigns and ads are structured in Facebook Ads Manager. The data you can collect is structured on four levels. You can only collect data on one level at a time—to collect data on more than one level, you will need to make a separate request for each level. Use the Level parameter to specify the level at which you want to collect data.
- Ad account: Represents an account that owns campaigns, ad sets and ads. Collect data at this level to see high-level performance data across multiple ad campaigns. Example data:
AdAccountId.- Campaign: Represents a single campaign, which can contain multiple ad sets. Collect data at this level to evaluate campaign performance against objectives. Example data:
CampaignName.- Ad set: Represents a single ad set, which can contain multiple ads. Collect data at this level to understand how different factors such as audiences are affecting performance. Example data:
AdSetId.- Ad: A single ad, such as an image or video. Collect data at this level to analyze the performance of individual creatives and CTAs. Example data:
AdName.
- Ad: A single ad, such as an image or video. Collect data at this level to analyze the performance of individual creatives and CTAs. Example data:
- Ad set: Represents a single ad set, which can contain multiple ads. Collect data at this level to understand how different factors such as audiences are affecting performance. Example data:
- Campaign: Represents a single campaign, which can contain multiple ad sets. Collect data at this level to evaluate campaign performance against objectives. Example data:
Note
When collecting data from Facebook Ads, there are some combinations of fields and filters that will not work. The API will still return a 200 OK response, indicating a successful data fetch, but no data will appear in the Data Productivity Cloud. If you experience this issue, try changing your fields and filters to find a combination that works. The combinations of fields and filters used in our examples in this guide were checked and confirmed during our own internal testing. However, the information here may become outdated if the Facebook API or data model changes.
Basic configuration example
The example configuration below shows a possible configuration for the Facebook Ads Query connector in Basic mode.
This configuration collects AdInsightsActions data, such as ad IDs and ad names, at the ad level. The time increment is set to 7 for a weekly breakdown and the date preset is equal to maximum. This date preset will collect all historical data so you may want to select a shorter range, such as last7d, for this filter. For more information, see the Facebook Ads data model or the Meta Insights API documentation.
| Property | Selected option(s) |
|---|---|
| Data Source | AdInsightsActions |
| Data Selection | Action28dClick, Action28dView, ActionAttributionWindows, AdId, AdName, DMA, ActionValue |
| Data Source Filter | Level Is Equal to ad, TimeIncrement Is Equal to 7, DatePreset Is Equal to maximum, ActionAttributionWindows Is Equal to 7d_view,28d_click |
Advanced configuration example
The code block below shows a possible SQL query that can be used to configure the Facebook Ads Query connector in Advanced mode.
This configuration collects AdInsightsActions data at the account level for a specific Facebook ad account, which is specified as the Target. The time increment is set to 30 for a monthly breakdown and the date preset is equal to maximum, which means it will collect all historical data. This configuration collects more data than the Basic configuration example above, and includes identifying information such as adname, performance metrics such as action28dclick, and demographic data such as age.
SELECT "AdAccountName" as "adaccountname",
"CampaignName" as "campaignname",
"AdSetName" as "adsetname",
"AdName" as "adname",
"Action1dClick" as "action1dclick",
"Action1dView" as "action1dview",
"Action7dClick" as "action7dclick",
"Action7dView" as "action7dview",
"Action28dClick" as "action28dclick",
"Action28dView" as "action28dview",
"AdEffectiveStatus" as "adeffectivestatus",
"Target" as "target",
"DateEnd" as "dateend",
"DateStart" as "datestart",
"AdAccountId" as "adaccountid",
"AdSetId" as "adsetid",
"AdId" as "adid",
"CampaignId" as "campaignid",
"Level" as "level",
"TimeIncrement" as "timeincrement",
"ActionType" as "actiontype",
"ActionValue" as "actionvalue",
"ActionCollection" as "actioncollection",
"Age" as "age",
"Gender" as "gender"
FROM "AdInsightsActions"
WHERE "Target" = 'act_1923287384560007'
AND "Level" = 'account'
AND "TimeIncrement" = '30'
AND "ActionAttributionWindows" = '7d_view,28d_click'
AND "ActionCollection" IN ('Actions')
AND "DatePreset" = 'maximum'
Tables and breakdowns
The table below explains which breakdown columns you can choose when collecting data using the AdInsightsActions view. In general, only one breakdown column can be selected. For more information, see the Breakdown columns section of the Facebook Ads data model.
| Table name | Contains breakdown columns | Notes |
|---|---|---|
| AdInsightsActions_AgeGender | Age, Gender, ActionType, ActionValue | Also available for the AdInsights view, but will not include ActionType or ActionValue. |
| AdInsightsActions_Country | Country, ActionType, ActionValue | Also available for the AdInsights view, but will not include ActionType or ActionValue. |
| AdInsightsActions_Region | Region, ActionType, ActionValue | Also available for the AdInsights view, but will not include ActionType or ActionValue. |
| AdInsightsActions_PlatformPublisher | PlatformPosition, PublisherPlatform, ActionType, ActionValue | Also available for the AdInsights view, but will not include ActionType or ActionValue. |
| AdInsightsActions_FrequencyValue | FrequencyValue, ActionType, ActionValue | Also available for the AdInsights view, but will not include ActionType or ActionValue. |
| AdInsightsActions_HStatsByAdvertiserTZ | HStatsByAdvertiserTZ, ActionType, ActionValue | Also available for the AdInsights view, but will not include ActionType or ActionValue. |
| AdInsightsActions_HStatsByAudienceTZ | HStatsByAudienceTZ, ActionType, ActionValue | Also available for the AdInsights view, but will not include ActionType or ActionValue. |
| AdInsightsActions_ProductId | ProductId, ActionType, ActionValue | Also available for the AdInsights view, but will not include ActionType or ActionValue. |
| AdInsightsActions_OtherDevice | ImpressionDevice, ActionDevice, ActionType, ActionValue | Also available for the AdInsights view, but will not include ActionDevice, ActionType or ActionValue. |
| AdInsightsActions_DevicePlatform | DevicePlatform, ActionValue | |
| AdInsightsActions_PlacePageId | PlacePageId, ActionType, ActionValue | |
| AdInsightsActions_DMA | DMA, ActionValue | |
| AdInsightsActions_ActionDestination | ActionDestination, ActionValue | |
| AdInsightsActions_ActionReaction | ActionReaction, ActionType, ActionValue | |
| AdInsightsActions_ActionCarousel | ActionCarouselCardId, ActionCarouselCardName, ActionType, ActionValue | |
| AdInsightsActions_ActionVideoType | ActionVideoType, ActionType, ActionValue | |
| AdInsightsActions_ActionVideoSound | ActionVideoSound, ActionType, ActionValue | |
| AdInsightsActions_ActionCanvasComponentName | ActionCanvasComponentName, ActionType, ActionValue | |
| AdInsightsActions_ActionConvertedProductId | ActionConvertedProductId, ActionType, ActionValue |
Data model
The example configurations in this guide relate to the relational tables, views, and stored procedures that are documented in the Facebook Ads data model. The following links contain more information about these tables and views, as well as connection options.