Stream

class tweepy.Stream(consumer_key, consumer_secret, access_token, access_token_secret, chunk_size=512, daemon=False, max_retries=inf, proxy=None, verify=True)

Filter and sample realtime Tweets with Twitter API v1.1

Note

New Twitter Developer Apps created on or after April 29, 2022 will not be able to gain access to v1.1 statuses/sample and v1.1 statuses/filter, the Twitter API v1.1 endpoints that Stream uses. Twitter API v2 can be used instead with StreamingClient.

Parameters
  • consumer_key (str) – Twitter API Consumer Key

  • consumer_secret (str) – Twitter API Consumer Secret

  • access_token (str) – Twitter API Access Token

  • access_token_secret (str) – Twitter API Access Token Secret

  • chunk_size (int) – The default socket.read size. Default to 512, less than half the size of a Tweet so that it reads Tweets with the minimal latency of 2 reads per Tweet. Values higher than ~1kb will increase latency by waiting for more data to arrive but may also increase throughput by doing fewer socket read calls.

  • daemon (bool) – Whether or not to use a daemon thread when using a thread to run the stream

  • max_retries (int) – Max number of times to retry connecting the stream

  • proxy (str | None) – URL of the proxy to use when connecting to the stream

  • verify (bool | str) – Either a boolean, in which case it controls whether to verify the server’s TLS certificate, or a string, in which case it must be a path to a CA bundle to use.

running

Whether there’s currently a stream running

Type

bool

session

Requests Session used to connect to the stream

Type

requests.Session

thread

Thread used to run the stream

Type

threading.Thread | None

user_agent

User agent used when connecting to the stream

Type

str

filter(*, follow=None, track=None, locations=None, filter_level=None, languages=None, stall_warnings=False, threaded=False)

Filter realtime Tweets

Parameters
  • follow (list[int | str] | None) – User IDs, indicating the users to return statuses for in the stream

  • track (list[str] | None) – Keywords to track

  • locations (list[float] | None) – Specifies a set of bounding boxes to track

  • filter_level (str | None) –

    Setting this parameter to one of none, low, or medium will set the minimum value of the filter_level Tweet attribute required to be included in the stream. The default value is none, which includes all available Tweets.

    When displaying a stream of Tweets to end users (dashboards or live feeds at a presentation or conference, for example) it is suggested that you set this value to medium.

  • languages (list[str] | None) – Setting this parameter to a comma-separated list of BCP 47 language identifiers corresponding to any of the languages listed on Twitter’s advanced search page will only return Tweets that have been detected as being written in the specified languages. For example, connecting with language=en will only stream Tweets detected to be in the English language.

  • stall_warnings (bool) – Specifies whether stall warnings should be delivered

  • threaded (bool) – Whether or not to use a thread to run the stream

Raises

TweepyException – When the stream is already connected or when the number of location coordinates is not a multiple of 4

Returns

The thread if threaded is set to True, else None

Return type

threading.Thread | None

References

https://developer.twitter.com/en/docs/twitter-api/v1/tweets/filter-realtime/api-reference/post-statuses-filter

sample(*, languages=None, stall_warnings=False, threaded=False)

Sample realtime Tweets

Parameters
  • languages (list[str] | None) – Setting this parameter to a comma-separated list of BCP 47 language identifiers corresponding to any of the languages listed on Twitter’s advanced search page will only return Tweets that have been detected as being written in the specified languages. For example, connecting with language=en will only stream Tweets detected to be in the English language.

  • stall_warnings (bool) – Specifies whether stall warnings should be delivered

  • threaded (bool) – Whether or not to use a thread to run the stream

Raises

TweepyException – When the stream is already connected

Returns

The thread if threaded is set to True, else None

Return type

threading.Thread | None

References

https://developer.twitter.com/en/docs/twitter-api/v1/tweets/sample-realtime/api-reference/get-statuses-sample

on_data(raw_data)

This is called when raw data is received from the stream. This method handles sending the data to other methods based on the message type.

Parameters

raw_data (JSON) – The raw data from the stream

References

https://developer.twitter.com/en/docs/twitter-api/v1/tweets/filter-realtime/guides/streaming-message-types

on_status(status)

This is called when a status is received.

Parameters

status (Status) – The Status received

on_delete(status_id, user_id)

This is called when a status deletion notice is received.

Parameters
  • status_id (int) – The ID of the deleted Tweet

  • user_id (int) – The ID of the author of the Tweet

on_disconnect_message(message)

This is called when a disconnect message is received.

Parameters

message (JSON) – The disconnect message

on_limit(track)

This is called when a limit notice is received.

Parameters

track (int) – Total count of the number of undelivered Tweets since the connection was opened

on_scrub_geo(notice)

This is called when a location deletion notice is received.

Parameters

notice (JSON) – The location deletion notice

on_status_withheld(notice)

This is called when a status withheld content notice is received.

Parameters

notice (JSON) – The status withheld content notice

on_user_withheld(notice)

This is called when a user withheld content notice is received.

Parameters

notice (JSON) – The user withheld content notice

on_warning(warning)

This is called when a stall warning message is received.

Parameters

warning (JSON) – The stall warning

disconnect()

Disconnect the stream

on_closed(response)

This is called when the stream has been closed by Twitter.

Parameters

response (requests.Response) – The Response from Twitter

on_connect()

This is called after successfully connecting to the streaming API.

on_connection_error()

This is called when the stream connection errors or times out.

on_disconnect()

This is called when the stream has disconnected.

on_exception(exception)

This is called when an unhandled exception occurs.

Parameters

exception (Exception) – The unhandled exception

on_keep_alive()

This is called when a keep-alive signal is received.

on_request_error(status_code)

This is called when a non-200 HTTP status code is encountered.

Parameters

status_code (int) – The HTTP status code encountered