CData Python Connector for Facebook Ads

Build 22.0.8462

AdInsightsActions

Query an Ad Report. Accessing Ad Report information requires the ads_read permission.

Table Specific Information

AdInsightsActions represents a breakdown of the Actions column from the AdInsights. See AdInsights for general information on querying AdInsights.

Select

When requesting AdInsightsActions, a Target must be specified. This indicates what element to retrieve the insights from. It can be an AdAccount, Campaign, AdSet, or an Ad. For instance:

SELECT * FROM AdInsightsActions WHERE Target = 'act_123456'

The specific collection to retrieve from AdInsightsActions may be specified via ActionCollection. If none is specified, Actions is used. Each input represents an available column from AdInsights where a collection of actions would return. Furthermore, multiple collections may be specified via the IN clause. For instance:

SELECT * FROM AdInsightsActions WHERE Target = 'act_123456' AND ActionCollection = 'UniqueActions'

SELECT * FROM AdInsightsActions WHERE Target = 'act_123456' AND ActionCollection IN ('Actions','UniqueActions')

Just as in the available selection criterias from AdInsights, breakdowns are available. Please see AdInsights for details on breakdowns. Additional breakdowns for AdInsightsActions include ActionType, ActionCanvasComponentName, ActionCarouselCardId, ActionCarouselCardName, ActionDestination, ActionDevice, ActionLinkClickDestination, ActionReaction, ActionTargetId, ActionVideoSound, and ActionVideoType.

ActionAttributionWindows is available to input a comma separated list of attribution windows. For instance:

SELECT * FROM AdInsightsActions WHERE Target='act_123456' AND level='ad' AND ActionAttributionWindows='1d_view,7d_view,28d_click'

Note: The following error message may be encountered when querying from this table: "Please reduce the amount of data you're asking for, then retry your request".

This error typically occurs when the driver requests an amount of data that Facebook cannot handle the calculations for on its end. It appears to be triggered based on individually dense fields, and not the page size.

If the provider encounters this error when first executing certain types of queries, the driver will attempt to retry the query at a lower level of ad object, if possible. To retry, the driver will execute the query at the next lowest level of ad object, down to the level defined in RetryLevel. Note that if the Level parameter is specified in a query, the driver will not attempt to retry beyond the ad object level specified by Level. Please see RetryLevel for more details. Additionally, spreading queries across more granular ad objects can decrease query performance by increasing the number of requests executed for the query.

If this error is still encountered, either reduce the date range of the query or remove expensive columns.

A good method for finding and removing expensive columns is to use a binary search by removing half of the columns you are selecting and retrying the query. Then retry again with half of the remaining columns if you get the same error, or half of the removed columns if you got no error.

Columns

Name Type Description
Target String The Id of the Account, Campaign, Ad Group, or Ad to get insights for.
DatePreset String An alternative to specifying the DateStart and DateEnd. A date range will automatically be calculated based on the specified preset value.

The allowed values are maximum, today, yesterday, this_week_sun_today, this_week_mon_today, last_week_sun_sat, last_week_mon_sun, last_3d, last_7d, last_14d, last_28d, last_30d, last_90d, this_month, last_month.

DateStart Date The starting date to retrieve insights for. In the Facebook UI, this is the Report Start field. In the Facebook UI, this is the Report Start field.
DateEnd Date The ending date to retrieve insights for. In the Facebook UI, this is the Report End field. In the Facebook UI, this is the Report End field.
TimeIncrement String The number of days of data aggregation. An int (1-90) or one of monthly or all_days. This value splits the range or preset date into smaller increments.

The default value is 1.

Level String The level to represent the results at.

The allowed values are ad, adset, campaign, account.

ActionAttributionWindows String A comma separated list which determines what is the attribution window for the actions. For example, 28d_click means the API returns all actions that happened 28 days after someone clicked on the ad. The default option means [1d_view,28d_click]. Possible values include 1d_view, 7d_view, 28d_view, 1d_click, 7d_click, 28d_click, default.
ActionCollection String The action collection to retrieve. The available values are: ActionValues, Actions, AdClickActions, AdImpressionActions, CatalogSegmentActions, CatalogSegmentValue, CatalogSegmentValueMobilePurchaseRoas, CatalogSegmentValueOmniPurchaseRoas, CatalogSegmentValueWebsitePurchaseRoas, ConversionValues, Conversions, ConvertedProductQuantity, ConvertedProductValue, CostPer15_secVideoView, CostPer2SecContinuousVideoView, CostPerActionType, CostPerAdClick, CostPerConversion, CostPerOneThousandAdImpression, CostPerOutboundClick, CostPerStoreVisitAction, CostPerThruplay, CostPerUniqueActionType, CostPerUniqueConversion, CostPerUniqueOutboundClick, InteractiveComponentTap, MobileAppPurchaseRoas, OutboundClicks, OutboundClicksCtr, PurchaseRoas, StoreVisitActions, UniqueActions, UniqueConversions, UniqueOutboundClicks, UniqueOutboundClicksCtr, UniqueVideoView15_sec, Video15_secWatchedActions, Video30_secWatchedActions, VideoAvgTimeWatchedActions, VideoContinuous2SecWatchedActions, VideoP100_watchedActions, VideoP25WatchedActions, VideoP50WatchedActions, VideoP75WatchedActions, VideoP95WatchedActions, VideoPlayActions, VideoPlayCurveActions, VideoPlayRetention0To15SActions, VideoPlayRetention20_to60SActions, VideoPlayRetentionGraphActions, VideoTimeWatchedActions, WebsiteCtr, WebsitePurchaseRoas

The default value is Actions.

AdAccountId String The Id of the Ad Account associated with the report row.
AdAccountName String The name of the Ad Account associated with the report row.
CampaignId String The Id of the Campaign associated with the report row.
CampaignName String The name of the Campaign associated with the report row.
AdSetId String The Id of the Ad Set associated with the report row.
AdSetName String The name of the Ad Set associated with the report row.
AdId String The Id of the Ad associated with the report row.
AdName String The name of the Ad associated with the report row.
ActionType String The kind of actions taken on your ad, Page, app or event after your ad was served to someone, even if they didn't click on it.
ActionValue String Metric value of default attribution window.
Action1dClick String Metric value of attribution window 1 day after clicking the ad.
Action1dView String Metric value of attribution window 1 day after viewing the ad.
Action7dClick String Metric value of attribution window 7 days after clicking the ad.
Action7dView String Metric value of attribution window 7 days after viewing the ad.
Action28dClick String Metric value of attribution window 28 days after clicking the ad.
Action28dView String Metric value of attribution window 28 days after viewing the ad.
ActionDDA String Metric value of attribution window which is powered by data driven model.
ActionCanvasComponentName String Name of a component within a Canvas ad.
ActionCarouselCardId String The ID of the specific carousel card that people engaged with when they saw your ad.
ActionCarouselCardName String The specific carousel card that people engaged with when they saw your ad. The cards are identified by their headlines.
ActionConvertedProductId String Converted product ids - for Collaborative Ads.
ActionDestination String The destination where people go after clicking on your ad.
ActionDevice String The device on which the conversion event you are tracking occurred.
ActionReaction String The number of reactions on your ads or boosted posts.
ActionTargetId String The id of destination where people go after clicking on your ad.
ActionVideoSound String The sound status (on/off) when user watches your video ad.
ActionVideoType String Video metrics breakdown.
Age String The age range for the metrics in this row. This is a breakdown column and selecting this column will cause results to be further broken down by this metric.
Country String The country for the metrics in this row. This is a breakdown column and selecting this column will cause results to be further broken down by this metric.
DevicePlatform String The device or platform used for viewing the ad. This is a breakdown column that may not be selected with other breakdown columns.
DMA String The designated marketing area. This is a breakdown column that may not be selected with other breakdown columns.
FrequencyValue String The number of times an ad in your Reach and Frequency campaign was served to each person. This is a breakdown column and selecting this column will cause results to be further broken down by this metric.
Gender String The gender for the metrics in this row. This is a breakdown column and selecting this column will cause results to be further broken down by this metric.
HStatsByAdvertiserTZ String Time period over which the stats were taken for the advertiser. This is a breakdown column and selecting this column will cause results to be further broken down by this metric.
HStatsByAudienceTZ String Time period over which the stats were taken for the audience. This is a breakdown column and selecting this column will cause results to be further broken down by this metric.
ImpressionDevice String The devices used to view the Ad. This is a breakdown column and selecting this column will cause results to be further broken down by this metric.
PlacePageId String The place page used if applicable. This is a breakdown column that may not be selected with other breakdown columns.
PlatformPosition String The position on the platform.
ProductId String The product Id advertised in the Ad. This is a breakdown column and selecting this column will cause results to be further broken down by this metric.
PublisherPlatform String The platforms the ads were published on.
Region String The region someone viewed the Ad from. This is a breakdown column and selecting this column will cause results to be further broken down by this metric.
AdEffectiveStatus String An input only list of supported statuses when retrieving insights at a level lower than the Ad Account. See the values listed on AdStatus for an example of valid values.
UseAsync Boolean A boolean indicating if an asynchronous call should be used for retrieving the insights.

Copyright (c) 2023 CData Software, Inc. - All rights reserved.
Build 22.0.8462