Filters

Filters determine which users, profiles, or events an endpoint includes. The API uses the same filter representation in request and response bodies. Each endpoint defines what the filter applies to and whether it can be null.

A filter is always a group of rules. Each rule is either a condition or a nested group. Each group uses a single logical operator, and nested groups let you mix and and or in the same filter.

For guidance on building filters and choosing operators, see the general filters documentation.

For example, the following filter represents country is US AND (plan is pro OR lifetimeValue is greater than 1000):

{
  "operator": "and",
  "rules": [
    {
      "property": "country",
      "operator": "is",
      "values": [ "US" ]
    },
    {
      "operator": "or",
      "rules": [
        {
          "property": "plan",
          "operator": "is",
          "values": [ "pro" ]
        },
        {
          "property": "lifetimeValue",
          "operator": "is greater than",
          "values": [ "1000" ]
        }
      ]
    }
  ]
}

Filter groups

A filter group has the following fields:

Field	Type	Required	Description
operator	string	✓	Determines how the group's rules are evaluated. Use "and" to require every rule to match, or "or" to require at least one rule to match.
rules	array	✓	One or more conditions or nested groups combined by the group's operator.

The root filter must be a group. A nested group has the same representation as the root filter.

Filter rules

The presence of property or rules determines the type of a rule:

• A rule with property is a condition.
• A rule with rules is a nested group.

A rule must contain exactly one of these fields.

Both conditions and groups have an operator field, but the allowed values are different. A group uses "and" or "or". A condition uses an operator supported by the property being evaluated.

Conditions

A filter condition has the following fields:

Field	Type	Required	Description
property	string	✓	The name or path of the property to evaluate.
operator	string	✓	Determines how the property is evaluated. The operators available depend on the property's type.
values	array of string		The values used by the operator. Whether it is present and how many elements it contains depend on the operator.

The number of values depends on the operator:

• No values: is true, is false, is empty, is not empty, is null, is not null, exists, and does not exist
• Exactly two values: is between and is not between
• One or more values: is one of and is not one of
• Exactly one value: all other operators

When an operator doesn't take values, responses omit values. Requests can omit values or set it to null. Don't use an empty array; the API rejects it.

Each value can contain at most 60 characters. This limit does not apply when a string property defines a fixed set of allowed values.

Property paths use dot notation. See Using keys of a JSON property for details.

Nested groups

A nested group has the same structure as the root filter: an operator and a rules array. Its operator must be "and" or "or". Its result is evaluated as one rule of its parent group, regardless of how many rules it contains.

Groups can be nested up to four levels, including the root group. A filter can contain up to 100 rules in total, counting both conditions and nested groups. The root group doesn't count toward this limit.