query field of the Search Tweets endpoint and on x.com.
Note: For a complete guide with copy-paste recipes, production code examples (Python and JavaScript with pagination), and a side-by-side comparison against the official X API v2 operator set, see the Twitter Search Operators Complete Cheat Sheet on the blog.
Syntax basics
- Spaces between terms act as implicit AND
ORmust be uppercase- Use a leading dash (
-) to exclude a term, phrase, or operator - Group expressions with parentheses
- Wrap exact phrases in double quotes
cat OR black dog is evaluated as cat OR (black dog). Use parentheses to eliminate ambiguity.
Free Visual Query Builder
If you don’t want to assemble operator strings by hand, use the Sorsa Search Builder. It is a free, no-login tool with a graphical interface where you toggle filters and preview the generated query string before integrating it into your code.1. Keyword and Boolean Logic
| Operator | Description | Example |
|---|---|---|
keyword keyword | Tweets containing both terms (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. Also prevents auto-correction. | "state of the art" |
-keyword | Excludes tweets containing the term, phrase, or operator. | crypto -scam |
( ) | Groups terms for complex Boolean logic. | (AI OR "machine learning") lang:en |
"word * word" | Wildcard inside a quoted phrase. The * replaces any single word. | "this is the * time" |
+word | Forces exact match, preventing auto-correction and stemming. | +radiooooo |
#hashtag | Matches a specific hashtag. | #tgif |
$cashtag | Matches a stock or crypto symbol. | $TSLA |
2. User and Account Filters
| 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. Web UI only, cannot be negated. | filter:follows |
filter:social | From your algorithmically expanded network. Works on “Top” results, not “Latest”. | filter:social |
3. Engagement Gating
| 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. | news -min_retweets:500 |
-min_replies:N | Maximum replies. | tech -min_replies:100 |
filter:has_engagement | Tweets with at least one interaction. Can be negated to find zero-engagement tweets. | from:username filter:has_engagement |
4. Media and Content Type
Media filters
| Operator | Description |
|---|---|
filter:media | All media types (images, video, GIFs). |
filter:images | All images, including third-party links. |
filter:twimg | Only native X images (pic.twitter.com links). |
filter:videos | All video types: native X video, YouTube embeds, etc. |
filter:native_video | Only X-owned video (native uploads, legacy Vine, legacy Periscope). |
filter:consumer_video | X native video only (excludes pro/Amplify). |
filter:pro_video | X pro video (Amplify) only. |
filter:spaces | X 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. |
Tweet type filters
| 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 (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 | 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 or potentially sensitive content. Not a guarantee. |
filter:hashtags | Only tweets containing at least one hashtag. |
filter:mentions | Only tweets containing any @mention. |
5. Date, Time, and Snowflake IDs
| 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 (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, m, s. |
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). |
6. Geographical Filters
| Operator | Description | Example |
|---|---|---|
near:"city" | Geotagged near a named place. Supports phrases. | near:"San Francisco" |
near:me | Near your current location (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 |
7. Language and Source
Language
Standard ISO 639-1 codes (lang:en, lang:es, lang:fr, lang:de, lang:ja, lang:ru, etc.) plus the following X-specific 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 text. |
Source (posting client)
| Operator | Description | Example |
|---|---|---|
source:client_name | Filter by the app used to post. Use underscores for spaces. | source:Twitter_for_iPhone |
Twitter_for_iPhone, Twitter_for_Android, Twitter_Web_App, TweetDeck, twitter_ads.
8. Card and URL Operators
| Operator | Description |
|---|---|
card_domain:domain | Matches the domain 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. |
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. Replace hyphens with underscores (e.g., url:t_mobile.com). |
card_name: typically only matches tweets from the last 7-8 days.
Building queries
A practical construction order that scales:- Group core keywords:
(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,-filter:retweets - Add time bounds:
since:2026-01-01 until:2026-03-01
Known limitations
- Operator cap: roughly 22-23 operators maximum per query.
- Geo coverage is thin: only 1-2% of tweets have precise location data.
card_name:is time-limited to the past 7-8 days.- Private and suspended accounts are excluded from search results.
- Language detection is imperfect for short tweets, code, or emoji-heavy posts.
- Not all tweets are indexed. Tweets flagged for platform violations may be excluded.
- Auto-correction happens silently in some cases. Use
+wordor"word"to force exact matching. - URL matching works for domains and subdomains but is unreliable for long URL paths.
Source
This reference draws on the maintained twitter-advanced-search repository by Igor Brigadir, the industry-standard source on undocumented X search behavior.Next Steps
- Search Tweets - complete guide to the
/search-tweetsendpoint. - Track Mentions - strategies for tracking @mentions of any account.
- Pagination - paginating through large result sets.
- Search Builder - free visual query builder.
- Full Cheat Sheet on the Blog - recipes, code examples, and X API v2 comparison.