Traffic filters

For all API methods in the /traffic family, filters can be used to constrain the events for aggregation. A filter thus allows you to drill down to a particular segment of your traffic seen in a specified period. Filters come in several flavors, depending on the constraint you need to express. These can be:

• event specific (types event, time, custom, intent and activeTime)

• content specific (type keyword)

• user and population specific (types user-keyword, user-external, user and explodeUsers)

Some of the filters can be nested, where the the outer filter expands or restricts the nested filter. Otherwise, the filters can be combined using logical operators (and, or, not) to yield more complex, composite filters.

Event filter

An event filter allows you to specify a filtering predicate based on a property associated with the event. For example, you may want to consider only the events that originate from users in Germany, or only events that originate from Apple phones, or only events that originate from the IP addresses known to be allocated to the company Microsoft. A list of the event groups that are available to use can be found here. The most popular items in each group can be listed using /traffic/event.

• The basic form of this filter is as follows:

{"type":"event", "group":"deviceType", "item":"Mobile"}

• Alternatively, it is possible to specify multiple items to match either of the values:

{"type":"event", "group":"deviceType", "items":["Mobile", "Tablet"]}

• It is also possible to match any defined (non-null, non-empty) value:

{"type":"event", "group":"referrerQuery"}

Event metrics filter

An event metrics filter allows you to specify a filtering predicate based on the data associated with the aggregation metrics. For example, you may want to consider only the events that originate from users spending between 20 and 30 seconds on the page, or only events that originate from users scrolling down within 80% and 100% of the page length. The currently available fields are activeTime and scrollDepth. It is possible to specify the min and max value, where both are inclusive and optional, with default values "min" = 0 and "max" is unbounded.

• The basic form of this filter is as follows:

{"type":"event-metrics", "group":"activeTime", "min":20, "max":30}

– this will obtain all the events with dwell time between 20 and 30 seconds.

• The filter without the upper bound:

{"type":"event-metrics", "group":"scrollDepth", "min":50}

– this will obtain all the events with scroll depth 50% and more.

Custom filter

A custom filter allows you to specify a filtering predicate based on a custom parameter associated with the event. The names and semantics of the custom key/value pair is up to your application and under your control, and depends on the circumstances under which your application submits the custom parameters.

• Similar to the event filter, the basic form of the filter matches a single group and item:

{"type":"custom", "group":"cx_source", "item":"recs"}

• Alternatively, multiple values of the same group:

{"type":"custom", "group":"cx_source", "items":["recs", "ad"]}

• Or, any defined (non-null) value:

{"type":"custom", "group":"cx_source"}

Keyword filter

A keyword filter allows you to specify a filtering predicate based on a property associated with the content being consumed. For example, you may want to only consider page view events for pages belonging to the Sports category, or only events for pages having negative sentiment, or only events for pages that mention the person Marit Bjørgen. The set of such properties that you can filter on with keyword filters are defined by what you find in the content profiles.

• The basic form of this filter is as follows:

{"type":"keyword", "group":"person", "item":"marit bjørgen"}

• Similar to the event filter, it is possible to match either of the multiple items. However, in this case, group must be specified:

{"type":"keyword", "group":"person", "items":["marit bjørgen", "therese johaug"]}

• It is also possible to look for item/items in default groups ("person", "location", "company", "concept", "entity", "category", "taxonomy"). To make this request set the group name to "term", and specify the item or items:

{"type":"keyword", "group":"term", "item":"marit bjørgen"}

• Or, it is possible to match any defined (non-null) value for the given group:

{"type":"keyword", "group":"person"}

• Or inclusive range filters for time items (start, stop):

{"type":"keyword", "group":"publishtime", "start":"1990-06-20", "stop":"-3y"}
{"type":"keyword", "group":"publishtime", "start":"-5d"}
{"type":"keyword", "group":"publishtime", "start":"-5d", "stop": "+10d"}
{"type":"keyword", "group":"publishtime", "stop":"2020-01-22"}

• Additionally, it is possible specify minimum and/or maximum item weight:

{"type":"keyword", "group":"person", "item":"marit bjørgen", "minWeight":0.25, "maxWeight":0.75}

– by default "minWeight" is 0.0 and "maxWeight" is 1.0.

User keyword filter

A user keyword filter allows you to specify a filtering predicate based on the data associated with the user keywords inferred based on their historical content consumption. For example, you could choose to only consider page view events from users interested in banking news, or any other topic or combination of topics from your custom taxonomy tree.

• Similar to the event filter, the basic form of the filter matches a single group and item:

{"type":"user-keyword", "group":"cxs-categories", "item":"news/business/bank"}

• Alternatively, multiple values of the same group:

{"type":"user-keyword", "group":"cxs-categories", "items":["news/business/bank", "news/business/investments"]}

• Or, any defined (non-null) value:

{"type":"user-keyword", "group":"cxs-categories"}

• Additionally, it is possible specify minimum and/or maximum item weight:

{"type":"user-keyword", "group":"cxs-categories", "item":"news/business/bank", "minWeight":0.25, "maxWeight":0.75}

– by default "minWeight" is 0.0 and "maxWeight" is 1.0.

User interest filter

A user interest filter allows to specify a filter predicate based on the inferred user interests. This filter is a subset of the user keyword filter in the same way as /traffic/user/interest is a subset of /traffic/user/keyword. The only distinction in the following examples versus those given above is in the specified type.

• Similar to the event filter, the basic form of the filter matches a single group and item:

{"type":"user-interest", "group":"cxs-categories", "item":"news/business/bank"}

• Alternatively, multiple values of the same group:

{"type":"user-interest", "group":"cxs-categories", "items":["news/business/bank", "news/business/investments"]}

• Or, any defined (non-null) value:

{"type":"user-interest", "group":"cxs-categories"}

• Additionally, it is possible specify minimum and/or maximum item weight:

{"type":"user-interest", "group":"cxs-categories", "item":"news/business/bank", "minWeight":0.25, "maxWeight":0.75}

– by default "minWeight" is 0.0 and "maxWeight" is 1.0.

User preference filter

A user preference filter matches users with preference for a given target filter. It will include events matching the given filter, for users having (number of events also matching the given target filter) / (number of events matching filter) > threshold.

The following example includes article reads for users with a strong reading preference for business and finance articles:

{
 "type": "user-preference",
 "filter": { # We consider pageviews
 "type": "keyword", # with content profile
 "group": "pageclass", # classifying the page
 "item": "article" # as an article.
 },
 "threshold": 0.85, # We include article reads for users with 85% of their read articles
 "targetFilter": { # having
 "type": "keyword", # content profile
 "group": "classification", # with IAB classification
 "item": "business-and-finance" # business and finance.
 }
}

Top User preference filter

A top user preference filter matches the top users with preference for a given target filter. It will include events matching the given filter, for the top users having (number of events also matching the given target filter) / (number of events matching filter).

The following example includes article reads for the top 85% users with a strong reading preference for business and finance articles:

{
 "type": "top-user-preference",
 "filter": { # We consider pageviews
 "type": "keyword", # with content profile
 "group": "pageclass", # classifying the page
 "item": "article" # as an article.
 },
 "percent": 0.85, # We include article reads for the top 85% users of their read articles
 "targetFilter": { # having
 "type": "keyword", # content profile
 "group": "classification", # with IAB classification
 "item": "business-and-finance" # business and finance.
 }
}

The percent will include the Top X percent of the users.

External user keyword filter (DMP 1st party data)

An external user keyword filter allows you to specify a filtering predicate based on the data associated with the external keywords associated with users.

For example, you could choose to only consider page view events from users tagged as "subscribers" with /profile/user/external/update.

• Similar to the event filter, the basic form of the filter matches a single group and item:

{"type":"user-external", "group":"cxs-subscriber", "item":"yes"}
{"type":"user-external", "group":"cxs-byear", "item":1942}

• Alternatively, multiple values of the same group:

{"type":"user-external", "group":"cxs-subscriber", "items":["yes", "no"]}
{"type":"user-external", "group":"cxs-byear", "items":[1942, 1940]}

• Or inclusive range filters for numeric items (min, max):

{"type":"user-external", "group":"cxs-byear", "min":1940, "max":1980}
{"type":"user-external", "group":"cxs-byear", "min":1940}
{"type":"user-external", "group":"cxs-byear", "max":2000}

• Or inclusive range filters for decimal item typed (min, max):

{"type":"user-external", "group":"cxs-price", "min":50.35, "max":90.98}
{"type":"user-external", "group":"cxs-price", "min":50.35}
{"type":"user-external", "group":"cxs-price", "max":90.98}

• Or inclusive range filters for time items (start, stop):

{"type":"user-external", "group":"cxs-subscription-date", "start":"1990-06-20", "stop":"-3y"}
{"type":"user-external", "group":"cxs-subscription-date", "start":"-5d"}
{"type":"user-external", "group":"cxs-subscription-date", "start":"-5d", "stop": "+10d"}
{"type":"user-external", "group":"cxs-subscription-date", "stop":"2020-01-22"}

• Or, any defined (non-null) value:

{"type":"user-external", "group":"cxs-subscriber"}

Intent filter

The short term intents wiki page describes how to annotate the events with intent information, either via (1) a query processing taxonomy, (2) a meta tag, or (3) a content processing taxonomy. The following filter is specific for intents generated by the query processing taxonomy (1). To filter on intents generated by the other two methods (2, 3) use a keyword filter with a <prefix>-intent group.Both filters allow you to consider only the page views marked with a particular intent. Differently from user-keywords such as interests, these filters will select not all events from the users with the given intent, but only the exact events (page veiws) triggering the intent. With "type":"intent" it will be the events with a query triggering the intent, while with the "type":"keyword" it will be events with a** content** triggering the intent. Either way, in order to get all events from such users, the filter must be wrapped in an explodeUsers filter, which is described longer below.

• Similar to the event filter, the basic form of the filter matches a single group and item:

{"type":"intent", "group":"cxd-intent", "item":"travel"}

• Alternatively, multiple values of the same group:

{"type":"intent", "group":"cxd-intent", "items":["travel", "shopping"]}

• Or, any defined (non-null) value:

{"type":"intent", "group":"cxd-intent"}

Active time filter

An active time filter allows to filter the events based on dwell time. It is possible to specify the min and max value as active time in seconds, where both are inclusive and optional, with default values "min":0 and "max":1800 (30 minutes).

{"type":"activeTime", "min":180, "max":360}

User filter

A user filter allows to filter based on the properties associated with the users.

• In the simplest form, it is possible to filter based on the number of events from a particular user:

{"type":"user", "having":{"min":5, "max":10}}

either min or max value must be specified, the default min value is 0 and the default max value is infinity.

• It is also possible to restrict the events that are subject to count to match a particular filter first:

{"type":"user", "having":{"min":5, "max":10, "filter":{"type":"custom", "group":"action", "item":"purchase"}}}

• Additionally, it is possible to filter users by event-data cardinality, that is the number of distinct items associated with the given event group and the given user:

{"type":"user", "having":{"type":"event", "group":"deviceType", "min":2}}

This filter can also have a sub-filter:

{"type":"user", "having":{"type":"event", "group":"url", "min":5, "max":10, "filter":{"type":"keyword", "group":"pageclass", "item":"article"}}}

User identifier filter

Additionally, the user filter lets you specify a filtering predicate based on a user identifier. The Audience-specific user identifier type 'cx' is available together with customer-specific user identifiers registered through the addExternalId() or /profile/user/external/link/update call (see the explanation of user identity types). The results will then be limited to the user(s) specified in the filter.

{"type":"user", "group":"cx", "item":"cx:12837483788478722:123"}

For external user identifiers, the group needs to be set to the registered customer prefix, and the item is the customer specified identity. Given the user subscriber14 registed with "XYZ Company Account" (registered with identity type xyz - the same value as their registered customer prefix), then a filter to only aggregate based on that user's traffic would look like:

{"type":"user", "group":"xyz", "item":"subscriber14"}

User explosion filter

A user explosion filter expands the set of the events matched by the sub-filter to all other events from the same users. This is logically somewhat similar to a nested SELECT statement in SQL.

The user explosion logic supports two modes:

• The default allEvents mode selects all events from the users matching the sub-filter, set of sites and the period.

{"type":"explodeUsers", "filter":{"type":"custom", "group":"action", "item":"purchase"}}

In this terms, explodeUsers is equivalent to the following filter:

{"type":"user", "having":{"min":1, "filter":{"type":"custom", "group":"action", "item":"purchase"}}}

• The consecutiveEvents mode selects only those events that has happened after the filtering predicate is first satisfied (that is the first event matching the sub-filter).To Illustrate the difference, consider a filtering predicate that selects the events where Facebook was listed as a referrer, and the scenario where a given user visits your site, then leaves and goes to Facebook, and is then referred back to your site from Facebook. With the allEvents mode you would include all the events generated by that user within the selected time period, also before he/she left your site and went to Facebook. Whereas with the consecutiveEvents mode you would only include the events generated by that user that took place after he/she was referred back to your site.

{"type":"explodeUsers", "filter":{"type":"event", "group":"action", "item":"purchase"}, "mode":"consecutiveEvents"}

• The previousEvent mode selects only the event that has happened before the filtering predicate is first satisfied. A possible use case of this mode is to know which is the previous page a user visited before generating a conversion event.

{"type":"explodeUsers", "filter":{"type":"event", "group":"url", "item":"https://www.mywebsite.com/conversionpage.html"}, "mode":"previousEvent"}

• Similarly to previousEvent, the nextEvent mode selects <u>only</u> the event that happen after the filtering predicate is first satisfied.

{"type":"explodeUsers", "filter":{"type":"event", "group":"url", "item":"https://www.mywebsite.com/conversionpage.html"}, "mode":"nextEvent"}

User implosion filter

A user implosion filter reduces the set of the events matched by the sub-filter to only the first or last event for each user.

The user implosion logic supports two modes:

• For each user, the firstEvent mode selects the first event (in each time bucket) among the events matching the sub-filter, set of sites and the period.

{"type":"implodeUsers", "mode":"firstEvent", "buckets": 1, "filter":{"type":"custom", "group":"action", "item":"addToCart"}}

The default number of buckets is 1. Alternatively it is possible to use the filter without specifying a sub-filter and/or number of buckets:

{"type":"implodeUsers", "mode":"firstEvent"}

• For each user, the lastEvent mode selects the last event (in each time bucket) among the events matching the sub-filter, set of sites and the period.

{"type":"implodeUsers", "mode":"lastEvent", "buckets": 1, "filter":{"type":"custom", "group":"action", "item":"addToCart"}}

The default number of buckets is 1. Alternatively it is possible to use the filter without specifying a sub-filter and/or number of buckets:

{"type":"implodeUsers", "mode":"lastEvent"}

Session start, stop and bounce filter

Session filters allow to look at the events associated only with a session start, stop or bounce (both start and stop). Note however that for the events that have happened less than the 30 minutes ago (the session duration constrain), session stops and therefore bounce may not be known yet. For these, the filter may therefore return a different set of events when applied/executed some time later. Otherwise, the set of matching events will be fixed and event count will be equal to the values returned via sessionStarts, sessionStops and/or sessionBounces fields (depending on which filter was used).

{"type":"sessionStart"}

{"type":"sessionStop"}

{"type":"sessionBounce"}

These filters can further be combined with user having filters to for example put a predicate on the number of sessions the users have had:

{"type":"user", "having":{"min":5, "filter":{"type":"sessionStart"}}}

Time filter

A time filter allows to restrict a nested filter to a certain period of time by specifying a filter and start and/or stop time according to Traffic time specification. To support the case when filters lie outside of the aggregation period (i.e., the start and stop range specified to the request), we define the filtering period as the time period between the earliest specified start and the latest specified stop. This period applies to all filters, and the time filters lacking start or stop default to these values. For this reason, it is recommended to specify both start and stop, at least when operating with filters that are partially outside of the aggregation period.

{"type":"time", "start":"-2d", "filter":{"type":"event", "group":"deviceType", "item":"Mobile"}}

Alternatively, the time filter can be written without a subfilter, so it will match all events in the specified period. This can be useful when time filter itself is used inside a user explosion/having filter:

{"type":"time", "start":"-1M", "stop":"-1w"}

This filter can be user to filter over Local time of the user, based on their timezone. It can filter over range of local hours, range of local days, or a specific set of days of the week.

Hour Range

Filter with Hour Range will filter activities after 08:00 in the morning till 16:00 in the users local time.

{"type":"time", "startHour":8, "stopHour":16}

Or it can be used crossed day:

{"type":"time", "startHour":22, "stopHour":5}

This will filter the activities after 22:00 till midnight, and before 05:00 in the morning.

Day Range

Filter with Day Range will filter activities during the weekdays based on the users local time.

{"type":"time", "startDay":"Monday", "stopDay":"Friday"}

Or it can be used crossed week:

{"type":"time", "startDay":5, "stopDay":1}

This will filter the activities between 5th day of the week till the end of the week, and before 1st day of the next week.

Set of days

Filter over a specific set of days:

{"type":"time", "days":[2, 6]}

This will filter activities happened on the 2nd and the 6th day of the week.

Segment filter

A segment filter allows to specify predicates based on previously defined segments by segment id and mode.

• The default mode simply applies the filter from the segment definition, equivalent to copying the "filters" part and pasting it in this filter.

{"type":"segment", "item":"00abfe6d40e"}

This is equivalent to specifying "mode":"match" and it captures all the events that match the segment filter.

{"type":"segment", "mode":"match", "item":"00abfe6d40e"}

• Alternatively, "mode":"member" allows to match all events from users matching a particular segment.

{"type":"segment", "mode":"member", "item":"00abfe6d40e"}

• Finally, "mode":"lookalike" will match all events from users defined as a [lookalike](page://Lookalike Modeling: Theory and Practice) of the segment.

{"type":"segment", "mode":"lookalike", "item":"00abfe6d40e"}

Boolean filter

Boolean filters allow you to combine a collection of filters to yield a more complex, composite filters. You can form composite filters that involve any of the filter types listed above. Logical conjunctions (and), disjunctions (or) and negations (not) are supported.

{"type":"and", "filters":[
 {"type":"not", "filter":
 {"type":"event", "group":"referrerHost", "item":"abc.com"}
 },
 {"type":"not", "filter":
 {"type":"event", "group":"referrerHost", "item":"xyz.com"}
 }
]}

{"type":"not", "filter":
 {"type":"or", "filters":[
 {"type":"event", "group":"referrerHost", "item":"abc.com"},
 {"type":"event", "group":"referrerHost", "item":"xyz.com"}
 ]}
}

Context filter

A context filter ensures that a provided filter is executed inside a certain context mode, one of

• traffic

• dmp

• recs

• conversion

• propensity

The filter is optional, and omitting it allows you to match all events in a given context. An example is {"type":"context","mode":"propensity"}, matching all propensity events.

Site filter

A site filter allows you to specify a filtering predicate based on the site or site group. The filter will be independent of request context - if context is dmp, the filter will use dmp.site, if context is traffic, the filter will use history.site. This makes it fundamentally different from the event/site-filter, which will happen in the traffic context.

• Filter on sites:

{"type": "site", "siteIds": ["8097"]}

• Convenient alternative for a single site:

{"type": "site", "siteId": "8097"}

• Filter on site groups:

{"type": "site", "siteGroupIds": ["9087"]}

Convenient alternative for a single site group:

{"type": "site", "siteGroupId": "9087"}

Consent filter

A consent filter allows you to specify a filtering predicate based on the Consent given for the events. Read more about user consent in the GDPR section.

Example:

# Filter on events with consent to be used for user segmentation.
{"type": "consent", "purpose": ["segment"]}

Subnet Filter

A subnet filter allows you to specify a filtering predicate based on whether events originates from an internal or external subnet. The internal subnet masks need to be registered in the customer object, as internalIpMasks.

Example:

# Only external traffic
{"type": "subnet", "mode": "external"}

DMP filters

DMP filters allow you to express constraints on DMP performance events. More documentation here.

Recs event filter

Similar to Event filter or Dmp event filter, but for recs event (see /recs/traffic). The most popular items in each group can be listed using /recs/traffic/event.

• The basic form of this filter is as follows:

{"type":"recs-event", "group":"widget", "item":"widgetId123"}

Conversion event filter

Similar to Event filter or Dmp event filter, but for conversion events (see /conversion/traffic). The most popular items in each group can be listed using /conversion/traffic/event.

• The basic form of this filter is as follows:

{"type":"conversion-event", "group":"funnelStep", "item":"start"}

Propensity event filter

Similar to Event filter or Dmp event filter, but for propensity event (see /propensity/traffic). The most popular items in each group can be listed using /propensity/traffic/event.

• The basic form of this filter is as follows:

{"type":"propensity-event", "group":"type", "item":"SUBSCRIBE"}

Page filter

A page filter allows you to filter pages based on the number of events they receive. This filter uses a having clause with min and max parameters to select pages that have received a specific range of events.

• The basic form of this filter is as follows:

{"type":"page", "having":{"min":1000, "max":5000}}

The min parameter specifies the minimum number of events a page must have received to be included (must be at least 1000). The max parameter specifies the maximum number of events. If only min is specified, there is no upper limit.

• Filter for pages with at least 2000 events:

{"type":"page", "having":{"min":2000}}

• Filter for pages with between 1500 and 3000 events:

{"type":"page", "having":{"min":1500, "max":3000}}

Field parameter

You can optionally specify a field parameter to filter based on specific types of events rather than total page views:

• Filter pages based on session starts:

{"type":"page", "having":{"min":1000, "field":"sessionStarts"}}

• Filter pages based on session stops:

{"type":"page", "having":{"min":1500, "max":3000, "field":"sessionStops"}}

• Filter pages based on session bounces:

{"type":"page", "having":{"min":1000, "field":"sessionBounces"}}

• Filter pages based on page views (default behavior):

{"type":"page", "having":{"min":1000, "field":"events"}}

Valid values for the field parameter are:

• events (default) - filters based on total page view events

• sessionStarts - filters based on session start events

• sessionStops - filters based on session stop events

• sessionBounces - filters based on session bounce events

Composition filter

A filter comprised of composition nodes

• The basic form of this filter is as follows:

{"type":"composition, "tree": {
 "or": [
 {"segmentId": "id1"},
 {"segmentId": "id2"}
 ]
}}

Last updated: June 25, 2026