Ads and Commerce
Ads and Commerce
Resources

Audience Rules

Updated: Feb 5, 2026
Audience rules determine whether someone is added your custom audience. The rules are applied on either the referrer URL or specific events and data.
Provide your rules as JSON-encoded strings structured like so:
Use audience rules for different types of custom audiences, including Website Custom Audiences, Mobile App Custom Audiences, and Offline Custom Audiences. For Engagement Audience Rules, see Engagement Custom Audiences.

Limitations

  • Each audience can specify up to 10 rules in the audience rule. This includes the number of rules in inclusions or exclusions.
  • Each rule can specify up to 100 filters, known as leaf nodes.

Audience Rules Syntax

To define an audience rule, the following structure must be followed:
rule: {
   "inclusions": <RULE_SET>,
   "exclusions": <RULE_SET>,
}

Available Fields

Name Description
inclusions
type: String
Required.
Rule Set JSON string that defines the inclusion. See Rule Set Syntax.
exclusions
type: String
Required.
Rule set JSON string that defines the exclusion. See Rule Set Syntax.

Rule Set Syntax

For each rule set, follow this structure:
{
  "operator" : <BOOLEAN_OPERATOR>,
  "rules" : <JSON_RULE>,
}

Available Fields

Name Description
operator
type: string
Required.
and or or.
rules
type: string
Required.
JSON string of rules (array of rules). See Inclusion And Exclusion Rule Syntax.

Inclusion And Exclusion Rule Syntax

For each inclusion or exclusion rule, follow this structure:
{
  "event_sources" : <EVENT_SOURCE_DEFINITION>,
  "retention_seconds" : <SECONDS>,
  "filter" : <FILTER>,
  "aggregation" : <AGGREGATION>,
}
aggregation and retention_seconds are editable fields. However, editing aggregation and retention_seconds does not flush the audience. People who only match the old rule/aggregation continue to be in the audience until they expire.

Available Fields

Name Description
event_sources
type: String
Required.
JSON object containing the id and type.
More event sources can be added to type using a comma delimited list "store_visits,pixel,app".
retention_seconds
type: Integer
Required.
Integer (in seconds) for the retention window of the audience, should be less than retention_days. Min=1; Max=365 days
filter
type: String
Required.
JSON string of the filter rules. See Filters.
aggregation
type: Integer
Optional.
JSON string of the aggregation functions. See Aggregate Functions.

Filters

Filtration follows this general format:
"filter" : {
  "operator": <BOOLEAN_OPERATOR>,
  "filters": <FILTER_SET>,
  }

Available Fields

Name Description
operator
type: string
Required.
and or or
filters
type: string
Required.
Array of JSON objects of filter rules. See Filter Set Syntax.

Filter Set Syntax

{
    "field": <FIELD>,
    "operator": <COMPARISON_OPERATOR>,
    "value": <VALUE>,
}

Available Fields

Name Description
field
type: String
Required.
  • For Website Custom Audiences, use 'event' if the filter is to specify an event. Parameters that match events sent by pixel (for example, 'ViewContent', 'Purchase').
  • For Mobile App Custom Audiences, Use 'event' if the filter is to specify an event. Parameters that match App events sent by app; for example, “_appVersion”, “_value”, and so on.
operator
type: String
Required.
  • =
  • !=
  • >=
  • >
  • <=
  • <
  • i_contains
  • i_not_contains
  • contains
  • not_contains
  • is_any
  • is_not_any
  • i_is_any
  • i_is_not_any
  • i_starts_with
  • starts_with
  • "regex_match"[INFO]
If field set to event, must use =.
value
type: String
Required.
If the field attribute is set to "event", the value must be set to an event name. Use the App Event API to see app events and parameters reported by the app.

Aggregate Functions

Create custom audiences based upon the frequency and intensity of behavior using the aggregation in the audience rule field. With this, you define an aggregate function, for example:
"aggregation" : {
  "type":"count",
  "operator":">",
  "value":1
}

Available Fields

Name Description
type
type: String
Required.
The aggregation function type.
  • For Website Custom Audiences, the following functions are available: 'count', 'sum', 'avg', 'min', 'max', 'time_spent', and 'last_event_time_field'.
  • For Mobile App Custom Audiences, the following functions are available: "count","sum", "avg", "min", and "max".
config
Required by certain types of aggregation functions.
method
type: String
Optional.
"absolute", meaning add people that logged events in specified range, or "percentile", meaning add people from a specified percentile range. If you select percentile, the operator should only be in_range and not_in_range.
field
type: String
Required. Unless type is count.
The parameter on which the aggregation function is applied.
operator
type: String
Required.
=, !=, >=, >, <=, <, in_range, not_in_range
value
type: String
Required.
Expected value of the parameter.
For example:
"aggregation" : {
  "type":"count",
  "operator":">",
  "value":1
}

Comparison Operators

Operator Description
> or gt
True if event’s parameter value greater than specified value.
>= or gte
True if event’s parameter value greater than or equal to specified value.
< or lt
True if event’s parameter value less than specified value.
<= or lte
True if event’s parameter value less than or equal to specified value.
= or eq
True if event’s parameter value equal to specified value. Note: This is equivalent to not specifying an operator at all; that is, “‘x’ : { ‘eq’ : ‘y’ }” is the same as “‘x’ : ‘y’ }.
!= or neq
True if event’s parameter value not equal to specified value.
contains
True if event’s parameter value, as string, contains specified string. Value of “shoe12345” fulfills ‘contains’ if specified value ‘shoe’.
not_contains
True if event’s parameter value, as string, does not contain specified string. Value “shoe12345” fulfills ‘not_contains’ if specified value is ‘purse’.
i_contains
Contains, case-insensitive
i_not_contains
Not contains, case-insensitive
is_any
True if event’s parameter value matches any strings in given array.
is_not_any
True if event’s parameter value matches no strings in specified array.
i_is_any
‘is_any’, case-insensitive.
i_is_not_any
‘is_not_any’, case-insensitive
starts_with
True is the event’s parameter value starts with the given string
i_starts_with
“starts_with”, case-insensitive
regex_match
Matches a regular expression such as "example\.com.*purchase$". The full PCRE grammar is supported

Examples

Website Custom Audiences

Match all referring URLs containing the string shoes in the last 30 days:
{
    "inclusions": {
        "operator": "or",
        "rules": [
            {
                "event_sources": [
                    {
                        "type": "pixel",
                        "id": "<PIXEL_ID>",
                    }
                ],
                "retention_seconds": 2592000,
                "filter": {
                    "operator": "and",
                    "filters": [
                        {
                            "field": "url",
                            "operator": "i_contains",
                            "value": "shoes"
                        }
                    ]
                },
            }
        ]
    }
}
Match ViewContent events where item price is greater than or equal to USD 100 in the last 30 days. Consider using this rule for the following event:
_fbq.push([ 'track', 'ViewContent', { productId: 1234, category: 'Men > Shoes', price: 199 } ]);

{
    "inclusions": {
        "operator": "or",
        "rules": [
            {
                "event_sources": [
                    {
                        "type": "pixel",
                        "id": "<PIXEL_ID>"
                    }
                ],
                "retention_seconds": 2592000,
                "filter": {
                    "operator": "and",
                    "filters": [
                        {
                            "field": "event",
                            "operator": "eq",
                            "value": "ViewContent"
                        },
                        {
                            "operator": "or",
                            "filters": [
                                {
                                    "field": "price",
                                    "operator": ">=",
                                    "value": "100"
                                }
                            ]
                        }
                    ]
                }
            }
        ]
    }
}

Mobile App Custom Audiences

See Mobile App Custom Audiences, Example Custom Audience Rules.

Operators and Data or Events

Rules have the following operators and data or events:
Operators The type of filter
i_contains
Contains substring, case insensitive
i_not_contains
Does not contain substring, case insensitive
contains
Contains substring, case sensitive
not_contains
Does not contain substring, case sensitive
eq
Equal to, case sensitive
neq
Not equal to, case sensitive
lt
Less than, numeric fields only
lte
Less than or equal to, numeric fields only
gt
Greater than, numeric fields only
gte
Greater than or equal to, numeric fields only
regex_match
Matches a regular expression such as \"example\\.com.*purchase$\". The full PCRE grammar is supported
Data Data being filtered
url
Fully escaped URL of the site visited
domain
Domain of site visited
path
Path of site visited, excluding domain
event
Name of pixel event, such as 'ViewContent'
device_type
Device that accessed site:
desktop
mobile_android_phone
mobile_android_tablet
mobile_ipad
mobile_ipod
mobile_iphone
mobile_tablet
mobile_windows_phone
any customData field
Any field added to customData for pixel fires, such as productId, category, price
Provide each rule as a JSON-encoded string.
Did you find this page helpful?
Thumbs up icon
Thumbs down icon