Aggregated Feeds – Demystified

3 min read
Thierry S.
Thierry S.
Published September 30, 2016 Updated February 9, 2022

Our team has been hard at work to make aggregated feeds easier to use. This blog post will dive into more detail and help you get your aggregated feeds up and running. If you're looking for something more interactive, also check out this 5 minute interactive tutorial.

When to Use Aggregated Feeds

You should use aggregation if you want to group similar activities together in a feed. Here are some examples of what you can achieve:

  • Alex and 35 others wrote on John's wall for his birthday
  • Nick liked 24 pictures
  • Ian, John and 3 others liked your picture

Aggregated feeds are sorted by the “updated_at” field of the aggregated activity. This allows you to bring a conversation back to the top of the feed.

How Aggregation Works

Aggregation on Stream works in 3 steps. 1: You insert an activity into an aggregated feed. Node.js Example:

var stream = require('getstream')
var client = stream.connect(key, secret)
chris = client.feed('timeline_aggregated', 'chris')
  actor: 'chris',
  verb: 'like',
  object: 'picture:10'

2: The aggregation format is applied You can define an aggregation format for timeline_aggregated in the dashboard. The example aggregation format below aggregates the feed based on the combination of actor and verb.

{{ actor }}_{{ verb.infinitive }}

When an activity is inserted Stream will apply the aggregation format. The above activity will be assigned the group "chris_like". 3: Activities with the same group are grouped together If Chris likes multiple pictures, all of his activities will have the same value for the group. (chris_like). All the activities with the group value “chris_like” will end up in the same group. You can confirm this by reading the aggregated feed:

var stream = require('getstream')
var client = stream.connect(key, secret)
chris = client.feed('timeline_aggregated', 'chris')
chris.get({'limit': 10}).then(function(response) {
    response.results.forEach(function(aggregatedActivity) {

Note: As you can see from this explanation and the diagram below, the aggregation format is applied at write time. If you make changes to the aggregation format they will only affect activities inserted in the future and not historical data.

Aggregation format explained

You can build complex logic with the aggregation format. Here are some more advanced aggregation formats:

Example 1

Aggregate activities with the same actor, verb id and day:

{{ actor }}_{{ }}_{{ time.strftime("%Y-%m-%d") }}

IE. Alex liked 3 pictures

Example 2

Per target, verb id and day:

{{ target }}_{{ }}_{{ time.strftime("%Y-%m-%d") }}

IE. Alex, John and 3 others liked your picture

Example 3

Use an if statement to group follow activities by actor, but other activities by target.

{% if verb.infinitive == 'follow' %}{{ actor }}{% else %}{{ target }}{% endif %}_{{ }}_{{ time.strftime("%Y-%m-%d") }}

For exmaple:

  • Chris followed 3 people.
  • Alex, John and 3 others like your picture

The variables and syntax of the aggregation format are documented here.

Debugging your aggregation format

Two tools come in handy when making changes to the aggregation format. The first is the aggregation preview screen in the dashboard: This aggregation preview shows how your existing feed would look going forward using the new aggregation format. (Remember, this is just a preview, changing the format will only impact new activities.) The second tool we recommend for debugging the aggregation format is simply reading the feed. The “group” value shows you how your aggregation format is working.

var stream = require('getstream')
var client = stream.connect(key, secret)
chris = client.feed('timeline_aggregated', 'chris')
chris.get({ limit: 10 }).then(function(response) {
    response.results.forEach(function(aggregatedActivity) {

Advanced aggregation

With our Enterprise solutions, we can help you go beyond what is capable with the aggregation format alone. Contact learn more about how our enterprise plans provide custom aggregation logic for your app.


Setting up aggregation can be a little tricky at first. We hope this guide helped you get started. If you want to see it in action, try the 5 minute interactive tutorial. Feel free to contact support if you have any additional questions.

decorative lines
Integrating Video With Your App?
We've built an audio and video solution just for you. Launch in days with our new APIs & SDKs!
Check out the BETA!