Filtered Stream Operators

This page provides a complete list of operators available when building rules for Filtered Stream.

Overview

Operators are used to match on specific Post attributes. There are two types:

Standalone operators — Can be used alone or with any other operators
Conjunction-required operators — Must be used with at least one standalone operator

Most operators are available on both Pay-per-use and Enterprise. Some advanced operators (such as semantic embedding) require Enterprise with additional tier access.

Keyword and phrase operators

Operator	Type	Summary	Example
`keyword`	Standalone	Matches a keyword within the Post body (tokenized match)	`pepsi OR cola OR "coca cola"`
`emoji`	Standalone	Matches an emoji within the Post body	`(😃 OR 😡) 😬`
`"exact phrase"`	Standalone	Matches the exact phrase within the Post body	`("X API" OR #v2) -"filtered stream"`
`"keyword1 keyword2"~N`	Standalone	Proximity match — keywords within N tokens of each other (max N=6)	`"social media"~5`

Entity operators

Operator	Type	Summary	Example
`#`	Standalone	Matches Posts containing a hashtag (exact match)	`#thankunext #fanart`
`@`	Standalone	Matches Posts mentioning a username	`(@XDevelopers OR @api) -@x`
`$`	Standalone	Matches Posts containing a cashtag	`$twtr OR @XDevelopers -$fb`

User operators

Operator	Type	Summary	Example
`from:`	Standalone	Matches Posts from a specific user	`from:XDevelopers OR from:api`
`to:`	Standalone	Matches Posts in reply to a specific user	`to:XDevelopers OR to:api`
`retweets_of:`	Standalone	Matches Retweets of a specific user	`retweets_of:XDevelopers`
`from_affiliate_of:`	Standalone	Matches Posts from affiliates of a specific user	`from_affiliate_of:XDevelopers`
`to_affiliate_of:`	Standalone	Matches Posts in reply to affiliates of a specific user	`to_affiliate_of:XDevelopers`

URL operators

Operator	Type	Summary	Example
`url:`	Standalone	Tokenized match on URL (matches `url` or `expanded_url` fields)	`url:"https://developer.x.com"`
`url_title:`	—	Keyword match on expanded URL HTML title metadata	`url_title:snow`
`url_description:`	—	Keyword match on expanded page description metadata	`url_description:weather`
`url_contains:`	—	Literal match on URL content	`url_contains:photos`

Context and entity operators

Operator	Type	Summary	Example
`context:`	Standalone	Matches Posts with a specific domain/entity pair	`context:10.799022225751871488` or `context:47.*`
`entity:`	Standalone	Matches Posts with a specific entity string value	`entity:"Michael Jordan"`
`conversation_id:`	Standalone	Matches Posts in a conversation thread	`conversation_id:1334987486343299072`

User profile operators

Operator	Type	Summary	Example
`bio:`	Standalone	Matches keyword in Post author’s bio	`bio:developer OR bio:"data engineer"`
`bio_name:`	Standalone	Matches keyword in Post author’s name	`bio_name:phd OR bio_name:md`
`bio_location:`	Standalone	Matches keyword in Post author’s location	`bio_location:"big apple" OR bio_location:nyc`

Location operators

Operator	Type	Summary	Example
`place:`	Standalone	Matches Posts tagged with a location	`place:"new york city" OR place:seattle`
`place_country:`	Standalone	Matches Posts with a country code	`place_country:US OR place_country:MX`
`point_radius:`	Standalone	Matches Posts within a radius of a point	`point_radius:[2.355128 48.861118 16km]`
`bounding_box:`	Standalone	Matches Posts within a bounding box	`bounding_box:[-105.301758 39.964069 -105.178505 40.09455]`

Post type operators

Operator	Type	Summary	Example
`is:retweet`	Conjunction required	Matches Retweets	`data @XDevelopers -is:retweet`
`is:reply`	Conjunction required	Matches replies	`from:XDevelopers is:reply`
`is:quote`	Conjunction required	Matches Quote Tweets	`"sentiment analysis" is:quote`
`is:verified`	Conjunction required	Matches Posts from verified authors	`#nowplaying is:verified`
`-is:nullcast`	Conjunction required	Excludes promotional Posts (must be negated)	`"mobile games" -is:nullcast`

Content type operators

Operator	Type	Summary	Example
`has:hashtags`	Conjunction required	Matches Posts with hashtags	`from:XDevelopers -has:hashtags`
`has:cashtags`	Conjunction required	Matches Posts with cashtags	`#stonks has:cashtags`
`has:links`	Conjunction required	Matches Posts with links	`from:XDevelopers has:links`
`has:mentions`	Conjunction required	Matches Posts with mentions	`#nowplaying has:mentions`
`has:media`	Conjunction required	Matches Posts with media (photo, GIF, video)	`(kittens OR puppies) has:media`
`has:images`	Conjunction required	Matches Posts with images	`#meme has:images`
`has:video_link`	Conjunction required	Matches Posts with native X videos	`#icebucketchallenge has:video_link`
`has:geo`	Conjunction required	Matches Posts with geolocation data	`recommend #paris has:geo`

Sampling and language operators

Operator	Type	Summary	Example
`sample:`	Conjunction required	Returns a random percent sample (1-100)	`#nowplaying @spotify sample:15`
`lang:`	Conjunction required	Matches Posts classified as a specific language	`recommend #paris lang:en`

User metrics operators

Operator	Type	Summary	Example
`min_followers:`	—	Matches Posts from users with at least the specified number of followers	`min_followers:1000`
`followers_count:`	—	Matches Posts from users with follower count in range	`followers_count:1000..10000`
`tweets_count:`	—	Matches Posts from users with Post count in range	`tweets_count:1000..10000`
`following_count:`	—	Matches Posts from users with following count in range	`following_count:1000..10000`
`listed_count:`	—	Matches Posts from users in specified number of Lists	`listed_count:10..100`

Post reference operators

Operator	Type	Summary	Example
`in_reply_to_tweet_id:`	—	Matches replies to a specific Post	`in_reply_to_tweet_id:1539382664746020864`
`retweets_of_tweet_id:`	—	Matches Retweets of a specific Post	`retweets_of_tweet_id:1539382664746020864`
`source:`	—	Matches Posts from a specific source application	`source:"X for iPhone"`

Logical operators

Operator	Summary	Example
`OR`	Logical OR between expressions	`cat OR dog`
Space (AND)	Logical AND between expressions	`cat dog` (both required)
`()`	Grouping for complex expressions	`(cat OR dog) -is:retweet`
`-`	Negation/exclusion	`cat -grumpy`

Embedding operators

Enterprise only — Embedding tier requiredThe embedding: and embedding_threshold: operators are only available on Enterprise accounts provisioned with Embedding tier access for Filtered Stream. On unsupported tiers, rule creation will be rejected with an “unavailable operator” error. Contact your account representative to enable.

These operators use a neural embedding model to match Posts by semantic similarity to a query, rather than requiring exact keyword matches.

Operator	Type	Summary	Example
`embedding:"query"`	Standalone	Matches Posts semantically similar to the query. Multi-word queries must be quoted.	`embedding:"climate change policy"`
`embedding_threshold:X.XX`	Conjunction required	Minimum cosine similarity for a match (0.0–1.0). Defaults to `0.3`. Use values between 0.3–0.6.	`embedding:"cryptocurrency regulation" embedding_threshold:0.45`

Key requirements and notes

embedding_threshold: cannot be the only operator in a rule. Pair it with embedding: (or another standalone operator).
Do not negate embedding: (e.g. -embedding:"..." is unsupported).
Longer, descriptive natural language queries produce better results than short keywords.
Embedding query processing is asynchronous — newly created rules may take a few seconds before they begin matching.
When a Post matches via an embedding rule, the delivered payload’s matching_rules entries will contain embedding_similarity and embedding_threshold (see Matching Posts to Rules).

Example rules:

embedding:"electric vehicle announcements" lang:en -is:retweet has:links
embedding:"natural disaster relief" embedding_threshold:0.45 has:media
embedding:"renewable energy" embedding_threshold:0.4 OR embedding:"solar power investment"

Supported languages

The lang: operator supports these BCP 47 language codes:

Language	Code	Language	Code	Language	Code
Amharic	`am`	Greek	`el`	Portuguese	`pt`
Arabic	`ar`	Gujarati	`gu`	Romanian	`ro`
Armenian	`hy`	Hebrew	`iw`	Russian	`ru`
Basque	`eu`	Hindi	`hi`	Serbian	`sr`
Bengali	`bn`	Hungarian	`hu`	Simplified Chinese	`zh-CN`
Bulgarian	`bg`	Indonesian	`in`	Slovak	`sk`
Catalan	`ca`	Italian	`it`	Slovenian	`sl`
Croatian	`hr`	Japanese	`ja`	Spanish	`es`
Czech	`cs`	Kannada	`kn`	Swedish	`sv`
Danish	`da`	Korean	`ko`	Tamil	`ta`
Dutch	`nl`	Latvian	`lv`	Telugu	`te`
English	`en`	Lithuanian	`lt`	Thai	`th`
Estonian	`et`	Malayalam	`ml`	Traditional Chinese	`zh-TW`
Finnish	`fi`	Marathi	`mr`	Turkish	`tr`
French	`fr`	Norwegian	`no`	Ukrainian	`uk`
German	`de`	Persian	`fa`	Urdu	`ur`
Georgian	`ka`	Polish	`pl`	Vietnamese	`vi`

Next steps

Build a rule

Learn rule syntax and best practices

Filtered Stream introduction

Get started with Filtered Stream

Handling disconnections

Handle streaming disconnections

Overview

Posts

Articles

Users

Direct Messages

Likes

Lists

Spaces

Communities

Community Notes

Trends

News

Media

X Activity

Usage

Stream Connections

Compliance

Webhooks

Filtered Stream Operators

Overview

Keyword and phrase operators

Entity operators

User operators

URL operators

Context and entity operators

User profile operators

Location operators

Post type operators

Content type operators

Sampling and language operators

User metrics operators

Post reference operators

Logical operators

Embedding operators

Key requirements and notes

Supported languages

Next steps

Build a rule

Filtered Stream introduction

Handling disconnections

​Overview

​Keyword and phrase operators

​Entity operators

​User operators

​URL operators

​Context and entity operators

​User profile operators

​Location operators

​Post type operators

​Content type operators

​Sampling and language operators

​User metrics operators

​Post reference operators

​Logical operators

​Embedding operators

​Key requirements and notes

​Supported languages

​Next steps

Build a rule

Filtered Stream introduction

Handling disconnections

Overview

Keyword and phrase operators

Entity operators

User operators

URL operators

Context and entity operators

User profile operators

Location operators

Post type operators

Content type operators

Sampling and language operators

User metrics operators

Post reference operators

Logical operators

Embedding operators

Key requirements and notes

Supported languages

Next steps