You can set an object level prefix on a filter to leverage Insights multi-level filtering. For example, an ads rule can be filtered by ad set or ad campaign performance. You can also specify attribution window and time preset prefixes on a filter. This is used to override the rule’s attribution window and time preset for this particular filter.

Usage

Prefixes are optional. A field can have:

an object level prefix

an attribution window prefix

a time preset prefix

You can have all the options above, none, or any combination, as long as you keep them in that order. The field should have following format:

{ object_level_prefix? } {attribution_window_prefix?} { time_preset_prefix? } { field_name }

Below, see examples of correct and incorrect prefixed Insights fields. We also provide examples of correct and incorrect prefixed metadata fields, to show which metadata filters we support.

Examples for Insights field `spent`

Good examples

✅ adset.yesterday_spent - total amount spent at the ad set level yesterday

✅ adset.spent - total amount spent at ad set level

✅ yesterday_spent - total amount spent yesterday

✅ campaign.28d_view_1d_click:lifetime_results - total results at the ad set level over its lifetime, with the attribution window of 28 days after viewing and 1 day after clicking

✅ campaign.lifetime_spent - total amount spent at the ad campaign level over its lifetime

Bad examples

❌ lifetime_campaign.spent - time preset prefixes cannot come before object level prefixes

❌ lifetime_today_spent - there cannot be two time preset prefixes

❌ ad.adset.spent - there cannot be two object level prefixes

❌ yesterday.adset_spent - bad delimiter

Examples for Metadata field `daily_budget`

Good examples

✅ adset.daily_budget - daily budget of the ad set

✅ daily_budget - daily budget

Bad examples

❌ yesterday_daily_budget - cannot use time preset prefixes on Metadata fields

❌ ad.daily_budget - ads do not have a daily budget

Object Level Prefixes

Prefix	Object Type	Valid on Object Types
`ad.`	Ad	Ad
`adset.`	Ad Set	Ad, Ad Set
`campaign.`	Campaign	Ad, Ad Set, Campaign

Attribution Window Prefixes

Attribution Window Prefix	Description
`account_default:`	Use the account level attribution window setting
`default:`	The Facebook default attribution window is 1 day views, 28 day clicks
`inline:`	Inline attribution only (0 day views, 0 day clicks)
`1d_view:`	1 day views, 0 day clicks
`7d_view:`	7 day views, 0 day clicks
`28d_view:`	28 day views, 0 day clicks
`1d_click:`	0 day views, 1 day clicks
`7d_click:`	0 day views, 7 day clicks
`28d_click:`	0 day views, 28 day clicks
`1d_view_1d_click:`	1 day views, 1 day clicks
`7d_view_1d_click:`	7 day views, 1 day clicks
`28d_view_1d_click:`	28 day views, 1 day clicks
`1d_view_7d_click:`	1 day views, 7 day clicks
`7d_view_7d_click:`	7 day views, 7 day clicks
`28d_view_7d_click:`	28 day views, 7 day clicks
`7d_view_28d_click:`	7 day views, 28 day clicks
`28d_view_28d_click:`	28 day views, 28 day clicks

Time Preset Prefixes

This list is the same as the list of valid time preset values, but made into lowercase and attached with a delimiter.

Prefix	Description
`lifetime_`	Lifetime of the object
`today_`	The current day starting from midnight in the ad account’s timezone
`last_2_days_`	`YESTERDAY` and `TODAY`
`last_3_days_`	Last 2 full days and `TODAY`
`last_7_days_`	Last 6 full days and `TODAY`
`last_14_days_`	Last 13 full days and `TODAY`
`last_28_days_`	Last 27 full days and `TODAY`
`last_30_days_`	Last 29 full days and `TODAY`
`this_month_`	This month, including `TODAY`
`this_week_mon_today_`	This week using Monday as first day of week, including `TODAY`
`this_week_sun_today`	This week using Sunday as first day of week, including `TODAY`
`yesterday_`	The previous full day, excluding `TODAY`
`last_2d_`	Last 2 full days, excluding `TODAY`
`last_3d_`	Last 3 full days, excluding `TODAY`
`last_7d_`	Last 7 full days, excluding `TODAY`
`last_14d_`	Last 14 full days, excluding `TODAY`
`last_28d_`	Last 28 full days, excluding `TODAY`
`last_30d_`	Last 30 full days, excluding `TODAY`
`last_nd_14_8_`	Last 14 days to Last 7 days, for ROAS
`last_nd_30_8_`	Last 30 days to Last 7 days, for ROAS
`last_nd_60_8_`	Last 60 days to Last 7 days, for ROAS
`last_nd_120_8_`	Last 120 days to Last 7 days, for ROAS
`last_nd_180_8_`	Last 180 days to Last 7 days, for ROAS
`last_nd_lifetime_8_`	Lifetime to Last 7 days, for ROAS
`last_nd_60_29_`	Last 60 days to Last 28 days, for ROAS
`last_nd_120_20_`	Last 120 days to Last 28 days, for ROAS
`last_nd_180_29_`	Last 180 days to Last 28 days, for ROAS
`last_nd_lifetime_29_`	Lifetime to Last 28 days, for ROAS

Aggregation

You can aggregate some Insights fields over multiple ad objects. This allows you to create filters on metrics over a specific subset of ad objects. For example, the total reach over multiple ads or the total number of clicks over different ad sets.

While some metrics such as clicks are calculated with simple summation, other metrics such as reach are calculated differently. Since reach is based on unique impressions, duplicate users are removed in the aggregation over multiple ad objects.

Usage

An aggregated field takes the form of aggregate({ field }). The field can contain attribution window and time preset prefixes. The set of ad objects to be aggregated is determined by another required filter field aggregation_id.

Example Aggregate Fields

Good examples

✅ aggregate(reach)

✅ aggregate(lifetime_reach)

Bad examples

❌ aggregate(daily_budget)

❌ aggregate(adset.reach)

Aggregation Id Filter

The aggregation_id filter specifies which ad objects to aggregate. It only supports the IN operator and a list of ids as its value. The ids may be of ads, ad sets, or ad campaigns, but all of them must be from the same object level.

Example `aggregation_id` filter

{
  "field": "aggregation_id",
  "operator": "IN",
  "value": [1234, 5678]
},
{
  "field": "aggregate(reach)",
  "operator": "GREATER_THAN",
  "value": 100
}

Supported Fields

clicks

cpc

cpm

cpp

ctr

frequency

impressions

mobile_app_purchase_roas

reach

result_rate

spent

unique_clicks

unique_impressions

website_purchase_roas

cost_per_unique_click

Formula Fields

You can set simple arithmetic expressions as a field. For example, this can be used to find the ratio between two numeric fields.

This works on Insights fields and on a subset of numeric Metadata fields. The full supported list is below.

Usage

A formula field consists of fields or constants and syntactically correct operators separated by spaces. It supports the operators + - * and /. You can add constants, for example to weigh specific fields or to act as offsets.

The fields in this case can be fully prefixed, so you can add valid object level and time preset prefixes.

We currently allow a maximum of 6 non-constant fields in a formula. You can have as many constants as you want.

today_spent / adset.today_spent

0.8 * cpc + 0.2 * cpm

{ field_or_constant_1 } { +

-

*

/ } { field_or_constant_2 }

Example Formulas

Good examples

✅ today_spent / adset.daily_budget - daily percent spend

✅ clicks / adset.clicks - ratio of clicks compared to ad set’s clicks

✅ today_impressions / yesterday_impressions - ratio of today’s number of impressions compared to yesterday’s number of impressions

✅ today_impressions / aggregate(today_impressions) - ratio of today’s number of impressions compared to an aggregated number of impressions

✅ (adset.spent - spent) - parentheses are accepted, when receiving formulas in API responses, they will be parenthesized

Bad examples

❌ (clicks + cpc + cpm + ctr + cpa + cpp) / cost_per - cannot use more than 6 fields

❌ today_impressions/yesterday_impressions - terms must be space separated

Valid Numeric Metadata Fields

Field	Valid on Object Types
`bid_amount`	Ad, Adset
`daily_budget`	Adset
`lifetime_budget`	Adset
`spend_cap`	Campaign

Did you find this page helpful?

Evaluation Spec Filters

Prefixed Insights Fields

Usage

Examples for Insights field spent

Good examples

Bad examples

Examples for Metadata field daily_budget

Good examples

Bad examples

Object Level Prefixes

Attribution Window Prefixes

Time Preset Prefixes

Aggregation

Usage

Example Aggregate Fields

Good examples

Bad examples

Aggregation Id Filter

Example aggregation_id filter

Supported Fields

Formula Fields

Usage

Example Formulas

Good examples

Bad examples

Valid Numeric Metadata Fields

Examples for Insights field `spent`

Examples for Metadata field `daily_budget`

Example `aggregation_id` filter