These functions allow access to the streaming API. For the public, local and hashtag streams, access is generally possible without authenticating.

If run_async is False, these methods block forever (or until an error is encountered).

If run_async is True, the listener will listen on another thread and these methods will return a handle corresponding to the open connection. If, in addition, reconnect_async is True, the thread will attempt to reconnect to the streaming API if any errors are encountered, waiting reconnect_async_wait_sec seconds between reconnection attempts. Note that no effort is made to “catch up” - events created while the connection is broken will not be received. If you need to make sure to get absolutely all notifications / deletes / toots, you will have to do that manually, e.g. using the on_abort handler to fill in events since the last received one and then reconnecting. Both run_async and reconnect_async default to false, and you’ll have to set each to true separately to get the behaviour described above.

The connection may be closed at any time by calling the handles close() method. The current status of the handler thread can be checked with the handles is_alive() function, and the streaming status can be checked by calling is_receiving().

The streaming functions take instances of StreamListener as the listener parameter. A CallbackStreamListener class that allows you to specify function callbacks directly is included for convenience.

For new well-known events implement the streaming function in StreamListener or CallbackStreamListener. The function name is on_ + the event name. If the event name contains dots, they are replaced with underscored, e.g. for an event called ‘status.update’ the listener function should be named on_status_update.

It may be that future Mastodon versions will come with completely new (unknown) event names. If you want to do something when such an event is received, override the listener function on_unknown_event. This has an additional parameter name which informs about the name of the event. unknown_event contains the content of the event. Alternatively, a callback function can be passed in the unknown_event_handler parameter in the CallbackStreamListener constructor.

Note that the unknown_event handler is not guaranteed to receive events once they have been implemented. Events will only go to this handler temporarily, while has not been updated. Changes to what events do and do not go into the handler will not be considered a breaking change. If you want to handle a new event whose name you _do_ know, define an appropriate handler in your StreamListener, which will work even if it is not listed here.

When in not-async mode or async mode without async_reconnect, the stream functions may raise various exceptions: MastodonMalformedEventError if a received event cannot be parsed and MastodonNetworkError if any connection problems occur. currently does not support websocket based, multiplexed streams, but might in the future.

Stream endpoints

Mastodon.stream_user(listener, run_async=False, timeout=300, reconnect_async=False, reconnect_async_wait_sec=5)[source]

Streams events that are relevant to the authorized user, i.e. home timeline and notifications.

Added: Mastodon v1.1.0, last changed: Mastodon v1.4.2

Mastodon.stream_public(listener, run_async=False, timeout=300, reconnect_async=False, reconnect_async_wait_sec=5)[source]

Streams public events.

Added: Mastodon v1.1.0, last changed: Mastodon v1.4.2

Mastodon.stream_local(listener, run_async=False, timeout=300, reconnect_async=False, reconnect_async_wait_sec=5)[source]

Streams local public events.

Added: Mastodon v1.1.0, last changed: Mastodon v1.4.2

Mastodon.stream_hashtag(tag, listener, local=False, run_async=False, timeout=300, reconnect_async=False, reconnect_async_wait_sec=5)[source]

Stream for all public statuses for the hashtag ‘tag’ seen by the connected instance.

Set local to True to only get local statuses.

Added: Mastodon v1.1.0, last changed: Mastodon v1.4.2

Mastodon.stream_list(id, listener, run_async=False, timeout=300, reconnect_async=False, reconnect_async_wait_sec=5)[source]

Stream events for the current user, restricted to accounts on the given list.

Added: Mastodon v2.1.0, last changed: Mastodon v2.1.0


Returns without True if streaming API is okay, False or raises an error otherwise.

Added: Mastodon v2.5.0, last changed: Mastodon v2.5.0


class mastodon.StreamListener[source]

Callbacks for the streaming API. Create a subclass, override the on_xxx methods for the kinds of events you’re interested in, then pass an instance of your subclass to Mastodon.user_stream(), Mastodon.public_stream(), or Mastodon.hashtag_stream().


A new status has appeared. status is the parsed status dict describing the status.


A new notification. notification is the parsed notification dict describing the notification.


A status has been deleted. status_id is the status’ integer ID.


A direct message (in the direct stream) has been received. conversation is the parsed conversation dict dictionary describing the conversation


A status has been edited. ‘status’ is the parsed JSON dictionary describing the updated status.

StreamListener.on_unknown_event(name, unknown_event=None)[source]

An unknown mastodon API event has been received. The name contains the event-name and unknown_event contains the content of the unknown event.


There was a connection error, read timeout or other error fatal to the streaming connection. The exception object about to be raised is passed to this function for reference.

Note that the exception will be raised properly once you return from this function, so if you are using this handler to reconnect, either never return or start a thread and then catch and ignore the exception.


The server has sent us a keep-alive message. This callback may be useful to carry out periodic housekeeping tasks, or just to confirm that the connection is still open.


class mastodon.CallbackStreamListener(update_handler=None, local_update_handler=None, delete_handler=None, notification_handler=None, conversation_handler=None, unknown_event_handler=None, status_update_handler=None, filters_changed_handler=None, announcement_handler=None, announcement_reaction_handler=None, announcement_delete_handler=None, encryted_message_handler=None)[source]

Simple callback stream handler class. Can optionally additionally send local update events to a separate handler. Define an unknown_event_handler for new Mastodon API events. This handler is not guaranteed to receive these events forever, and should only be used for diagnostics.