A Filter restricts a stream of messages on the server side so your client only sees what it’s interested in. Streams are currently the only way to use filters right now.

  "clauses": [
      "field": "/data/entities/hashtags/*/name",
      "object_type": "post",
      "operator": "matches",
      "value": "rollout"
  "id": "1",
  "match_policy": "include_any",
  "name": "Posts about rollouts",
  "owner": "...user object..."

Filter fields

Field Type Description
id string Primary identifier for a filter. This will be an integer, but it is always expressed as a string to avoid limitations with the way JavaScript integers are expressed.
name string An optional User assigned name for this filter.
clauses list A list of filter clauses to match against. Must be non-empty.
match_policy string How should the clauses be joined together? One of include_any, include_all, exclude_any, or exclude_all. For example, include_any will include a message if it matches any of the clauses and exclude_all will exclude a message if it matches all of the clauses. This allows either white- or blacklist filtering.
owner User object This is an embedded version of the User object. In certain cases (e.g., when a user account has been deleted), this key may be omitted.

Filter Clauses

Field Type Description
object_type string What type of object does this filter operate on? Must be one of post, star, user_follow, mute, block, stream_marker, message, channel, channel_subscription, token, file.
operator string How should field be matched against value.
Operator Description
equals Does field equal value.
matches Is the string value a substring of field.
lt Is the integer in field < value.
le Is the integer in fieldvalue.
gt Is the integer in field > value.
ge Is the integer in fieldvalue.
one_of Is the field an element in the list value.
field string A JSON Pointer string that specifies what part of the message we should match against.
value string, int, or list A string, integer, or list that the message's data is compared against. Some variables are also accepted.

Filter variables

Value Type Description
$authorized_userids list A list of the current user ids who have authorized the App that is using this filter in a stream. Since this is a list, make sure you use the one_of operator with this variable.

JSON Pointer

We use a slightly modified version of the JSON Pointer standard to specify which part of a message we should filter against. According to the spec:

JSON Pointer defines a string syntax for identifying a specific value within a JSON document.

For instance, in the message:

  "data": {
    "canonical_url": "",
    "created_at": "2012-10-11T19:48:40Z",
    "entities": {
      "hashtags": [
          "len": 8,
          "name": "adnhack",
          "pos": 90
      "links": [
          "len": 29,
          "pos": 100,
          "text": "",
          "url": ""
      "mentions": [

    "html": "<span itemscope=\"\">If you're in San Francisco on Saturday October 20 and Sunday October 21 come to the first <span data-hashtag-name=\"adnhack\" itemprop=\"hashtag\">#adnhack</span> => <a href=\"\"></a></span>",
    "id": "914440",
    "machine_only": false,
    "num_replies": 1,
    "num_reposts": 3,
    "num_stars": 3,
    "source": {
      "client_id": "caYWDBvjwt2e9HWMm6qyKS6KcATHUkzQ",
      "link": "",
      "name": "Alpha"
    "text": "If you're in San Francisco on Saturday October 20 and Sunday October 21 come to the first #adnhack =>",
    "thread_id": "914440",
    "user": "...user object...",
    "you_reposted": false,
    "you_starred": false
  "meta": {
    "code": 200
  • /data/source/client_id = “caYWDBvjwt2e9HWMm6qyKS6KcATHUkzQ”
  • /data/entities/hashtags/0/name = “adnhack”
  • /data/num_replies = 1

We extend JSON pointer slightly to allow all the elements of a list to match. For example, to answer the question “Does this post contain the hashtag ‘rollout’”, you’d use a field selector like /data/entities/hashtags/*/name. Following the JSON Pointer spec, if you’d like to encode a literal * you can use ~2 instead.

Description Method Path Token
Create a Filter POST /filters User
Retrieve a Filter GET /filters/{filter_id} User
Update a Filter PUT /filters/{filter_id} User
Delete a Filter DELETE /filters/{filter_id} User
Get the current User's Filters GET /filters User
Delete the current User's Filters DELETE /filters User