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 operatorsConjunction-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 keywordStandalone Matches a keyword within the Post body (tokenized match) pepsi OR cola OR "coca cola"emojiStandalone 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"~NStandalone 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:apito:Standalone Matches Posts in reply to a specific user to:XDevelopers OR to:apiretweets_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:snowurl_description:— Keyword match on expanded page description metadata url_description:weatherurl_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:mdbio_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:seattleplace_country:Standalone Matches Posts with a country code place_country:US OR place_country:MXpoint_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:retweetConjunction required Matches Retweets data @XDevelopers -is:retweetis:replyConjunction required Matches replies from:XDevelopers is:replyis:quoteConjunction required Matches Quote Tweets "sentiment analysis" is:quoteis:verifiedConjunction required Matches Posts from verified authors #nowplaying is:verified-is:nullcastConjunction required Excludes promotional Posts (must be negated) "mobile games" -is:nullcast
Content type operators Operator Type Summary Example has:hashtagsConjunction required Matches Posts with hashtags from:XDevelopers -has:hashtagshas:cashtagsConjunction required Matches Posts with cashtags #stonks has:cashtagshas:linksConjunction required Matches Posts with links from:XDevelopers has:linkshas:mentionsConjunction required Matches Posts with mentions #nowplaying has:mentionshas:mediaConjunction required Matches Posts with media (photo, GIF, video) (kittens OR puppies) has:mediahas:imagesConjunction required Matches Posts with images #meme has:imageshas:video_linkConjunction required Matches Posts with native X videos #icebucketchallenge has:video_linkhas:geoConjunction 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:15lang: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..10000tweets_count:— Matches Posts from users with Post count in range tweets_count:1000..10000following_count:— Matches Posts from users with following count in range following_count:1000..10000listed_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:1539382664746020864retweets_of_tweet_id:— Matches Retweets of a specific Post retweets_of_tweet_id:1539382664746020864source:— Matches Posts from a specific source application source:"X for iPhone"
Logical operators Operator Summary Example ORLogical OR between expressions cat OR dogSpace (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 tier The 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.XXConjunction 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:linksembedding:"natural disaster relief" embedding_threshold:0.45 has:mediaembedding:"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 amGreek elPortuguese ptArabic arGujarati guRomanian roArmenian hyHebrew iwRussian ruBasque euHindi hiSerbian srBengali bnHungarian huSimplified Chinese zh-CNBulgarian bgIndonesian inSlovak skCatalan caItalian itSlovenian slCroatian hrJapanese jaSpanish esCzech csKannada knSwedish svDanish daKorean koTamil taDutch nlLatvian lvTelugu teEnglish enLithuanian ltThai thEstonian etMalayalam mlTraditional Chinese zh-TWFinnish fiMarathi mrTurkish trFrench frNorwegian noUkrainian ukGerman dePersian faUrdu urGeorgian kaPolish plVietnamese 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
