Skip to content


Twitter API v2 live stream client.

This client gives access to a live stream of Tweets. That is, Tweets that have just been published. This is different to stream.TwitterRecentStream, which also covers Tweets that have been published over recent days, and not necessarily in real-time.

A list of filtering rules has to be provided. For instance, this allows focusing on a subset of topics and/or users.


Using this requires having the requests package installed.


  • rules

    See the documentation[^2] for a comprehensive overview of filtering rules.

  • bearer_token

    A bearer token that is available in each account's developer portal.


The live stream is instantiated by passing a list of filtering rules, as well as a bearer token. For instance, we can listen to all the breaking news Tweets from the BBC and CNN.

>>> from river import stream

>>> tweets = stream.TwitterLiveStream(
...     rules=["from:BBCBreaking", "from:cnnbrk"],
...     bearer_token="<insert_bearer_token>"
... )

The stream can then be iterated over, possibly in an infinite loop. This will listen to the
live feed of Tweets and produce a Tweet right after it's been published.

import logging

while True:
        for tweet in tweets:
    except requests.exceptions.RequestException as e:

Here's a Tweet example:

    'data': {
        'author_id': '428333',
        'created_at': '2022-08-26T12:59:48.000Z',
        'id': '1563149212774445058',
        'text': "Ukraine's Zaporizhzhia nuclear power plant, which is currently held by

Russian forces, has been reconnected to Ukraine's electricity grid, according to the country's nuclear operator" }, 'includes': { 'users': [ { 'created_at': '2007-01-02T01:48:14.000Z', 'id': '428333', 'name': 'CNN Breaking News', 'username': 'cnnbrk' } ] }, 'matching_rules': [{'id': '1563148866333151233', 'tag': 'from:cnnbrk'}] } ```


[^1]: [Filtered stream introduction](
[^2]: [Building rules for filtered stream](
[^3]: [Stream Tweets in real-time](