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
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 |
Supported Languages
Thelang: 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 |