Introduction

The filtered stream endpoint group enables developers to filter the real-time stream of public Tweets. This endpoint group’s functionality includes multiple endpoints that enable you to create and manage rules, and apply those rules to filter a stream of real-time Tweets that will return matching public Tweets. This endpoint group allows users to listen for specific topics and events in real-time, monitor the conversation around competitions, understand how trends develop in real-time, and much more.

Developers can use the REST rules endpoint to add and remove rules to a persistent stream connection without needing to disconnect. These rules can be created with operators that match on Tweet attributes such as message keywords, hashtags, and URLs. Operators and rule clauses can be combined with boolean logic and parentheses to help refine the filter’s matching behavior. 

Once you've added a set of rules, you can establish a streaming connection which will start to deliver Tweet objects in JSON format through a persistent HTTP Streaming connection. You will only receive content matching your rules while connected to the stream.
 

Certain aspects of the filtered stream endpoint are limited by access level:

Essential access

  • Five rules per stream
  • 25 requests per 15 minutes when using the POST /2/tweets/search/stream/rules endpoint to add rules
  • Can only use the core operators when building your rule
  • Can build rules up to 512 characters in length
  • Cannot use the recovery and redundancy features
     

Elevated access

  • 25 rules per stream
  • 50 requests per 15 minutes when using the POST /2/tweets/search/stream/rules endpoint to add rules
  • Can only use the core operators when building your rule
  • Can build rules up to 512 characters in length
  • Cannot use the recovery and redundancy features

Academic Research access

  • 1000 rules per stream
  • 100 requests per 15 minutes when using the POST /2/tweets/search/stream/rules endpoint to add rules
  • Can use all operators when building your rule
  • Can build rules up to 1024 characters in length
  • Can use the recovery and redundancy features to maximize up-time and recover lost data in case of an outage

 

The returned Tweets from filtered stream count towards the monthly Tweet cap.

Account setup

To access these endpoints, you will need:

Learn more about getting access to the Twitter API v2 endpoints in our getting started guide.