> ## 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.

# Search Operators

X search operators are special keywords and symbols that filter tweets by author, date, engagement, media type, language, location, and other attributes. Most operators on this page work in the `query` field of the [Search Tweets](https://docs.sorsa.io/api-reference/search/search-tweets) endpoint and on x.com. A few are marked UI only: those depend on a signed-in account (your follows, your location, your network) and do not work through the API.

> **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](https://api.sorsa.io/blog/twitter-search-operators) on the blog.

## Syntax basics

* Spaces between terms act as **implicit AND**
* `OR` must be **uppercase**
* Use a leading dash (`-`) to **exclude** a term, phrase, or operator
* Group expressions with **parentheses**
* Wrap exact phrases in **double quotes**

Operators can be combined freely up to roughly 22-23 operators per query. AND binds tighter than OR: `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](https://api.sorsa.io/playground/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`                              |

Plurals match their singulars and vice versa. Operators match against tweet body, the author's display name, screen name, and expanded URLs inside the tweet.

***

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

Counts become approximate for very large values (1,000+).

***

## 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).    |

**Snowflake ID conversion.** Every tweet ID encodes its creation timestamp:

```text theme={null}
millisecond_epoch = (tweet_id >> 22) + 1288834974657
```

For pulling historical sets, see [Historical Data](https://docs.sorsa.io/historical-data).

***

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

Only an estimated 1-2% of tweets carry precise geolocation data. If a tweet does not have coordinates, the API falls back to reverse-geocoding the user's profile location.

***

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

Common values: `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:

1. **Group core keywords:** `(bitcoin OR ethereum OR $BTC)`
2. **Add content constraints:** `lang:en`, `filter:images`, `-filter:replies`
3. **Set engagement thresholds:** `min_faves:50`, `min_retweets:10`
4. **Exclude noise:** `-from:spambot`, `-scam`, `-filter:retweets`
5. **Add time bounds:** `since:2026-01-01 until:2026-03-01`

For full code examples (Python and JavaScript with pagination and rate-limit handling) and 14 production-ready query recipes, see the [full guide on the blog](https://api.sorsa.io/blog/twitter-search-operators).

***

## 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 `+word` or `"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](https://github.com/igorbrigadir/twitter-advanced-search) by Igor Brigadir, the industry-standard source on undocumented X search behavior.

***

## Next Steps

* [Search Tweets](https://docs.sorsa.io/search-tweets) - complete guide to the `/search-tweets` endpoint.
* [Track Mentions](https://docs.sorsa.io/search-mentions) - strategies for tracking @mentions of any account.
* [Pagination](https://docs.sorsa.io/pagination) - paginating through large result sets.
* [Search Builder](https://api.sorsa.io/playground/search-builder) - free visual query builder.
* [Full Cheat Sheet on the Blog](https://api.sorsa.io/blog/twitter-search-operators) - recipes, code examples, and X API v2 comparison.