Documentation Index
Fetch the complete documentation index at: https://docs.sorsa.io/llms.txt
Use this file to discover all available pages before exploring further.
Twitter search operators (also called X advanced search commands) are special keywords and symbols you can type into the X search bar - or pass programmatically via an API - to filter the global timeline by date, engagement, author, media type, language, and more. Instead of scrolling through thousands of irrelevant results, a single well-crafted query string can surface exactly the tweets you need for brand monitoring, competitive analysis, sentiment research, or social listening at scale.
This guide is the most complete reference for every working X search operator in 2026. Each operator includes a description, a ready-to-use example, and notes on edge cases. You can use these commands in the X search bar, TweetDeck, or programmatically via the Sorsa Search Tweets API by passing the operator string into the query field of a POST request.
Free Visual Query Builder
If you don’t want to assemble complex query strings by hand, use the Sorsa Search Builder. It is a free, no-login tool with a graphical interface where you toggle filters, pick operators, and preview results - and it generates the exact query string you can copy into your API request or the X search bar. It is the fastest way to prototype and test advanced search queries before integrating them into your code.
1. Basic Text Matching and Boolean Logic
These are the building blocks. Every advanced query starts here.
| Operator | What It Matches | Example |
|---|
keyword keyword | Tweets containing both terms. Spaces act as implicit AND. | nasa esa |
keyword OR keyword | Tweets containing either term. OR must be uppercase. | bitcoin OR ethereum |
"exact phrase" | Tweets containing the exact phrase in that order. Also prevents spelling correction. | "state of the art" |
-keyword | Excludes tweets containing the term. Works with words, phrases, and other operators. | crypto -scam |
( ) | Groups terms for complex Boolean logic. | (AI OR "machine learning") lang:en |
"word * word" | Wildcard within a quoted phrase. The * replaces any single word. Only works inside quotes with spaces. | "this is the * time" |
+word | Forces exact match, preventing Twitter’s auto-correction and stemming. | +radiooooo |
#hashtag | Matches a specific hashtag. | #tgif |
$cashtag | Matches a stock/crypto symbol. | $TSLA |
bulls will match bull. Twitter sometimes interprets common words as intent: searching for photo may return tweets with images even if the word “photo” is absent. Wrap such words in double quotes ("photo") to force a literal match.
Words can match against the tweet text, the author’s display name, screen name, and expanded URLs within the tweet. Keep this in mind when debugging unexpected results.
The maximum number of operators in a single query is approximately 22-23. If your query exceeds this, split it into multiple API calls.
2. User and Account Filters
These operators let you filter tweets by who posted them, who they are directed at, or who they mention.
| Operator | Description | Example |
|---|
from:username | Tweets sent by a specific account (without the @). | from:elonmusk |
to:username | Tweets that are replies to a specific account. | to:openai |
@username | Tweets that mention a specific account anywhere in the text. | @sorsa_app |
list:ID | Tweets from members of a public X List. Use the numeric List ID from the URL. | list:715919216927322112 |
filter:verified | Only from legacy verified accounts (pre-2023 blue checkmarks). | AI filter:verified |
filter:blue_verified | Only from X Premium (paid Blue) subscribers. | crypto filter:blue_verified |
filter:follows | Only from accounts you follow. Works in the X UI only, not via API. Cannot be negated. | filter:follows |
filter:social | From your algorithmically expanded network. Works on “Top” results, not “Latest”. | filter:social |
from: with -from: to build powerful brand monitoring queries. For example, "Tesla" -from:tesla finds what everyone except Tesla’s official account says about the brand.
3. Engagement Gating
Filter tweets by minimum (or maximum) engagement thresholds. These are essential for cutting through noise in high-volume keyword searches and for finding viral content, trending discussions, and influential voices.
| Operator | Description | Example |
|---|
min_faves:N | Minimum number of likes. | AI min_faves:100 |
min_retweets:N | Minimum number of retweets. | crypto min_retweets:50 |
min_replies:N | Minimum number of replies. | "product launch" min_replies:20 |
-min_faves:N | Maximum likes (negated form). | bitcoin -min_faves:1000 |
-min_retweets:N | Maximum retweets (negated form). | news -min_retweets:500 |
-min_replies:N | Maximum replies (negated form). | tech -min_replies:100 |
filter:has_engagement | Tweets with at least one interaction (like, retweet, or reply). Can be negated to find zero-engagement tweets. | from:username filter:has_engagement |
min_faves:10) and increase gradually. Counts become approximate for very large values (1000+). Combining engagement filters with -filter:retweets ensures you see only original content that earned its engagement organically.
4. Media and Content Type Filters
Control what kind of content appears in your results - images, videos, links, polls, GIFs, or specific tweet types like replies and quote tweets.
| Operator | Description |
|---|
filter:media | All media types (images, video, GIFs). |
filter:images | All images, including third-party links (e.g., Instagram). |
filter:twimg | Only native Twitter images (pic.twitter.com links). |
filter:videos | All video types: native Twitter video, YouTube embeds, etc. |
filter:native_video | Only Twitter-owned video (native uploads, Vine, Periscope). |
filter:consumer_video | Twitter native video only (excludes pro/Amplify). |
filter:pro_video | Twitter pro video (Amplify) only. |
filter:spaces | Twitter Spaces audio content. |
filter:links | Tweets containing any URL. Includes media URLs - use -filter:media to isolate non-media links. |
card_name:animated_gif | Specifically matches GIFs. |
| Operator | Description |
|---|
filter:replies | Only tweets that are replies to another tweet. |
-filter:replies | Exclude replies (show only top-level original tweets). |
filter:nativeretweets | Only native retweets (created via the retweet button). |
include:nativeretweets | Include native retweets in results (they are excluded by default). |
filter:retweets | Old-style RT retweets plus quote tweets. |
-filter:retweets | Exclude retweets entirely. |
filter:quote | Only quote tweets. |
quoted_tweet_id:ID | Quotes of a specific tweet by its ID. |
quoted_user_id:ID | All quotes of a specific user by their user ID. |
conversation_id:ID | All tweets in a thread (direct replies and nested replies). |
Special Content Filters
| Operator | Description |
|---|
card_name:poll2choice_text_only | Tweets containing 2-choice text polls. |
card_name:poll3choice_text_only | 3-choice text polls. |
card_name:poll4choice_text_only | 4-choice text polls. |
card_name:poll2choice_image | 2-choice image polls. |
filter:news | Tweets linking to recognized news domains. |
filter:safe | Excludes NSFW / potentially sensitive content. Does not guarantee SFW results in all cases. |
filter:hashtags | Only tweets containing at least one hashtag. |
filter:mentions | Only tweets containing any @mention. |
5. Date, Time, and Snowflake ID Operators
Precise time-based filtering is critical for event analysis, campaign tracking, and historical data extraction.
| Operator | Format | Description |
|---|
since:YYYY-MM-DD | since:2026-01-01 | Tweets posted on or after this date (inclusive). |
until:YYYY-MM-DD | until:2026-03-01 | Tweets posted before this date (not inclusive). |
since:YYYY-MM-DD_HH:MM:SS_UTC | since:2026-03-05_12:00:00_UTC | Precision timestamp with timezone. |
since_time:UNIX | since_time:1142974200 | After a specific Unix timestamp (in seconds). |
until_time:UNIX | until_time:1142974215 | Before a specific Unix timestamp. |
within_time:Xd | within_time:2d | Within the last X days. Also supports h (hours), m (minutes), s (seconds). |
since_id:ID | since_id:1234567890 | After a specific Snowflake ID (not inclusive). |
max_id:ID | max_id:1234567890 | At or before a specific Snowflake ID (inclusive). |
"product name" since:2026-02-10 until:2026-02-17 lang:en min_faves:5
Snowflake ID Trick
Every tweet ID on X is a Snowflake ID that encodes its creation timestamp. You can convert between IDs and timestamps using this formula:
Millisecond Epoch = (tweet_id >> 22) + 1288834974657
since_id and max_id give you exact tweet-level control over your result window. For more on working with historical tweet data, see Historical Data.
6. Geographical and Location Filters
Very few tweets carry precise geolocation data (estimated at 1-2% of all tweets). Twitter removed precise location tagging from the main iOS/Android apps in June 2019, though users can still tag tweets with Place objects.
| Operator | Description | Example |
|---|
near:"city" | Geotagged near a named place. Supports phrases. | near:"San Francisco" |
near:me | Near your current location (X UI only). | near:me |
within:Xkm | Radius limit for near:. Accepts km or mi. | earthquake near:Tokyo within:50km |
geocode:lat,long,radius | Pinpoint precision using coordinates. | geocode:37.77,-122.41,5km |
place:ID | Search by X Place Object ID. | place:96683cc9126741d1 (USA) |
7. Language and Source Filters
Language
X supports 2-letter ISO 639-1 language codes. Common examples: lang:en (English), lang:es (Spanish), lang:fr (French), lang:de (German), lang:ja (Japanese), lang:ru (Russian).
There are also several special language codes:
| Code | Meaning |
|---|
lang:und | Undefined language (emoji-only or media-only tweets). |
lang:qme | Tweets with media links only (since 2022). |
lang:qst | Very short text tweets. |
lang:qht | Tweets with hashtags only. |
lang:qam | Tweets with mentions only. |
lang:qct | Tweets with cashtags only. |
lang:zxx | Tweets with media or Twitter Card only, no additional text. |
Source (Posting Client)
| Operator | Description | Example |
|---|
source:client_name | Filter by the app used to post the tweet. Use underscores for spaces. | source:Twitter_for_iPhone |
Twitter_for_iPhone, Twitter_for_Android, Twitter_Web_App, TweetDeck, twitter_ads. Note that source: sometimes requires another operator alongside it to return results.
8. App-Specific and Card Operators
These operators match on Twitter Card metadata - the rich previews attached to tweets containing links, media, and embedded content.
| Operator | Description |
|---|
card_domain:domain | Matches the domain name in a Twitter Card. Mostly equivalent to url:. |
card_url:domain | Similar to card_domain: but may return different results. |
card_name:audio | Tweets with Player Cards (Spotify, SoundCloud, etc.). |
card_name:player | Tweets with any Player Card. |
card_name:summary | Small-image summary cards. |
card_name:summary_large_image | Large-image summary cards. |
card_name:promo_website | Promoted website cards (usually posted via Ads). |
card_name:promo_image_convo | Conversational ad cards with images. |
card_name:promo_video_convo | Conversational ad cards with video. |
url:domain | Matches URLs. Works well for domains and subdomains, less reliably for long URL paths. YouTube video IDs work well. |
card_name: operator typically only works for tweets from the last 7-8 days.
9. Practical Query Recipes (Copy-Paste Ready)
Mastering advanced search is about combining operators into a single, precise query string. Here are high-value combinations for common scenarios.
Brand and Reputation Monitoring
Find viral original content about a brand, excluding the brand’s own posts and noisy retweets:
("Tesla" OR "Elon Musk") min_faves:500 filter:links lang:en -from:tesla -filter:nativeretweets
Competitor Analysis and Lead Generation
Find users asking questions or looking for alternatives in your niche:
("notion" OR "obsidian") "?" -filter:links -from:notionhq
Influencer Discovery
Find high-engagement original posts from verified accounts in a topic:
"machine learning" filter:blue_verified min_faves:200 -filter:replies -filter:retweets lang:en
OSINT and Breaking News
Track specific events from X Premium sources with visual evidence:
"breaking news" filter:images since:2026-03-01 filter:blue_verified
Content Curation from X Lists
Find viral videos or GIFs posted by members of a specific X List:
list:715919216927322112 (filter:videos OR card_name:animated_gif) min_retweets:50
Developer Troubleshooting
Find conversations about bugs or errors that include GitHub links:
url:github.com "error" lang:en filter:replies
Crypto and Finance Sentiment
Track sentiment-laden discussions about a token with engagement gating:
(bitcoin OR $BTC) (bullish OR bearish OR crash OR moon) min_faves:20 lang:en since:2026-01-01 -filter:retweets
Hyper-Local Monitoring
Find what people are saying near a specific location in a tight timeframe:
"traffic" near:"London" within:5km since:2026-03-05_12:00:00_UTC
Searching for Quotes of a Specific User
Find all tweets that quote someone by searching for their tweet URL pattern and excluding their own handle:
twitter.com/elonmusk/status/ -elonmusk
10. How to Use Operators with the Sorsa API
Every operator listed above works in the query field of the Sorsa /v3/search-tweets endpoint. Pass your full query string - operators included - as a POST request:
curl -X POST https://api.sorsa.io/v3/search-tweets \
-H "ApiKey: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "(AI OR \"machine learning\") min_faves:100 lang:en -filter:retweets",
"order": "popular"
}'
Python Example
import requests
response = requests.post(
"https://api.sorsa.io/v3/search-tweets",
headers={
"ApiKey": "YOUR_API_KEY",
"Content-Type": "application/json",
},
json={
"query": '("your brand" OR "@yourbrand") -from:yourbrand min_faves:5 lang:en',
"order": "latest",
},
)
data = response.json()
for tweet in data.get("tweets", []):
print(f"@{tweet['user']['username']}: {tweet['full_text'][:100]}")
print(f" Likes: {tweet['likes_count']} | RTs: {tweet['retweet_count']}\n")
JavaScript Example
const response = await fetch("https://api.sorsa.io/v3/search-tweets", {
method: "POST",
headers: {
"ApiKey": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
query: '("your brand" OR "@yourbrand") -from:yourbrand min_faves:5 lang:en',
order: "latest",
}),
});
const data = await response.json();
for (const tweet of data.tweets || []) {
console.log(`@${tweet.user.username}: ${tweet.full_text.slice(0, 100)}`);
console.log(` Likes: ${tweet.likes_count} | RTs: ${tweet.retweet_count}\n`);
}
next_cursor value from the response to your next request. See Pagination and Search Tweets for complete pagination examples.
Building Complex Queries: Order of Operations
When constructing your own advanced query strings, follow this sequence:
- Group your core keywords in parentheses:
(bitcoin OR ethereum OR $BTC)
- Add content constraints:
lang:en, filter:images, -filter:replies
- Set engagement thresholds:
min_faves:50, min_retweets:10
- Exclude noise:
-from:spambot, -scam, -airdrop, -filter:retweets
- Add time bounds if needed:
since:2026-01-01 until:2026-03-01
Remember that AND has precedence over OR. cat OR black dog is evaluated as cat OR (black dog), not (cat OR black) dog. When in doubt, use parentheses to make your intent explicit.
Known Limitations
A few edge cases and restrictions to keep in mind:
- Operator limit: Queries support roughly 22-23 operators maximum.
- Geo coverage is thin: Only about 1-2% of tweets carry geolocation data. Most users do not opt in to precise location sharing.
card_name: is time-limited: This operator typically only returns results from the past 7-8 days.- Private and suspended accounts are excluded from all search results.
- Language detection is imperfect. Short tweets, code snippets, or emoji-heavy posts may be misclassified.
- Not all tweets are indexed. Twitter’s search index may exclude tweets flagged for platform violations or anti-spam rules.
- Spelling auto-correction happens silently in some cases. Use
+word or "word" to force exact matching.
- URL matching works well for domains and subdomains but is unreliable for long URL paths. Hyphens in domains must be replaced with underscores (e.g.,
url:t_mobile.com).
Source and Acknowledgments
This guide draws on the comprehensive research of the Twitter Advanced Search repository by Igor Brigadir. With over 1,500 stars on GitHub, this project is the industry-standard reference for X search logic, Snowflake ID mechanics, and undocumented operator behaviors.
Next Steps
- Search Tweets - complete guide to the
/search-tweets endpoint with Python and JavaScript examples, pagination, and CSV export.
- Track Mentions - dedicated strategies for tracking @mentions of any account.
- Search Builder - the free visual query builder where you can test any operator combination instantly.
- API Reference - full specification for all Sorsa API endpoints.
- Response Format - complete schema reference for Tweet and User objects.
