X query syntax - APIs | Desearch Docs

Advanced Search on X (Twitter)

Reference for every search operator you can use in an X query string, with a tested example for each.

These operators work on Web, Mobile, and Tweetdeck. There is some overlap, but largely they will not work for the v1.1 Search, Premium Search, or v2 Search APIs.

Adapted from TweetDeck Help, @lucahammer's Guide, @eevee's Twitter Manual, @pushshift, and Twitter / Tweetdeck itself.

Tweet Content

Match on words, phrases, hashtags, cashtags, URLs, and language.

Operator	Finds Tweets	Example
`nasa esa` `(nasa esa)`	Containing both "`nasa`" and "`esa`". Spaces are implicit AND. Brackets can be used to group individual words when using other operators.	🔗
`nasa OR esa`	Either "`nasa`" or "`esa`". OR must be in uppercase.	🔗
`"state of the art"`	The complete phrase "`state of the art`". Will also match "`state-of-the-art`". Also, use quotes to prevent spelling correction.	🔗
`"this is the * time this week"`	A complete phrase with a wildcard. `*` does not work outside of a quoted phrase or without spaces.	🔗
`+radiooooo`	Force a term to be included as-is. Useful to prevent spelling correction.	🔗
`-love` `-"live laugh love"`	`-` is used for excluding "`love`". Also applies to quoted phrases and other operators.	🔗
`#tgif`	A hashtag	🔗
`$TWTR`	A cashtag, like hashtags but for stock symbols	🔗
`What ?`	Question marks are matched	🔗
`:) OR :(`	Some emoticons are matched, positive `:) :-) :P :D` or negative `:-( :(`	🔗
👀	Emoji searches are also matched. Usually needs another operator to work.	🔗
`url:google.com`	URLs are tokenized and matched, working very well for subdomains and domains, but not as well for long URLs, which depend on the specific URL. YouTube IDs work well. Works for both shortened and canonical URLs, eg,`gu.com` shortener for `theguardian.com`. When searching for Domains with hyphens in them, you have to replace the hyphen with an underscore (like `url:t_mobile.com`) but underscores `_` are also tokenized out, and may not match	🔗
`lang:en`	Search for tweets in specified language, not always accurate, see the full list and special `lang` codes below.	🔗

Users

Filter by author, recipient, mentions, lists, and verification.

Operator	Finds Tweets	Example
`from:user`	Sent by a particular `@username` e.g. `"dogs from:NASA"`	🔗
`to:user`	Replying to a particular `@username`	🔗
`@user`	Mentioning a particular `@username`. Combine with `-from:username` to get only mentions	🔗
`list:715919216927322112` `list:esa/astronauts`	Tweets from members of this public list. Use the list ID from the API or with URLs like `twitter.com/i/lists/715919216927322112`. List slug is for old list URLs like `twitter.com/esa/lists/astronauts`. Cannot be negated, so you can't search for "not on list".	🔗
`filter:verified`	From verified users	🔗
`filter:blue_verified`	From "verified" users who paid $8 for Twitter Blue	🔗
`filter:follows`	Only from accounts you follow. Cannot be negated.	🔗
`filter:social` `filter:trusted`	Only from an algorithmically expanded network of accounts based on your own follows and activities. Works on "`Top`" results not "`Latest`"	🔗

Geo

Filter by location, radius, or Place ID.

Operator	Finds Tweets	Example
`near:city`	Geotagged in this place. Also supports Phrases, eg: `near:"The Hague"`	🔗
`near:me`	Near where Twitter thinks you are	🔗
`within:radius`	Within a specific radius of the "near" operator, to apply a limit. Can use km or mi. e.g. `fire near:san-francisco within:10km`	🔗
`geocode:lat,long,radius`	E.g., to get tweets 10km around Twitter's hq, use `geocode:37.7764685,-122.4172004,10km`	🔗
`place:96683cc9126741d1`	Search tweets by Place Object ID eg: USA Place ID is `96683cc9126741d1`	🔗

Time

Filter by date, time, Unix timestamp, or tweet ID.

Operator	Finds Tweets	Example
`since:2021-12-31`	On or after (inclusive) a specified date. 4 digit year, 2 digit month, 2 digit day separated by `-` a dash.	🔗
`until:2021-12-31`	Before (NOT inclusive) a specified date. Combine with a "since" operator for dates between.	🔗
`since:2021-12-31_23:59:59_UTC`	On or after (inclusive) a specified date and time in the specified timezone. 4 digit year, 2 digit month, 2 digit day separated by `-` dashes, an `_` underscore separating the 24-hour clock format hours:minutes:seconds and timezone abbreviation.	🔗
`until:2021-12-31_23:59:59_UTC`	Before (NOT inclusive) a specified date and time in the specified timezone. Combine with a "since" operator for dates between.	🔗
`since_time:1142974200`	On or after a specified Unix timestamp in seconds. Combine with the "until" operator for dates between. Maybe easier to use than `since_id` below.	🔗
`until_time:1142974215`	Before a specified Unix timestamp in seconds. Combine with a "since" operator for dates between. Maybe easier to use than `max_id` below.	🔗
`since_id:tweet_id`	After (NOT inclusive) a specified Snowflake ID (See Note) below)	🔗
`max_id:tweet_id`	At or before (inclusive) a specified Snowflake ID (see Note below)	🔗
`within_time:2d` `within_time:3h` `within_time:5m` `within_time:30s`	Search within the last number of days, hours, minutes, or seconds	🔗

Tweet Type

Filter by retweet, reply, thread, quote, or poll.

Operator	Finds Tweets	Example
`filter:nativeretweets`	Only retweets created using the retweet button. Works well combined with `from:` to show only retweets. Only works within the last 7-10 days or so.	🔗
`include:nativeretweets`	Native retweets are excluded by default. This shows them. In contrast to `filter:`, which indicates only retweets, and this includes retweets in addition to other tweets. Only works within the last 7-10 days or so.	🔗
`filter:retweets`	Old-style retweets ("RT") + quoted tweets.	🔗
`filter:replies`	The tweet is a reply to another Tweet. good for finding conversations, or threads if you add or remove `to:user`	🔗
`filter:self_threads`	Only self-replies. Tweets that are part of a thread, not replies in other conversations.	🔗
`conversation_id:tweet_id`	Tweets that are part of a thread (direct replies and other replies)	🔗
`filter:quote`	Contain Quote Tweets	🔗
`quoted_tweet_id:tweet_id`	Search for quotes of a specific tweet	🔗
`quoted_user_id:user_id`	Search for all quotes of a specific user, by numeric User ID (See Note below)	🔗
`card_name:poll2choice_text_only` `card_name:poll3choice_text_only` `card_name:poll4choice_text_only` `card_name:poll2choice_image` `card_name:poll3choice_image` `card_name:poll4choice_image`	Tweets containing polls. For polls containing 2, 3, 4, or image choices.	🔗

Engagement

Filter by reply, like, and retweet counts.

Operator	Finds Tweets	Example
`filter:has_engagement`	Has some engagement (replies, likes, retweets). Can be negated to find tweets with no engagement. Note all of these are mutually exclusive with `filter:nativeretweets` or `include:nativeretweets`, as they apply to the retweet, not the original tweet, so they won't work as expected.	🔗
`min_retweets:5`	A minimum number of Retweets. Counts appear to be approximate for larger values (e.g., 1000+).	🔗
`min_faves:10`	A minimum number of Likes	🔗
`min_replies:100`	A minimum number of replies	🔗
`-min_retweets:500`	A maximum number of Retweets	🔗
`-min_faves:500`	A maximum number of Likes	🔗
`-min_replies:100`	A maximum number of replies	🔗

Media

Filter by attached images, video, and Spaces.

Operator	Finds Tweets	Example
`filter:media`	All media types.	🔗
`filter:twimg`	Native Twitter images (`pic.twitter.com` links)	🔗
`filter:images`	All images.	🔗
`filter:videos`	All video types, including native Twitter video and external sources such as YouTube.	🔗
`filter:periscope`	Periscopes	🔗
`filter:native_video`	All Twitter-owned video types (native video, Vine, Periscope)	🔗
`filter:vine`	Vines (RIP)	🔗
`filter:consumer_video`	Twitter native video only	🔗
`filter:pro_video`	Twitter pro video (Amplify) only	🔗
`filter:spaces`	Twitter Spaces only	🔗

More Filters

Filter by links, mentions, news, safety, and hashtags.

Operator	Finds Tweets	Example
`filter:links`	Only containing some URLs, including media. use `-filter:media` for urls that aren't media	🔗
`filter:mentions`	Containing any sort of `@mentions`	🔗
`filter:news`	It contains a link to a news story. Combine with a list operator to further narrow down the user set. Matches on a list of Domains (See Note for full list)	🔗
`filter:safe`	Excluding NSFW content. Excludes content that users have marked as "Potentially Sensitive". Doesn't always guarantee SFW results.	🔗
`filter:hashtags`	Only Tweets with Hashtags.	🔗

App Specific

Filter by client app and Twitter Card type.

Operator	Finds Tweets	Example
`source:client_name`	Sent from a specified client e.g., source:tweetdeck (See Note for common ones,) e.g. `twitter_ads` doesn't work on it's own, but does with another operator.	🔗
`card_domain:pscp.tv`	Matches domain name in a Twitter Card. Mostly equivalent to `url:` operator.	🔗
`card_url:pscp.tv`	Matches domain name in a Card, but with different results to `card_domain`.	🔗
`card_name:audio`	Tweets with a Player Card (Links to Audio sources, Spotify, Soundcloud etc.)	🔗
`card_name:animated_gif`	Tweets With GIFs	🔗
`card_name:player`	Tweets with a Player Card	🔗
`card_name:app` `card_name:promo_image_app`	Tweets with links to an App Card. `promo_app` does not work, `promo_image_app` is for an app link with a large image, usually posted in Ads.	🔗
`card_name:summary`	Only Small image summary cards	🔗
`card_name:summary_large_image`	Only large image Cards	🔗
`card_name:promo_website`	Larger than `summary_large_image`, usually posted via Ads	🔗
`card_name:promo_image_convo` `card_name:promo_video_convo`	Finds Conversational Ads cards.	🔗
`card_name:3260518932:moment`	Find Moments cards. `3260518932` is the user ID of `@TwitterMoments`, but the search finds moments for everyone, not that specific user.	🔗

Matching

How keyword operators match, and which tweets are excluded from the index.

Keyword operators can match the user's name, the @ screen name, tweet text, and both shortened and expanded URL text. For example, url:trib.al finds accounts that use that shortener even though the full URL is displayed.

By default, "Top" results are shown: tweets with some level of engagement. "Latest" has the most recent tweets. People search matches on descriptions, but not all operators work there. "Photos" and "Videos" are presumably equivalent to filter:images and filter:videos.

Exact tokenization is not known. URLs are tokenized. Spelling correction appears sometimes, and plurals are matched: bears also matches bear. A - not preceding an operator is removed, so "state-of-the-art" is the same as "state of the art".

Private accounts are not in the search index, so their tweets do not appear. Locked and suspended accounts are also hidden. Tweets can also be missing when anti-spam measures apply or indexing failed.

Twitter treats some words as signals. Searching "photo" is assumed to mean tweets with attached photos. To match the literal word, wrap it in double quotes: "photo".

Building Queries

Combine operators with spaces (implicit AND), uppercase OR, parentheses, and - for negation.

Most filter:type operators can be negated with -, with exceptions like filter:follows. exclude:links is the same as -filter:links. If a search doesn't work, try an alias like that.

Example 1: I want mentions of either "puppy" or "kitten", AND with mentions of either "sweet" or "cute", excluding Retweets, with at least 10 likes.

(puppy OR kitten) (sweet OR cute) -filter:nativeretweets min_faves:10
Example 2: I want Tweets from @Nasa with all types of media except images

from:NASA filter:media -filter:images
Example 3: I want mentions of "space" and either "big" or "large" by members of the NASA astronauts List, sent from an iPhone or twitter.com, with images, excluding mentions of #asteroid, since 2011.

space (big OR large) list:nasa/astronauts (source:twitter_for_iphone OR source:twitter_web_client) filter:images since:2011-01-01 -#asteroid

Limitations

card_name: only works for the last 7-8 days. The maximum number of operators seems to be about 22 or 23. All Time operators must be combined with something else to work.

Tweetdeck Equivalents

Tweetdeck column options have web search equivalents:

Tweets with Images: filter:images
Videos: filter:videos
Tweets with GIFs: card_name:animated_gif
"Tweets with broadcasts": (card_domain:pscp.tv OR card_domain:periscope.tv OR "twitter.com/i/broadcasts/")
"Any Media": (filter:images OR filter:videos)
"Any Links (includes media)": filter:links

📘 Standard API Search

Web, Mobile, and Tweetdeck search run on one system. Standard API Search is a different index. Premium and Enterprise Search are separate products based on Gnip.

Snowflake IDs

User, tweet, DM, and some other object IDs are snowflake IDs: each ID contains a timestamp. Tweets since 2010-06-01, user IDs since 2013-01-22.

An easy way to get a user_id from a @user_name is tweeterid.com.

To use tweet IDs with since_id / max_id as time delimiters, either pick a tweet ID with roughly the created_at time you need (all times on Twitter are UTC), or convert directly:

Convert Twitter ID to Millisecond Epoch

(tweet_id >> 22) + 1288834974657 -- This gives the millisecond epoch of when the tweet or user was created.

Convert from Epoch back to a Tweet Id

(millisecond_epoch - 1288834974657) << 22 = tweet id

Use Case

You want to gather all tweets for a search term starting at August 4, 2019 09:00:00 UTC. Convert the epoch milliseconds to a tweet ID (use https://www.epochconverter.com):

August 4, 2019 09:00:00 UTC = 1564909200000 (epoch milliseconds)

(1564909200000 - 1288834974657) << 22 = 1157939227653046272 (tweet id)

Set max_id to 1157939227653046272 to collect tweets earlier than that datetime.

python

def convert_milliepoch_to_tweet_id(milliepoch):
    if milliepoch <= 1288834974657:
        raise ValueError("Date is too early (before snowflake implementation)")
    return (milliepoch - 1288834974657) << 22

📘 64 Bit Integer in Javascript

JavaScript does not support 64bit integers, so these calculations often fail in unexpected ways. More details on snowflake in @pushshift's document here.

Quote-Tweets

Quote-Tweets are tweets containing the URL of another tweet, so search for that URL. Remove any URL parameters first: Twitter appends a client parameter when copying tweet URLs through the sharing menu, e.g. ?s=20 for the Web App and ?s=09 for Android. Example: twitter.com/jack/status/20/ -from:jack

To find all tweets that quote a specific user, search for the first part of the tweet URL and exclude the user: twitter.com/jack/status/ -from:jack.

Geo Searches

Very few tweets have exact geo coordinates. Exact coordinates are phased out for normal tweets but remain for photos: https://twitter.com/TwitterSupport/status/1141039841993355264

Tweets can instead be tagged by Place.

Known Unknowns and Assumptions

Behavior that is observed but not documented by Twitter:

filter:news appears to match a whitelist of news domains. The list is not public.
lang:und matches most empty tweets, or tweets with only a number or a link.
filter:safe presumably uses the "Contains Sensitive Content" user setting, and may also apply to specific tweets.
Tweets composed in Twitter Ads are available with source:twitter_ads. Other promoted tweets may not have been created with that app.
Collections and Moments can be found with url: searches, eg url:twitter.com/i/events and url:twitter.com/i/moments, but url:twitter.com url:timelines has many false positives.
In Search Settings, the "Hide Sensitive Content" equivalent is filter:safe. No known equivalent exists for "Remove Blocked and Muted Accounts".

Supported Languages

Language is specified as a 2 letter ISO code. It is tagged automatically from the tweet text and not always accurate; see here for notes on accuracy.

Supported Languages

lang:am Amharic (አማርኛ)

lang:ar Arabic (العربية)

lang:bg Bulgarian (Български)

lang:bn Bengali (বাংলা)

lang:bo Tibetan (བོད་སྐད)

lang:ca Catalan (Català)

lang:ch` Cherokee (ᏣᎳᎩ)

lang:cs Czech (čeština)

lang:da Danish (Dansk)

lang:de German (Deutsch)

lang:dv Maldivian (ދިވެހި)

lang:el Greek (Ελληνικά)

lang:en English (English)

lang:es Spanish (Español)

lang:et Estonian (eesti)

lang:fa Persian (فارسی)

lang:fi Finnish (Suomi)

lang:fr French (Français)

lang:gu Gujarati (ગુજરાતી)

lang:hi Hindi (हिंदी)

lang:ht Haitian Creole (Kreyòl ayisyen)

lang:hu Hungarian (Magyar)

lang:hy Armenian (Հայերեն)

lang:in Indonesian (Bahasa Indonesia)

lang:is Icelandic (Íslenska)

lang:it Italian (Italiano)

lang:iu Inuktitut (ᐃᓄᒃᑎᑐᑦ)

lang:iw Hebrew (עברית)

lang:ja Japanese (日本語)

lang:ka Georgian (ქართული)

lang:km Khmer (ខ្មែរ)

lang:kn Kannada (ಕನ್ನಡ)

lang:ko Korean (한국어)

lang:lo Lao (ລາວ)

lang:lt Lithuanian (Lietuvių)

lang:lv Latvian (latviešu valoda)

lang:ml Malayalam (മലയാളം)

lang:my Myanmar (မြန်မာဘာသာ)

lang:ne Nepali (नेपाली)

lang:nl Dutch (Nederlands)

lang:no Norwegian (Norsk)

lang:or Oriya (ଓଡ଼ିଆ)

lang:pa Panjabi (ਪੰਜਾਬੀ)

lang:pl Polish (Polski)

lang:pt Portuguese (Português)

lang:ro Romanian (limba română)

lang:ru Russian (Русский)

lang:si Sinhala (සිංහල)

lang:sk Slovak (slovenčina)

lang:sl Slovene (slovenski jezik)

lang:sv Swedish (Svenska)

lang:ta Tamil (தமிழ்)

lang:te Telugu (తెలుగు)

lang:th Thai (ไทย)

lang:tl Tagalog (Tagalog)

lang:tr Turkish (Türkçe)

lang:uk Ukrainian (українська мова)

lang:ur Urdu (ﺍﺭﺩﻭ)

lang:vi Vietnamese (Tiếng Việt)

lang:zh Chinese (中文)

Searching for lang:chr, lang:iu, lang:sk seems to fail: tweets matching the keywords are returned instead of the language.

Some special language codes work:

lang:und for undefined language
lang:qam for tweets with mentions only (works for tweets since 2022-06-14)
lang:qct for tweets with cashtags only (works for tweets since 2022-06-14)
lang:qht for tweets with hashtags only (works for tweets since 2022-06-14)
lang:qme for tweets with media links (works for tweets since 2022-06-14)
lang:qst for tweets with a very short text (works for tweets since 2022-06-14)
lang:zxx for tweets with either media or Twitter Card only, without any additional text (works for tweets since 2022-06-14)

Common Clients

source: should work for any API client. Try putting the client name in quotes or replacing spaces with underscores. This is the App name field from the developer app configuration page, so anyone can set anything here and appear to tweet from a made-up client. You cannot copy an existing name. This operator must be combined with something else to work, eg lang:en.

Official Twitter Clients

twitter_web_client

twitter_web_app

twitter_for_iphone

twitter_for_ipad

twitter_for_mac

twitter_for_android

twitter_ads

tweetdeck

tweetdeck_web_app

twitter_for_advertisers

twitter_media_studio

cloudhopper (tweets via sms service)

X (Twitter) Queries