Awesome Open Source
Awesome Open Source


build Gem Version

stream-ruby is the official Ruby client for Stream, a web service for building scalable newsfeeds and activity streams.

Note there is also a higher level Ruby on Rails - Stream integration library which hooks into the Ruby on Rails ORM.

You can sign up for a Stream account at

Ruby version requirements and support

This API Client project requires Ruby 2.5.x at a minimum.

See the Travis configuration for details of how it is built and tested.


gem install 'stream-ruby'

Full documentation

Documentation for this Ruby client are available at the Stream website.


# Instantiate a new client to connect to us east API endpoint
require 'stream'
client ='YOUR_API_KEY', 'API_KEY_SECRET', 'APP_ID', location: 'us-east')

# Find your API keys here

# Instantiate a feed object
user_feed_1 = client.feed('user', '1')

# Get activities from 5 to 10 (slow pagination)
result = user_feed_1.get(limit: 5, offset: 5)
# (Recommended & faster) Filter on an id less than the given UUID
result =
  user_feed_1.get(limit: 5, id_lt: 'e561de8f-00f1-11e4-b400-0cc47a024be0')

# Create a new activity
activity_data = { actor: 1, verb: 'tweet', object: 1, foreign_id: 'tweet:1' }
activity_response = user_feed_1.add_activity(activity_data)
# Create a bit more complex activity
activity_data = {
  actor: 1,
  verb: 'tweet',
  object: 1,
  foreign_id: 'tweet:1',
  course: { name: 'Golden Gate park', distance: 10 },
  participants: %w[Thierry Tommaso],
activity_response = user_feed_1.add_activity(activity_data)

# Update an existing activity (requires both :foreign_id and :time fields)
activity_data = {
  actor: 1,
  verb: 'tweet',
  object: 1,
  foreign_id: 'tweet:1',
  popularity: 100,
  time: '2016-05-13T16:12:30'

# Update activities

# Remove an activity by its id

# Remove activities by their foreign_id
user_feed_1.remove_activity('tweet:1', foreign_id: true)

# Follow another feed
user_feed_1.follow('flat', '42')

# Stop following another feed
user_feed_1.unfollow('flat', '42')

# Batch adding activities
activities = [
  [actor: '1', verb: 'tweet', object: '1'],
  [actor: '2', verb: 'like', object: '3']

# Batch following many feeds (requires ruby 2.1 or later)
follows = [
  { source: 'flat:1', target: 'user:1' },
  { source: 'flat:1', target: 'user:2' },
  { source: 'flat:1', target: 'user:3' }

# Add an activity and push it to other feeds too using the `to` field
data = [actor_id: '1', verb: 'like', object_id: '3', to: %w[user:44 user:45]]

# Updating parts of an activity
set = {
  'product.price': 19.99, 'shares': { 'facebook': '...', 'twitter': '...' }
unset = %w[daily_likes popularity]
# ID
  id: '54a60c1e-4ee3-494b-a1e3-50c06acb5ed4', set: set, unset: unset
# ...or by combination of foreign ID and time
  foreign_id: 'product:123',
  time: '2016-11-10T13:20:00.000000',
  set: set,
  unset: unset

# Generating tokens for client side usage
token = user_feed_1.readonly_token

# Javascript client side feed initialization
user1 = client.feed('user', '1', '{{ token }}')

# Retrieve first 10 followers of a feed
user_feed_1.followers(0, 10)

# Retrieve followers from 10 to 20
user_feed_1.followers(10, 10)

# Retrieve 10 feeds followed by user_feed_1

# Retrieve 10 feeds followed by user_feed_1 starting from the 11th
user_feed_1.following(10, 10)

# Check if user_feed_1 follows specific feeds
user_feed_1.following(0, 2, filter = %w[user:42 user:43])

# Add one activity to many feeds in one request
feeds = %w[flat:1 flat:2 flat:3 flat:4]
activity = {
  actor: 'User:2', verb: 'pin', object: 'Place:42', target: 'Board:1'
client.add_to_many(activity, feeds)

# Retrive open graph information

Copyright and License Information

Project is licensed under the BSD 3-Clause.

We are hiring!

We've recently closed a $38 million Series B funding round and we keep actively growing. Our APIs are used by more than a billion end-users, and you'll have a chance to make a huge impact on the product within a team of the strongest engineers all over the world.

Check out our current openings and apply via Stream's website.

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Ruby (312,148
Feed (585
Timeline (513
Related Projects