Evaluation Spec - Filters

In Schedule Based rules, it is possible to use more advanced types of filter fields.

Prefixed Insights Fields

Similar to how you can specify prefixes for Metadata filters - specifically to perform multi-level filtering, we support specific types of prefixes for Insights filters.

We support setting an object level prefix on a filter, which allows you to leverage multi-level filtering through Insights. For example, if a rule applies to Ads, we can filter based on Ad Set or Campaign level performance.

We also support setting attribution window and time preset prefixes on a filter, which allows you to override the rule's attribution window and time preset for this particular filter.

Usage

Prefixes are optional - a field may have only an object level prefix, only an attribution window prefix, only a time preset prefix, all, none, or any combination (in order). The field should also follow the following format:

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

Below, we provide examples of good and bad prefixed Insights fields. We also provide examples of good and bad prefixed Metadata fields, just to draw a parallel with what Metadata filters already 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 adset 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 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

PrefixObject TypeValid 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 FB 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

Note that 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

We support aggregating some Insights fields over multiple ad objects. This allows the creation of filters on metrics over a specific subset of ad objects, such as 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, we remove duplicate users 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 provided ids may be ids of Ads, Ad Sets, or Campaigns, but all ids must be 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
  • social_clicks
  • social_impressions
  • spend
  • spent
  • total_actions
  • unique_clicks
  • unique_impressions
  • website_purchase_roas
  • cost_per_unique_click

Formula Fields

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

This not only works on Insights fields, but also 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, which means that 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 need.

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 # impressions compared to yesterday's # impressions)

today_impressions / aggregate(today_impressions) (ratio of today's # impressions compared to an aggregated number of impressions)

(adset.spent - spent) (parentheses are ok, 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

FieldValid on Object Types

bid_amount

Ad, Adset

daily_budget

Adset

lifetime_budget

Adset

spend_cap

Campaign