Destination Filters

The Destination Filters API provides fine-grained controls that allow you to conditionally prevent data delivery to specific destinations. You can filter entire events (for example, selectively drop them) or block/allow individual fields in events before you send them. You can conditionally apply filters to each event based on the contents of that event’s payload. For example, you could apply a filter to Track events with a plan property equal to Professional, or you could apply a filter to events with a user email address that does not match *@example.com.

Use cases

Use Destination Filters to:

  • Reduce the delivery volume of events to a Destination to save on costs
  • Filter out Personally Identifying Information (PII) from the events sent to a Destination that shouldn't receive or store PII
  • Prevent internal user activity from reaching an analytics tool
  • Send the events that you care about to an custom webhook

Availability

Destination Filters are available to all Business customers and support cloud-based (server-side) and web device-mode destinations. Mobile device-mode destinations are in beta and only support Swift, Kotlin, and React Native 2.0 libraries. S3 and Warehouse Destinations are not yet supported.

Types of filters

There are three filters that can be applied to events:

Type Action
drop_event Do not send the event to the destination
sample_event Send only a percentage of events through to the destination. You can optionally sample based on a field. For example, you can sample 10% of users by sampling on userId instead of a random 10% of all events, which is the default.
whitelist_fields Whitelist fields in the event by specifying nested JSON objects (for example, context, properties.productDetails, etc.) and a list of fields that should be retained in that nested object, with all others dropped before the event is sent to the destination.
blacklist_fields Blacklist fields in the event by specifying nested JSON objects (for example, context, properties.productDetails, etc.) and a list of fields to drop from those nested objects before the event is sent to the destination.

The whitelist_fields and blacklist_fields filters may only filter fields inside the following top-level fields of Segment events:

  • properties
  • context
  • traits

Filter order

Filters are applied in the following order for each event:

  1. drop_event
  2. sample_event
  3. whitelist_fields
  4. blacklist_fields

Conditional filters

Filters can optionally be applied to an event by writing an "if" statement using Filter Query Language ("FQL"), Segment’s simple query language for streaming JSON. FQL statements evaluate to true or false based on the contents of each event, allowing you to only apply filters to specific events.

For example, given the following event payload:

{
  "event": "Button Clicked",
  "type": "track",
  "context": {
    "library": {
      "name": "analytics.js",
      "version": "1.0",
    }
  }
}

The following FQL statements will evaluate to "true", causing the filter to be applied:

  • event = 'Button Clicked'
  • event = 'Button Clicked' and type = 'track'
  • match(context.library.version, '1.*')
  • type = 'identify' or type = 'track'

And the following FQL statements will evaluate to "false", causing the filter to be skipped:

  • event = 'Screen Tapped'
  • context.path.path = '/login'
  • match (context.library.version, '2.*')

For more detailed documentation including a list of all operators and functions, see the FQL Documentation.

Universal filters

To apply a filter to all events going to a destination, you can supply an "if" statement of "all". All actions in that filter will be applied to events before being delivered to that destination.

Limits

Destination Filters currently have the following limits:

  • Each Destination may have no more than 10 filters.
  • FQL "if" statements may be a maximum of 3Kb in size.
  • Filters may have a maximum of 4 actions.
  • Whitelist / blacklist fields filters may target a maximum of 8 objects and each object may have a maximum of 64 fields in the whitelist or blacklist.
  • The Preview API "input" payload may be a maximum of 128Kb.

If you would like any of these limits lifted, please reach out to Segment at friends@segment.com.

API models

Filter

Attribute Type Description
name string The URL path of this filter. read-only
enabled boolean Whether or not this filter should be active.
title string A human-readable title for this filter.
description string A longer human-readable description of this filter.
if string A FQL statement that causes this filter’s action to be applied if it evaluates to true. "all" will cause the filter to be applied to all events required
actions []action The filtering action to take on events that match the "if" statement. Must be one of: "drop_event", "whitelist_fields", or "blacklist_fields". required

Action

Drop event

The drop_event action will cause the event to be dropped and not sent to the destination if the "if" statement evaluates to true.

Attribute Type Description
type string The action name. For the drop event action, this must be "drop_event". required

Sample event

The sample_event action will allow only a percentage of events through. It can sample randomly or, if given a path attribute, it can sample a percentage of events based on the contents of a field. This is useful for sampling all events for a percentage of users rather than a percentage of all events for all users.

Attribute Type Description
type string The action name. For the sample event action, this must be "sample_event". required
percent float A percentage in the range [0.0, 1.0] that determines the percent of events to allow through. 0.0 will allow no events and 1.0 will allow all events. The default is 0.0. required
path string If non-empty, events will be sampled based on the value at this path. For example, if path is userId, a percentage of users will have their events allowed through to the destination.

Whitelist fields

The whitelist_fields action takes a list of nested objects (for example, context, properties.orderDetails) and a list of fields for each object that should be allowed, with all other fields in those objects dropped.

Attribute Type Description
type string The action name. For the whitelist fields action, this must be "whitelist_fields". required
fields map of string → Field List A map of nested JSON objects that should have their properties filtered. The map key is the path to the nested JSON object (for example, context.ip, properties, etc.) and the value is a field list object (see below) that specifies which fields within the object to allow. Nested JSON objects not specified in this map will be untouched by this filter required

Blacklist fields

The blacklist_fields action takes a list of nested objects (for example, context, properties.orderDetails) and a list of fields for each object that should be dropped, with all other fields in those objects untouched.

Attribute Type Description
type string The action name. For the blacklist fields action, this must be "blacklist_fields". required
fields map of string → Field List A map of nested JSON objects that should have their properties filtered. The map key is the path to the nested JSON object (for example, context.ip, properties, etc.) and the value is a field list object (see below) that specifies which fields within the object to drop. Nested JSON objects not specified in this map will be untouched by this filter required

Field list

Attribute Type Description
fields []string One or more JSON object field names. Nested fields (that is, dot-separated field names) are not supported.

Migrate from the Config API

Config API field Public API counterpart
name Use the id field instead
enabled enabled
title title
description description
if if
actions actions

To migrate, replace any usages of the Config API endpoints with the Segment Public API counterparts, using the field mappings in the table above.

Create Filter for Destination

Creates a filter in a Destination.

When called, this endpoint may generate the Destination Filter Created event in the audit trail.

Securitytoken
Request
path Parameters
destinationId
required
string [ 1 .. 255 ]
Request Body schema:
sourceId
string (sourceId)

The id of the Source associated with this filter.

if
required
string (if)

The filter's condition.

required
Array of objects (actions)

Actions for the Destination filter.

title
string (title)

The title of the filter.

description
string (description)

The description of the filter.

enabled
required
boolean (enabled)

When set to true, the Destination filter is active.

Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

post/destination/{destinationId}/filters
Request samples
{
  • "sourceId": "rh5BDZp6QDHvXFCkibm1pR",
  • "destinationId": "fP7qoQw2HTWt9WdMr718gn",
  • "title": "Filter \"Identify\" events",
  • "description": "Drop Identify tracking from this destination",
  • "if": "type = \"identify\"",
  • "actions": [
    ],
  • "enabled": true
}
Response samples
{
  • "data": {
    }
}

List Filters from Destination

Lists filters for a Destination.

Securitytoken
Request
path Parameters
destinationId
required
string [ 1 .. 255 ]
query Parameters
required
object (PaginationInput)

Pagination options.

This parameter exists in v1.

Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/destination/{destinationId}/filters
Request samples
Response samples
{
  • "data": {
    }
}

Get Filter in Destination

Gets a Destination filter by id.

Securitytoken
Request
path Parameters
destinationId
required
string [ 1 .. 255 ]
filterId
required
string [ 1 .. 255 ]
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/destination/{destinationId}/filters/{filterId}
Request samples
Response samples
{
  • "data": {
    }
}

Remove Filter from Destination

Deletes a Destination filter.

When called, this endpoint may generate the Destination Filter Deleted event in the audit trail.

Securitytoken
Request
path Parameters
destinationId
required
string [ 1 .. 255 ]
filterId
required
string [ 1 .. 255 ]
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

delete/destination/{destinationId}/filters/{filterId}
Request samples
Response samples
{
  • "data": {
    }
}

Update Filter for Destination

Updates a filter in a Destination.

When called, this endpoint may generate one or more of the following audit trail events:

  • Destination Filter Enabled
  • Destination Filter Disabled
Securitytoken
Request
path Parameters
destinationId
required
string [ 1 .. 255 ]
filterId
required
string [ 1 .. 255 ]
Request Body schema:
if
string (if)

The FQL if condition to update.

Array of objects (actions)

Actions for this Destination filter.

title
string (title)

The title to update.

description
string or null (description)

The description of this filter.

enabled
boolean (enabled)

When set to true, this Destination filter is active.

Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

patch/destination/{destinationId}/filters/{filterId}
Request samples
{
  • "filterId": "xx6AySGeFExzdv2Gw2EuhV",
  • "destinationId": "fP7qoQw2HTWt9WdMr718gn",
  • "if": "!(type = \"track\")",
  • "actions": [
    ],
  • "title": "Allow Track",
  • "description": "Allows track calls through to the destination.",
  • "enabled": true
}
Response samples
{
  • "data": {
    }
}

Preview Destination Filter

Simulates the application of a Destination filter to a provided JSON payload.

Securitytoken
Request
Request Body schema:
required
object (filter)

The filter to preview.

required
object (payload)

The JSON payload to apply the filter to.

Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

post/destination/filters/preview
Request samples
{
  • "filter": {
    },
  • "payload": {
    }
}
Response samples
{
  • "data": {
    }
}