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

Table Specific Information

AdInsights in Facebook can be requested with a great amount of detail to simulate the same sort of information that can be retrieved in a report.

Select

When requesting AdInsights, 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 AdInsights WHERE Target = 'act_123456'

A date range can be specified using DateStart and DateEnd, or DatePreset must also be specified. For instance:

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'

The available values for DatePreset 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

The TimeIncrement can used to specify how many days should be included in each report row. For instance:

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

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

The Level column can be used to specify what level insights are retrieved at. This can be set to ad,adset,campaign, or account. For instance:

SELECT DateStart, DateEnd, AdAccountId, Age, Spend, Impressions FROM AdInsights WHERE Target = 'act_123456' AND Level = 'campaign'

There are a number of breakdown columns. In general, only one breakdown column can be selected at a time. If you use SELECT *, no breakdown columns will be used. The available breakdown columns are:

• Age: Can also be selected with Gender
• Country
• FrequencyValue
• Gender: Can also be selected with Age
• HStatsByAdvertiserTZ (Hourly Stats by Advertizer Timezone)
• HStatsByAudienceTZ (Hourly Stats by Audience Timezone)
• ImpressionDevice: Can also be selected with PublisherPlatform or both PublisherPlatform and PlatformPosition.
• PlatformPosition: Must be selected with PublisherPlatform. Can also be selected with ImpressionDevice.
• PublisherPlatform: Can be selected with PlatformPosition, ImpressionDevice, or both PlatformPosition and ImpressionDevice.
• ProductId
• Region

Most other columns not already mentioned can be used with standard SQL WHERE clause modifiers. For instance:

SELECT DateStart, DateEnd, AdAccountId, Spend, Impressions FROM AdInsights WHERE Target = 'act_123456' WHERE Impressions > 10000 AND Spend < 1000

Both the DatePreset and the breakdowns are subject to frequent changes by Facebook. The lists above may be outdated due to Facebook changes. To see the most currently available breakdowns and date presets, see the documentation on Facebook for parameters and breakdowns: https://developers.facebook.com/docs/marketing-api/insights/.

Note that Facebook Ads does enforce restrictions on what breakdowns can be selected together, so by default the connector 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.

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 connector 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