Activity Feeds v3 is in beta — try it out!

Activity selectors

Activity selectors give you control over which data is shown in a feed. For example you can decide to show only popular activities, or activities that fit the current user’s interests.

Each activity selector selects the first 1000 activities that match its selection criteria.

This page details what kind of activity selectors are supported by the Stream API, and how can you configure them.

You can create custom feed groups or update the built-in groups with your own activity selector configuration.

Selector types

Current Feed Selector

Shows activities from the current feed. This is the selector used when reading a user feed.

Parameters

Name	Type	Description	Default	Required
`sort`	array, see Sort	Sort options	Newest first	No
`filter`	object, see Filter	Additional filter conditions	-	No
`cutoff_window`	string, duration like `2h` or `5d`	Activities older than this window won’t be selected	`7d` (last 7 days)	No

Scope

The feed we’re currently reading

Example

const response = await client.feeds.createFeedGroup({
  id: "myid",
  activity_selectors: [
    {
      type: "current_feed",
      // Optionally provide cutoff window
      cutoff_window: "10d",
    },
  ],
});

activitySelector := getstream.ActivitySelectorConfig{
  Type:             getstream.PtrTo("current_feed"),
  // Optionally provide cutoff window
  CutoffWindow: getstream.PtrTo("10d"),
}

request := &getstream.CreateFeedGroupRequest{
  ID:                "myid",
  ActivitySelectors: []getstream.ActivitySelectorConfig{activitySelector},
}

ctx := context.Background()
response, err := client.Feeds().CreateFeedGroup(ctx, request)
if err != nil {
  log.Fatal("Error creating feed group:", err)
}

$createResponse = $feedsClient->createFeedGroup(
    new GeneratedModels\CreateFeedGroupRequest(
        id: "myid",
        activitySelectors: [
            new GeneratedModels\ActivitySelectorConfig(
                type: "current_feed",
                cutoffWindow: "10d"
            )
        ]
    )
);

var createResponse = await _feedsV3Client.CreateFeedGroupAsync(new CreateFeedGroupRequest
{
    ID = feedGroupId,
    DefaultVisibility = "public",
    ActivityProcessors = new List<ActivityProcessorConfig>
    {
        new() { Type = "default" }
    }
});

create_response = self.client.feeds.create_feed_group(
    id= feed_group_id,
    default_visibility= "public",
)

Following Feed Selector

Shows activities from feeds the current feed follows. This is the selector used when reading a timeline feed.

Parameters

Name	Type	Description	Default	Required
`sort`	array, see Sort	Sort options	Newest first	No
`filter`	object, see Filter	Additional filter conditions	-	No
`cutoff_window`	string, duration like `2h` or `5d`	Activities older than this window won’t be selected	`7d` (last 7 days)	No

Scope

Feeds followed by the feed we’re currently reading

Example

const response = await client.feeds.createFeedGroup({
  id: "myid",
  activity_selectors: [
    {
      type: "following",
      // Optionally provide cutoff window
      cutoff_window: "10d",
    },
  ],
});

activitySelector := getstream.ActivitySelectorConfig{
  Type:             getstream.PtrTo("following"),
  // Optionally provide cutoff window
  CutoffWindow: getstream.PtrTo("10d"),
}

request := &getstream.CreateFeedGroupRequest{
  ID:                "myid",
  ActivitySelectors: []getstream.ActivitySelectorConfig{activitySelector},
}

ctx := context.Background()
response, err := client.Feeds().CreateFeedGroup(ctx, request)
if err != nil {
  log.Fatal("Error creating feed group:", err)
}

$createResponse = $feedsClient->createFeedGroup(
    new GeneratedModels\CreateFeedGroupRequest(
        id: "myid",
        activitySelectors: [
            new GeneratedModels\ActivitySelectorConfig(
                type: "following",
                cutoffWindow: "10d"
            )
        ]
    )
);

var createResponse = await _feedsV3Client.CreateFeedGroupAsync(new CreateFeedGroupRequest
{
    ID = feedGroupId,
    DefaultVisibility = "public",
    ActivityProcessors = new List<ActivityProcessorConfig>
    {
        new() { Type = "default" }
    }
});

create_response = self.client.feeds.create_feed_group(
    id= feed_group_id,
    default_visibility= "public",
)

Popular Activity Selector

Selects popular activities from public and visible feeds.

Popularity is computed by the following formula:

activity.popularity = reactions + comments * 2 + bookmarks * 3 + shares * 3;

Parameters

Name	Type	Description	Default	Required
`sort`	array, see Sort	Sort options	Newest first	No
`filter`	object, see Filter	Additional filter conditions	-	No
`cutoff_window`	string, duration like `2h` or `5d`	Activities older than this window won’t be selected	`7d` (last 7 days)	No

Scope

Any feed with public or visible visibility level.

const response = await client.feeds.createFeedGroup({
  id: "myid",
  activity_selectors: [
    {
      type: "popular",
      // Optional parameters
      min_popularity: 70,
      cutoff_window: "10d",
    },
  ],
});

activitySelector := getstream.ActivitySelectorConfig{
  Type:             getstream.PtrTo("popular"),
  // Optional parameters
  CutoffWindow:     getstream.PtrTo("10d"),
  MinPopularity:    getstream.PtrTo(70),
}

request := &getstream.CreateFeedGroupRequest{
  ID:                "myid10",
  ActivitySelectors: []getstream.ActivitySelectorConfig{activitySelector},
}

ctx := context.Background()
response, err := client.Feeds().CreateFeedGroup(ctx, request)
if err != nil {
  log.Fatal("Error creating feed group:", err)
}

$createResponse = $feedsClient->createFeedGroup(
    new GeneratedModels\CreateFeedGroupRequest(
        id: "myid",
        activitySelectors: [
            new GeneratedModels\ActivitySelectorConfig(
                type: "popular",
                minPopularity: 70,
                cutoffWindow: "10d"
            )
        ]
    )
);

var createResponse = await _feedsV3Client.CreateFeedGroupAsync(new CreateFeedGroupRequest
{
    ID = feedGroupId,
    DefaultVisibility = "public",
    ActivityProcessors = new List<ActivityProcessorConfig>
    {
        new() { Type = "default" }
    }
});

create_response = self.client.feeds.create_feed_group(
    id= feed_group_id,
    default_visibility= "public",
)

Proximity Activity Selector

Shows activities based on geographic proximity

Parameters

Name	Type	Description	Default	Required
`sort`	array, see Sort	Sort options	Newest first	No
`filter`	object, see Filter	Additional filter conditions	-	No
`cutoff_window`	string, duration like `2h` or `5d`	Activities older than this window won’t be selected	`7d` (last 7 days)	No
`min_popularity`	number (only positive numbers are accepted)	Minimum popularity an activity should have to be selected	`0`	No

Scope

The feed we’re currently reading

Example

// Provide filter when reading the feed
await feed.getOrCreate({
  filter: {
    within_bounds: {
      $eq: {
        ne_lat: 52.43017,
        ne_lng: 4.924821,
        sw_lat: 52.334272,
        sw_lng: 4.822116,
      },
    },
    // Optionally provide other filter properties, just like when querying activities
    activity_type: "hike",
  },
});

// Use either within_bounds or near filter
await feed.getOrCreate({
  filter: {
    near: { $eq: { lat: 52.373558, lng: 4.885261, distance: 10 } },
  },
});

// You can omit filter if location is set for user
const me = client.state.getLatestValue().connected_user;
await client.updateUsersPartial({
  users: [
    {
      id: me.id,
      set: {
        lat: 52.373558,
        lng: 4.885261,
      },
    },
  ],
});

await feed.getOrCreate({
  // If filter is not provided, but feed group has proximity selector, API searches based on user's location
});

const response = await client.feeds.createFeedGroup({
  id: "myid",
  activity_selectors: [
    {
      type: "proximity",
      // Optional parameters
      min_popularity: 40,
      cutoff_window: "1d",
    },
  ],
});

// Provide filter when reading the feed
await feed.getOrCreate({
  filter: {
    within_bounds: {
      $eq: {
        ne_lat: 52.43017,
        ne_lng: 4.924821,
        sw_lat: 52.334272,
        sw_lng: 4.822116,
      },
    },
  },
  user_id: "<user id>",
});

// Use either within_bounds or near filter
await feed.getOrCreate({
  filter: {
    near: { $eq: { lat: 52.373558, lng: 4.885261, distance: 10 } },
  },
  user_id: "<user id>",
});

activitySelector := getstream.ActivitySelectorConfig{
  Type:             getstream.PtrTo("proximity"),
  // Optional parameters
  CutoffWindow:     getstream.PtrTo("1d"),
  MinPopularity:    getstream.PtrTo(40),
}

request := &getstream.CreateFeedGroupRequest{
  ID:                "myid",
  ActivitySelectors: []getstream.ActivitySelectorConfig{activitySelector},
}

// Create the feed group
ctx := context.Background()
response, err := client.Feeds().CreateFeedGroup(ctx, request)
if err != nil {
  log.Fatal("Error creating feed group:", err)
}

// Reading feed
ctx := context.Background()
feed := client.Feeds().Feed("user", "john")
response, err := feed.GetOrCreate(ctx, &getstream.GetOrCreateFeedRequest{
  Filter:  map[string]any{
    "within_bounds": map[string]any{
      "$eq": map[string]any{
        "ne_lat": 52.43017,
        "ne_lng": 4.924821,
        "sw_lat": 52.334272,
        "sw_lng": 4.822116,
      },
    },
  },
  UserID:  getstream.PtrTo("john"),
})
if err != nil {
  log.Fatal("Error:", err)
}

response, err = feed.GetOrCreate(ctx, &getstream.GetOrCreateFeedRequest{
  Filter:  map[string]any{
    "near": map[string]any{
      "$eq": map[string]any{
        "lat":      52.373558,
        "lng":      4.885261,
        "distance": 10,
      },
    },
  },
  UserID:  getstream.PtrTo("john"),
})

if err != nil {
  log.Fatal("Error:", err)
}

$createResponse = $feedsClient->createFeedGroup(
    new GeneratedModels\CreateFeedGroupRequest(
        id: "myid",
        activitySelectors: [
            new GeneratedModels\ActivitySelectorConfig(
                type: "proximity",
                minPopularity: 40,
                cutoffWindow: "1d",
            )
        ]
    )
);

// Provide filter when reading the feed
$feedResponse = $feedsClient->getOrCreateFeed(
    "myid",
    "user123",
    new GeneratedModels\GetOrCreateFeedRequest(
        filter: (object)[
            'within_bounds' => (object)[
                '$eq' => (object)[
                    'ne_lat' => 52.43017,
                    'ne_lng' => 4.924821,
                    'sw_lat' => 52.334272,
                    'sw_lng' => 4.822116,
                ]
            ]
        ],
        userID: "user123"
    )
);

// Use either within_bounds or near filter
$feedResponse2 = $feedsClient->getOrCreateFeed(
    "myid",
    "user123",
    new GeneratedModels\GetOrCreateFeedRequest(
        filter: (object)[
            'near' => (object)[
                '$eq' => (object)[
                    'lat' => 52.373558,
                    'lng' => 4.885261,
                    'distance' => 10
                ]
            ]
        ],
        userID: "user123"
    )
);

var createResponse = await _feedsV3Client.CreateFeedGroupAsync(new CreateFeedGroupRequest
{
    ID = feedGroupId,
    DefaultVisibility = "public",
    ActivityProcessors = new List<ActivityProcessorConfig>
    {
        new() { Type = "default" }
    }
});

create_response = self.client.feeds.create_feed_group(
    id= feed_group_id,
    default_visibility= "public",
)

Interest Activity Selector

Selects activities that match the logged-in user’s interests. Interests are automatically calculated for each user by Stream API based on which activities the user interacts with.

Interests are based on activity topics. Topics are stored in the interest_tags field of an activity. It can be computed automatically using activity processors or set when creating an activity.

Parameters

Name	Type	Description	Default	Required
`sort`	array, see Sort	Sort options	Newest first	No
`filter`	object, see Filter	Additional filter conditions	-	No
`cutoff_window`	string, duration like `2h` or `5d`	Activities older than this window won’t be selected	`7d` (last 7 days)	No
`min_popularity`	number (only positive numbers are accepted)	Minimum popularity an activity should have to be selected	`0`	No

Scope

Feeds that are visible to the logged-in user.

Examples

const response = await client.feeds.createFeedGroup({
  id: "myid",
  activity_selectors: [
    {
      type: "interest",
      // Optional parameters
      sort: [{ field: "popularity", direction: -1 }],
      filter: {
        activity_type: "post",
      },
    },
  ],
});

response, err := client.Feeds().CreateFeedGroup(context.Background(), &getstream.CreateFeedGroupRequest{
  ID: "myid",
  ActivitySelectors: []getstream.ActivitySelectorConfig{
    {
      Type: getstream.PtrTo("interest"),
      // Optional parameters
      Sort: []getstream.SortParam{
        {
          Field:     getstream.PtrTo("popularity"),
          Direction: getstream.PtrTo(-1),
        },
      },
      Filter: map[string]any{
        "activity_type": "post",
      },
    },
  },
})
if err != nil {
  log.Fatal("Error creating feed group:", err)
}

$createResponse = $feedsClient->createFeedGroup(
    new GeneratedModels\CreateFeedGroupRequest(
        id: "myid",
        activitySelectors: [
            new GeneratedModels\ActivitySelectorConfig(
                type: "interest",
                sort: [
                    ['field' => 'popularity', 'direction' => -1]
                ],
                filter: (object)[
                    'activity_type' => 'post'
                ]
            )
        ]
    )
);

var createResponse = await _feedsV3Client.CreateFeedGroupAsync(new CreateFeedGroupRequest
{
    ID = feedGroupId,
    DefaultVisibility = "public",
    ActivityProcessors = new List<ActivityProcessorConfig>
    {
        new() { Type = "default" }
    }
});

create_response = self.client.feeds.create_feed_group(
    id= feed_group_id,
    default_visibility= "public",
)

Query Activity Selector

Selects activities using the provided filter query.

Parameters

Name	Type	Description	Default	Required
`sort`	array, see Sort	Sort options	Newest first	No
`filter`	object, see Filter	Additional filter conditions	-	No
`cutoff_window`	string, duration like `2h` or `5d`	Activities older than this window won’t be selected	`7d` (last 7 days)	No

Scope

Feeds that are visible to the logged-in user.

Example

const response = await client.feeds.createFeedGroup({
  id: "myid",
  activity_selectors: [
    {
      type: "query",
      filter: { search_data: { $contains: { workout_type: "hike" } } },
      // Optional parameters
      sort: [{ field: "created_at", direction: -1 }],
    },
  ],
});

response, err := client.Feeds().CreateFeedGroup(context.Background(), &getstream.CreateFeedGroupRequest{
  ID: "myid",
  ActivitySelectors: []getstream.ActivitySelectorConfig{
    {
      Type: getstream.PtrTo("query"),
      Filter: map[string]any{
        "search_data": map[string]any{
          "$contains": map[string]any{
            "workout_type": "hike",
          },
        },
      },
      // Optional parameters
      Sort: []getstream.SortParam{
        {
          Field:     getstream.PtrTo("created_at"),
          Direction: getstream.PtrTo(-1),
        },
      },
    },
  },
})
if err != nil {
  log.Fatal("Error creating feed group:", err)
}

$createResponse = $feedsClient->createFeedGroup(
    new GeneratedModels\CreateFeedGroupRequest(
        id: "myid",
        activitySelectors: [
            new GeneratedModels\ActivitySelectorConfig(
                type: "query",
                filter: (object)[
                    'search_data' => (object)[
                        '$contains' => (object)[
                            'workout_type' => 'hike'
                        ]
                    ]
                ],
                sort: [
                    ['field' => 'created_at', 'direction' => -1]
                ]
            )
        ]
    )
);

var createResponse = await _feedsV3Client.CreateFeedGroupAsync(new CreateFeedGroupRequest
{
    ID = feedGroupId,
    DefaultVisibility = "public",
    ActivityProcessors = new List<ActivityProcessorConfig>
    {
        new() { Type = "default" }
    }
});

create_response = self.client.feeds.create_feed_group(
    id= feed_group_id,
    default_visibility= "public",
)

Selector parameters

Supported values for sort and filter objects.

Sort

The following sort options are available:

Fields:

created_at
popularity

Direction: 1 or -1

Filters

The following filter options are available for the current, popular, interest, proximity and query selectors:

name	type	description	supported operations	example
`id`	string or list of strings	The ID of the activity	`$in`, `$eq`	`{ id: { $in: [ 'abc', 'xyz' ] } }`
`activity_type`	string or list of strings	The type of the activity	`$in`, `$eq`	`{ activity_type: { $in: [ 'abc', 'xyz' ] } }`
`user_id`	string or list of strings	The ID of the user who created the activity	`$in`, `$eq`	`{ user_id: { $in: [ 'abc', 'xyz' ] } }`
`text`	string	The text content of the activity	`$eq`, `$q`, `$autocomplete`	`{ text: { $q: 'popularity' } }`
`search_data`	object	The extra metadata for search indexing	`$contains`, `$path_exists`	`{ search_data: { $contains: { 'category': 'sports', 'status': 'active' } } }`
`interest_tags`	list of strings	Tags for user interests	`$eq`, `$contains`	`{ interest_tags: { $in: [ 'sports', 'music' ] } }`
`filter_tags`	list of strings	Tags for filtering	`$eq`, `$contains`	`{ filter_tags: { $in: [ 'categoryA', 'categoryB' ] } }`
`created_at`	string, must be formatted as an RFC3339 timestamp	The time the activity was created	`$eq`, `$gt`, `$lt`, `$gte`, `$lte`	`{ created_at: { $gte: '2023-12-04T09:30:20.45Z' } }`
`popularity`	number	The popularity score of the activity	`$eq`, `$ne`, `$gt`, `$lt`, `$gte`, `$lte`	`{ popularity: { $gte: 70 } }`
`near`	object	Indicates the GEO point to search nearby activities	`$eq`	`{ near: { $eq: { lat: 40.0, lng: -74.0, distance: 200 } } }`
`within_bounds`	object	Indicates the GEO bounds to search for activities within	`$eq`	`{ within_bounds: { $eq: { ne_lat: 40.0, ne_lng: -115.0, sw_lat: 32.0, sw_lng: -125.0 } } }`

The following filter options are available for the following selector:

name	type	description	supported operations	example
`id`	string or list of strings	The ID of the activity	`$in`, `$eq`	`{ id: { $in: [ 'abc', 'xyz' ] } }`
`filter_tags`	list of strings	Tags for filtering	`$eq`, `$contains`	`{ filter_tags: { $in: [ 'categoryA', 'categoryB' ] } }`

Combining selectors

You can combine multiple selectors. The example below will include:

popular activities from public and visible feeds
activities from feeds the user follows
activities from feeds the user has access to, and match the user’s interest

Each activity selector selects the first 1000 activities that match its selection criteria. We suggest taking adventage of the different config options for the selectors to make sure that the selectors return the most relevant activities. When combining selectors, every selector runs independently, so in this case 3 * 1000 activities can be selected.

Once selectors run, ranking is applied to the activities that are returned by the selectors. Even if you have multiple selectors, ranking only runs once.

const response = await client.feeds.createFeedGroup({
  id: "myid",
  activity_selectors: [
    { type: "popular" },
    { type: "following" },
    { type: "interest" },
  ],

  ranking: { type: "expression", score: "decay_linear(time) * popularity" },
});

response, err := client.Feeds().CreateFeedGroup(context.Background(), &getstream.CreateFeedGroupRequest{
  ID: "myid",
  ActivitySelectors: []getstream.ActivitySelectorConfig{
    {
      Type: getstream.PtrTo("popular"),
    },
    {
      Type: getstream.PtrTo("following"),
    },
    {
      Type: getstream.PtrTo("interest"),
    },
  },
  Ranking: &getstream.RankingConfig{
    Type: getstream.PtrTo("expression"),
    Score: getstream.PtrTo("decay_linear(time) * popularity"),
  },
})
if err != nil {
  log.Fatal("Error creating feed group:", err)
}

$createResponse = $feedsClient->createFeedGroup(
    new GeneratedModels\CreateFeedGroupRequest(
        id: "myid",
        activitySelectors: [
            new GeneratedModels\ActivitySelectorConfig(
                type: "popular"
            ),
            new GeneratedModels\ActivitySelectorConfig(
                type: "following"
            ),
            new GeneratedModels\ActivitySelectorConfig(
                type: "interest"
            )
        ],
        ranking: new GeneratedModels\RankingConfig(
            type: "expression",
            score: "decay_linear(time) * popularity"
        )
    )
);

var createResponse = await _feedsV3Client.CreateFeedGroupAsync(new CreateFeedGroupRequest
{
    ID = feedGroupId,
    DefaultVisibility = "public",
    ActivityProcessors = new List<ActivityProcessorConfig>
    {
        new() { Type = "default" }
    }
});

create_response = self.client.feeds.create_feed_group(
    id= feed_group_id,
    default_visibility= "public",
)

Experimenting with selectors

Feed groups let you define what activities should be included in the feed and the ranking to sort these activities.

By default all feeds in the given group will have the same settings. However, you might want to experiment with different selectors and rankings. Feed views let you do that by overriding the group’s default settings.

Note that any write operation to feed groups/views can take up to 30 seconds to propagate to all API nodes.

Ranking

Notification Feeds