StreamingClient

class tweepy.StreamingClient(bearer_token, *, return_type=Response, wait_on_rate_limit=False, chunk_size=512, daemon=False, max_retries=inf, proxy=None, verify=True)

Filter and sample realtime Tweets with Twitter API v2

New in version 4.6.

Parameters

  • bearer_token (str) – Twitter API Bearer Token

  • return_type (type[dict | requests.Response | Response]) – Type to return from requests to the API

  • wait_on_rate_limit (bool) – Whether to wait when rate limit is reached

  • 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

add_rules(add, *, dry_run)

Add rules to filtered stream.

Parameters

  • add (list[StreamRule] | StreamRule) – Specifies the operation you want to perform on the rules.

  • dry_run (bool) – Set to true to test a the syntax of your rule without submitting it. This is useful if you want to check the syntax of a rule before removing one or more of your existing rules.

Return type

dict | requests.Response | Response

References

https://developer.twitter.com/en/docs/twitter-api/tweets/filtered-stream/api-reference/post-tweets-search-stream-rules

delete_rules(ids, *, dry_run)

Delete rules from filtered stream.

Parameters

  • ids (int | str | list[int | str | StreamRule] | StreamRule) – Array of rule IDs, each one representing a rule already active in your stream. IDs must be submitted as strings.

  • dry_run (bool) – Set to true to test a the syntax of your rule without submitting it. This is useful if you want to check the syntax of a rule before removing one or more of your existing rules.

Return type

dict | requests.Response | Response

References

https://developer.twitter.com/en/docs/twitter-api/tweets/filtered-stream/api-reference/post-tweets-search-stream-rules

filter(*, backfill_minutes=None, expansions=None, media_fields=None, place_fields=None, poll_fields=None, tweet_fields=None, user_fields=None, threaded=False)

Streams Tweets in real-time based on a specific set of filter rules.

If you are using the academic research product track, you can connect up to two redundant connections to maximize your streaming up-time.

The Tweets returned by this endpoint count towards the Project-level Tweet cap.

Parameters

  • backfill_minutes (int | None) –

    By passing this parameter, you can request up to five (5) minutes worth of streaming data that you might have missed during a disconnection to be delivered to you upon reconnection. The backfilled Tweets will automatically flow through the reconnected stream, with older Tweets generally being delivered before any newly matching Tweets. You must include a whole number between 1 and 5 as the value to this parameter.

    This feature will deliver duplicate Tweets, meaning that if you were disconnected for 90 seconds, and you requested two minutes of backfill, you will receive 30 seconds worth of duplicate Tweets. Due to this, you should make sure your system is tolerant of duplicate data.

    This feature is currently only available to the Academic Research product track.

  • expansions (list[str] | str) – expansions

  • media_fields (list[str] | str) – media_fields

  • place_fields (list[str] | str) – place_fields

  • poll_fields (list[str] | str) – poll_fields

  • tweet_fields (list[str] | str) – tweet_fields

  • user_fields (list[str] | str) – user_fields

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

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/tweets/filtered-stream/api-reference/get-tweets-search-stream

get_rules(*, ids)

Return a list of rules currently active on the streaming endpoint, either as a list or individually.

Parameters

ids (list[str] | str) – Comma-separated list of rule IDs. If omitted, all rules are returned.

Return type

dict | requests.Response | Response

References

https://developer.twitter.com/en/docs/twitter-api/tweets/filtered-stream/api-reference/get-tweets-search-stream-rules

sample(*, backfill_minutes=None, expansions=None, media_fields=None, place_fields=None, poll_fields=None, tweet_fields=None, user_fields=None, threaded=False)

Streams about 1% of all Tweets in real-time.

If you are using the academic research product track, you can connect up to two redundant connections to maximize your streaming up-time.

Parameters

  • backfill_minutes (int | None) –

    By passing this parameter, you can request up to five (5) minutes worth of streaming data that you might have missed during a disconnection to be delivered to you upon reconnection. The backfilled Tweets will automatically flow through the reconnected stream, with older Tweets generally being delivered before any newly matching Tweets. You must include a whole number between 1 and 5 as the value to this parameter.

    This feature will deliver duplicate Tweets, meaning that if you were disconnected for 90 seconds, and you requested two minutes of backfill, you will receive 30 seconds worth of duplicate Tweets. Due to this, you should make sure your system is tolerant of duplicate data.

    This feature is currently only available to the Academic Research product track.

  • expansions (list[str] | str) – expansions

  • media_fields (list[str] | str) – media_fields

  • place_fields (list[str] | str) – place_fields

  • poll_fields (list[str] | str) – poll_fields

  • tweet_fields (list[str] | str) – tweet_fields

  • user_fields (list[str] | str) – user_fields

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

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/tweets/volume-streams/api-reference/get-tweets-sample-stream

on_data(raw_data)

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

Parameters

raw_data (JSON) – The raw data from the stream

References

https://developer.twitter.com/en/docs/twitter-api/tweets/filtered-stream/integrate/consuming-streaming-data

on_tweet(tweet)

This is called when a Tweet is received.

Parameters

status (Tweet) – The Tweet received

on_includes(includes)

This is called when includes are received.

Parameters

includes (dict) – The includes received

on_errors(errors)

This is called when errors are received.

Parameters

errors (dict) – The errors received

on_matching_rules(matching_rules)

This is called when matching rules are received.

Parameters

matching_rules (list[StreamRule]) – The matching rules received

on_response(response)

This is called when a response is received.

Parameters

response (StreamResponse) – The response received

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

StreamResponse

class tweepy.StreamResponse(data, includes, errors, matching_rules)

The StreamResponse returned by StreamingClient.on_response() is a collections.namedtuple, with data, includes, errors, and matching_rules fields, corresponding with the fields in responses from Twitter’s API.

New in version 4.6.

StreamRule

class tweepy.StreamRule(value: Optional[str] = None, tag: Optional[str] = None, id: Optional[str] = None)

Rule for filtered stream

New in version 4.6.

Parameters

  • value (str | None) – The rule text. If you are using a Standard Project at the Basic access level, you can use the basic set of operators, can submit up to 25 concurrent rules, and can submit rules up to 512 characters long. If you are using an Academic Research Project at the Basic access level, you can use all available operators, can submit up to 1,000 concurrent rules, and can submit rules up to 1,024 characters long.

  • tag (str | None) – The tag label. This is a free-form text you can use to identify the rules that matched a specific Tweet in the streaming response. Tags can be the same across rules.

  • id (str | None) – Unique identifier of this rule. This is returned as a string.

Create new instance of StreamRule(value, tag, id)