Filtered stream v1 (retired)

Please note:

We graduated the Labs version of filtered stream into Twitter API v2: Early Access and retired it in October 2020.

Learn more about the new filtered stream, and review our migration resources to update to The New Twitter API.



The endpoints we release in Labs will be previews and are likely to change before they are released broadly, so we encourage you to take that into consideration as you build. Before getting started, we encourage you to read more about Twitter Developer Labs.

The filtered stream endpoints allow developers to filter the real-time stream of public Tweets. Developers can filter the real-time stream by applying a set of rules (specified using a combination of operators), and they can select the response format on connection.

This preview contains a streaming endpoint that delivers Tweets in real-time. It also contains a set of rules endpoints to create, delete and dry-run rule changes. During Labs, you can create up to 10 rules (each one up to 512 characters long) can be set on your stream at the same time. Unlike the existing statuses/filter endpoint, these rules are retained and are not specified at connection time.

Streaming endpoint

The streaming endpoint is a simple GET connection authenticated using a bearer token. Once a connection is established, Tweets are delivered in JSON format (see sample payload below) through a persistent HTTP Streaming connection. You will only receive content matching your rules while connected to the stream.

Rules and operators endpoint

Rules can be set by specifying a combination of keywords (a specific word or emoji, or full text match) and operators. Operators can be joined and negated to specify complex expressions.

You can specify a tag for each rule you define. This tag is a label that can be used to quickly identify a rule. For example, you can assign the tag cat-meme to the rule "grumpy cat" has:images to identify the rule you set. When a Tweet is delivered through the streaming endpoint, it will also return a set of matching rules including their tags.



Additional resources

Was this document helpful?
Thank you

Thank you for the feedback. We’re really glad we could help!

Thank you for the feedback. How could we improve this document?
Thank you for the feedback. Your comments will help us improve our documents in the future.