Evaluation Spec

The main purpose of the evaluation_spec of a rule is to determine the objects upon which the rule should execute its action. The evaluation_type determines the type of evaluation method and has the following options:

The evaluation_spec contains a filters array, which allows you to further narrow the list of matched objects. For example, you can construct filters on ad, ad set and ad campaign metadata and Insights metrics. All filters are evaluated together using the AND operator.

The filters array contains a list of filter objects. These objects are dictionaries with keys of field, value, and operator:

Each filter has a list of supported logical operators. Here are the logical operators supported in SCHEDULE and TRIGGER rules:

The evaluation_spec requires a trigger for the TRIGGER evaluation type. The trigger contains a type and an underlying filter specification. Filter specification can be field, value, and operator.

The trigger dynamically determines whether or not we should evaluate a rule, and you can have only one. See Trigger Based Rules for more information.

Below we define some special filters and general groups of filters that you can use.

Special Filters

time_preset

The time_preset filter determines the time period over which we aggregate Insights metrics. Currently, we only allow one time_preset. It applies to all stats filters in the rule, including the one used for the trigger, if present.

The only supported operator for time_preset is EQUAL, and this is required as long as any Insights filter or trigger is present. Trigger Based Rules only support time presets that include TODAY because it performs real-time evaluation.

Time presets for rules can behave differently from other interfaces. Some of the time presets here include today's data. This is because today's data is critical for rules that run more frequently than daily. For other interfaces, a preset value of LAST_N_DAYS generally does not include today's data. See the descriptions below for more details.

{
  "field": "time_preset",
  "value": "TODAY",
  "operator": "EQUAL"
}

attribution_window

The attribution_window filter determines the lookback window over which insights metrics are aggregated. For more information, see the Insights documentation on Attribution Windows.

Currently, we only allow one attribution_window, and it applies to all stats filters in the rule. The only supported operator for attribution_window is EQUAL, and this is only supported by Schedule Based Rules.

Whether specified or not, the only allowed value for the attribution_window is ACCOUNT_DEFAULT.

{
  "field": "attribution_window",
  "value": "ACCOUNT_DEFAULT",
  "operator": "EQUAL"
}

Metadata filters

With metadata filters, you can filter objects based on the current state of their metadata fields. These also support multi-level filtering, which means you can use prefixes to apply a metadata filter on an object's parent or grandparent. This does not affect other filters. Insights filters still apply to the normal object.

For instance, if you want a rule that applies to ad sets of ad campaigns whose objective is WEBSITE_CLICKS, you can include two filters:

 "filters" : [
  {
    "field": "entity_type",
    "value": "ADSET",
    "operator": "EQUAL",
  },
  {
    "field": "campaign.objective",
    "value": "WEBSITE_CLICKS",
    "operator": "EQUAL"
  }
]

Metadata filters supported by Trigger and Schedule Based rules

Metadata filters supported only by Schedule Based rules

entity_type and id

For every rule of evaluation type SCHEDULE or TRIGGER, you must specify either an entity_type or id filter.

When you specify an entity_type filter, you determine a dynamic object level for which to apply the rule. For example, if the entity_type is AD, that rule automatically evaluates every new ad that added to the ad account. This happens regardless of when you create the rule. By specifying an id filter, the rule only applies to a static list of objects.

When you specify an id filter with no prefix, we automatically compute the object level for which to apply the rule. For example, if you want to apply a rule to ads [123, 456], you only need one filter field id, value [123, 456], and operator IN. In this case, entity_type not required, since you provided an initial static list of objects, and we can compute the object level from those objects.

You can use entity_type and id in conjunction with multi-level filtering. For example, if you want a rule that applies to all ads under some specified ad sets, you can have an entity_type filter of AD and an adset.id filter with the specified ad sets.

By default, if you do not specify an effective_status filter, we implicitly add an effective_status filter when evaluating the rule.

For all execution types that act upon active objects, this default filter has an operator of IN and a value of ['ACTIVE', 'PENDING_REVIEW']. This means the rule only evaluates objects that have or will have active delivery. For execution types that do not act upon active objects (UNPAUSE), we add this filter with an operator of NOT_IN and a value of ['DELETED', 'ARCHIVED']. The default filter is an internal optimization for our execution types.

Insights Filters

We evaluate insights filters against the current values returned from Insights API for a given time_preset. These filters apply directly to the list or level of objects, and do not support multi-level filtering. All Insights filters support the following operators: GREATER_THAN, LESS_THAN, EQUAL, IN_RANGE, NOT_IN_RANGE.

For a description of each of the fields below, see the Insights API docs. All of these filters are supported by Schedule Based Rules.

Below is a list of Insights filters and whether they are supported by Trigger Based Rules:

Advanced Filters

You can customize and derive advanced fields based off the insights and metadata filters above. For more information, see Advanced Evaluation Spec Filters.

Advanced filters support the following operators: GREATER_THAN, LESS_THAN, EQUAL, IN_RANGE, NOT_IN_RANGE. They are only supported by Schedule Based Rules.

For some of the most commonly used advanced filters, we support an alias as the filter: