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 Do not send the event to the destination
sample 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.
allow_properties Allow properties 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.
drop_properties Drop properties 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 allow_properties and drop_properties 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
  2. sample
  3. allow_properties
  4. drop_properties

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.
  • Allow / Drop properties filters may target a maximum of 8 objects and each object may have a maximum of 64 fields in the allow or drop.
  • 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", "sample", "allow_properties", or "drop_properties". required

Action

Drop

The drop 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 action, this must be "drop". required

Sample

The sample 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 action, this must be "sample". 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.

Allow properties

The allow_properties 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 allow properties action, this must be "allow_properties". required
fields map of string → list of string 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 list of string that specifies which fields within the object to allow. Nested JSON objects not specified in this map will be untouched by this filter required

Drop properties

The drop_properties 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 drop properties action, this must be "drop_properties". required
fields map of string → list of string 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 list of string that specifies which fields within the object to drop. Nested JSON objects not specified in this map will be untouched by this filter required

Migrate from the Config API

Destination filter model

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

Action model differences

Type property

Config API Public API counterpart
drop_event drop
sample_event sample
whitelist_fields allow_properties
blacklist_fields drop_properties

Fields property

The type of fields property has been changed:

Config API Public API counterpart
map of string → Field List (see below) map of string → list of string

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.

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 ]
Example: fP7qoQw2HTWt9WdMr718gn
Request Body schema:
required
sourceId
required
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
required
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",
  • "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 ]
Example: fP7qoQw2HTWt9WdMr718gn
query Parameters
required
object (PaginationInput)

Pagination options.

This parameter exists in v1.

Example: pagination[count]=3
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/destination/{destinationId}/filters
Request samples
import { configureApis, unwrap } from '@segment/public-api-sdk-typescript'

const api = configureApis('/* Insert your Public API token here */')

try {
  const result = await unwrap(api.destinationFilters.listFiltersFromDestination('fP7qoQw2HTWt9WdMr718gn', { count: 3 }))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}

Get Filter in Destination

Gets a Destination filter by id.

Securitytoken
Request
path Parameters
destinationId
required
string [ 1 .. 255 ]
Example: fP7qoQw2HTWt9WdMr718gn
filterId
required
string [ 1 .. 255 ]
Example: xx6AySGeFExzdv2Gw2EuhV
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/destination/{destinationId}/filters/{filterId}
Request samples
import { configureApis, unwrap } from '@segment/public-api-sdk-typescript'

const api = configureApis('/* Insert your Public API token here */')

try {
  const result = await unwrap(api.destinationFilters.getFilterInDestination('fP7qoQw2HTWt9WdMr718gn', 'xx6AySGeFExzdv2Gw2EuhV'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
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 ]
Example: fP7qoQw2HTWt9WdMr718gn
filterId
required
string [ 1 .. 255 ]
Example: 2c0vbGYWOBwbKszg0F0CoLSS01b
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

delete/destination/{destinationId}/filters/{filterId}
Request samples
import { configureApis, unwrap } from '@segment/public-api-sdk-typescript'

const api = configureApis('/* Insert your Public API token here */')

try {
  const result = await unwrap(api.destinationFilters.removeFilterFromDestination('fP7qoQw2HTWt9WdMr718gn', '2c0vbGYWOBwbKszg0F0CoLSS01b'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
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 ]
Example: fP7qoQw2HTWt9WdMr718gn
filterId
required
string [ 1 .. 255 ]
Example: xx6AySGeFExzdv2Gw2EuhV
Request Body schema:
required
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
{
  • "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
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": {
    }
}