> ## Documentation Index
> Fetch the complete documentation index at: https://x-preview-mintlify-24fef6d1.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Filtered Stream
> Receive near real-time Posts that match custom rules with X API v2 Filtered Stream, using powerful operators to filter the public Post firehose.
export const Button = ({href, children}) => {
return ;
};
The Filtered Stream endpoints let you receive near real-time Posts that match your filter rules. Create rules using powerful operators, then connect to a persistent stream to receive matching Posts as they're published.
Filtered Stream prioritizes data hydration and delivery, with approximately 4-5 seconds of P99 latency. For lower latency requirements, see [Powerstream](/x-api/powerstream/introduction).
## Overview
Receive Posts within seconds of publication
Add and remove rules without disconnecting
Match on keywords, hashtags, users, and more
Optionally receive Posts via webhooks
***
## How it works
1. **Create rules** — Define filter rules using operators
2. **Connect to stream** — Establish a persistent HTTP connection
3. **Receive Posts** — Get matching Posts in near real-time
```mermaid actions={false} theme={null}
flowchart LR
A["Create/manage
rules"] --> B["Connect to
streaming endpoint"] --> C["Receive
matching Posts"]
```
***
## Endpoints
| Method | Endpoint | Description |
| :- | :- | :- |
| GET | [`/2/tweets/search/stream`](/x-api/stream/stream-filtered-posts) | Connect to the stream |
| POST | [`/2/tweets/search/stream/rules`](/x-api/stream/update-stream-rules) | Add or delete rules |
| GET | [`/2/tweets/search/stream/rules`](/x-api/stream/get-stream-rules) | List current rules |
***
## Access levels
| Feature | Pay-per-use | Enterprise |
| :- | :- | :- |
| Rules per project | 1,000 | 25,000+ |
| Rule length | 1,024 chars | 2,048 chars |
| Connections | 1 | Multiple |
| Core operators | ✓ | ✓ |
| Semantic embedding operators | — | ✓ (requires Embedding tier) |
Get higher limits and additional features
Some operators require specific tiers. The `embedding:` semantic operator is available **only for Filtered Stream** on Enterprise plans with Embedding tier access. Standard Pay-per-use access includes core operators only.
***
## Building rules
Rules use the same operators as search queries:
```
(AI OR "machine learning") lang:en -is:retweet
```
### Example rules
| Rule | Matches |
| :- | :- |
| `#python` | Posts with #python hashtag |
| `from:elonmusk` | Posts by @elonmusk |
| `"breaking news" has:images` | Posts with phrase and images |
| `(@XDevelopers OR @X) -is:retweet` | Mentions, excluding retweets |
| `embedding:"climate change policy"` | Posts semantically about climate policy (Enterprise + Embedding tier) |
Learn rule syntax and operators
***
## Connecting to the stream
Establish a persistent HTTP connection to receive Posts:
```python theme={null}
import requests
def stream_posts(bearer_token):
url = "https://api.x.com/2/tweets/search/stream"
headers = {"Authorization": f"Bearer {bearer_token}"}
response = requests.get(url, headers=headers, stream=True)
for line in response.iter_lines():
if line:
print(line.decode("utf-8"))
```
### Keep-alive signals
The stream sends blank lines (`\r\n`) every 20 seconds to maintain the connection. If you don't receive data or a keep-alive for 20 seconds, reconnect.
Reconnect gracefully
Process Posts efficiently
***
## Webhook delivery
Instead of maintaining a persistent connection, you can receive Posts via webhooks:
Set up webhook delivery for filtered stream
***
## Post edits
The stream delivers edited Posts with their edit history. Each edit creates a new Post ID:
```json theme={null}
{
"data": {
"id": "1234567893",
"text": "Hello world! (edited)",
"edit_history_tweet_ids": ["1234567890", "1234567891", "1234567893"]
}
}
```
Learn more about Post edits
***
## Getting started
**Prerequisites**
* An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
* A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
* Your App's [Bearer Token](/resources/fundamentals/authentication)
Connect to the stream in minutes
Learn rule syntax
All available operators
Working code examples
***
## Advanced topics
Reconnect gracefully
Handle high throughput
Build resilient applications
Identify which rules matched