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

Some advanced operators (such as semantic embedding) require Embedding tier access in addition to Enterprise.

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`

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
`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`

Semantic operators

Requires Embedding tierThe embedding: and embedding_threshold: operators require Embedding tier access on your Enterprise Filtered Stream instance. If not provisioned, rule creation will fail with an “‘embedding’ is not an available operator” error.

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

Getting Started

Products

Fundamentals

Partners & Customers

Resources

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

Semantic 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

​Semantic 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

Semantic operators

Key requirements and notes

Supported languages

Next steps