#hashtag
operator, which is standalone:
#xapiv2
Conjunction-required operators cannot be used by themselves in a query; they can only be used when at least one standalone operator is included in the query. This is because using these operators alone would be far too general, and would match on an extremely high volume of Posts.
For example, the following queries are not supported since they contain only conjunction-required operators:
has:media
has:links OR is:retweet
If we add in a standalone operator, such as the phrase "X data"
, the query would then work properly.
"X data" has:mentions (has:media OR has:links)
AND logic | Successive operators with a space between them will result in boolean “AND” logic, meaning that Posts will match only if both conditions are met. For example, snow day #NoSchool will match Posts containing the terms snow and day and the hashtag #NoSchool. |
OR logic | Successive operators with OR between them will result in OR logic, meaning that Posts will match if either condition is met. For example, specifying grumpy OR cat OR #meme will match any Posts containing at least the terms grumpy or cat, or the hashtag #meme. |
NOT logic, negation | Prepend a dash (-) to a keyword (or any operator) to negate it (NOT). For example, cat #meme -grumpy will match Posts containing the hashtag #meme and the term cat, but only if they do not contain the term grumpy. One common query clause is -is:retweet , which will not match on Retweets, thus matching only on original Posts, Quote Tweets, and replies. All operators can be negated, but negated operators cannot be used alone. |
Grouping | You can use parentheses to group operators together. For example, (grumpy cat) OR (#meme has:images) will return either Posts containing the terms grumpy and cat, or Posts with images containing the hashtag #meme. Note that ANDs are applied first, then ORs are applied. |
-is:nullcast
must always be negated.
Negated operators cannot be used alone.
Do not negate a set of operators grouped together in a set of parentheses. Instead, negate each individual operator. For example, instead of using skiing -(snow OR day OR noschool)
, we suggest that you use skiing -snow -day -noschool
.
apple OR iphone ipad
would be evaluated as apple OR (iphone ipad)
ipad iphone OR android
would be evaluated as (iphone ipad) OR android
(apple OR iphone) ipad
iphone (ipad OR android)
Diacrítica
or hashtag #cumpleaños
will match Diacrítica or #cumpleaños, as well as with Diacritica or #cumpleanos without the tilde í or eñe.
Characters with accents or diacritics are treated the same as normal characters and are not treated as word boundaries. For example, a query with the keyword cumpleaños
would only match activities containing the word cumpleaños and would not match activities containing cumplea, cumplean, or os.
All operators are evaluated in a case-insensitive manner. For example, the query cat
will match Posts with all of the following: cat, CAT, Cat.
The filtered stream matching behavior acts differently from Search Posts. When building a filtered stream rule, know that keywords and hashtags that include accents and diacritics will only match on terms that also include the accent and diacritic, and will not match on terms that use normal characters instead.
For example, filtered stream rules that include a keyword Diacrítica
or hashtag #cumpleaños
will only match the terms Diacrítica and #cumpleaños, and will not match on Diacritica or #cumpleanos without the tilde í or eñe
happy
you will likely get anywhere from 200,000 - 300,000 Posts per day.(happy OR happiness) place_country:GB -birthday -is:retweet
(happy OR happiness) place_country:GB -birthday -is:retweet
happy OR happiness
lang:
operator:
(happy OR happiness) lang:en
The test delivered a number of Posts wishing people a happy birthday, so we are going to add -birthday
as a negated keyword operator. We also want to only receive original Posts, so we’ve added the negated -is:retweet
operator:
(happy OR happiness) lang:en -birthday -is:retweet
excited
and elated
.
(happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet
-holidays
keyword.
(happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet -holidays
query
parameter. As with any query parameters, you must make sure to HTTP encode the query that you developed.
Here is an example of what this might look like using a cURL command, with an additional tweet.fields
and max_results
parameter included. If you would like to use this command, please make sure to replace $BEARER_TOKEN
with your own Bearer Token:
has:geo (from:NWSNHC OR from:NHC\_Atlantic OR from:NWSHouston OR from:NWSSanAntonio OR from:USGS\_TexasRain OR from:USGS_TexasFlood OR from:JeffLindner1) -is:retweet
And here is what the query would look like with the HTTP encoding, the query parameter, and the recent search URI:
https://api.x.com/2/tweets/search/recent?query=-is%3Aretweet%20has%3Ageo%20(from%3ANWSNHC%20OR%20from%3ANHC\_Atlantic%20OR%20from%3ANWSHouston%20OR%20from%3ANWSSanAntonio%20OR%20from%3AUSGS\_TexasRain%20OR%20from%3AUSGS_TexasFlood%20OR%20from%3AJeffLindner1)
#nowplaying (happy OR exciting OR excited OR favorite OR fav OR amazing OR lovely OR incredible) (place\_country:US OR place\_country:MX OR place_country:CA) -horrible -worst -sucks -bad -disappointing
#nowplaying (horrible OR worst OR sucks OR bad OR disappointing) (place\_country:US OR place\_country:MX OR place_country:CA) -happy -exciting -excited -favorite -fav -amazing -lovely -incredible
And here is what the query would look like with the HTTP encoding, the query parameter, and the recent search URI:
https://api.x.com/2/tweets/search/recent?query=%23nowplaying%20(happy%20OR%20exciting%20OR%20excited%20OR%20favorite%20OR%20fav%20OR%20amazing%20OR%20lovely%20OR%20incredible)%20(place\_country%3AUS%20OR%20place\_country%3AMX%20OR%20place_country%3ACA)%20-horrible%20-worst%20-sucks%20-bad%20-disappointing
https://api.x.com/2/tweets/search/recent?query=%23nowplaying%20(horrible%20OR%20worst%20OR%20sucks%20OR%20bad%20OR%20disappointing)%20(place\_country%3AUS%20OR%20place\_country%3AMX%20OR%20place_country%3ACA)%20-happy%20-exciting%20-excited%20-favorite%20-fav%20-amazing%20-lovely%20-incredible
context:
operator to take advantage of the Post annotation functionality. We first used the Post lookup endpoint and the tweet.fields=context_annotations
fields parameter to identify which domain.entity IDs we need to use in our query:
domain
66 (Interests and Hobbies category) with entity 852262932607926273 (Cats). domain
65 (Interests and Hobbies Vertical) with entity 852262932607926273 (Pets). context:65.852262932607926273 -context:66.852262932607926273 -is:retweet has:images lang:ja
And here is what the query would look like with the HTTP encoding, the query parameter, and the recent search URI:
https://api.x.com/2/tweets/search/recent?query=context%3A65.852262932607926273%20-context%3A66.852262932607926273%20-is%3Aretweet%20has%3Aimages%20lang%3Aja
Try out the query builder tool for additional support.
Operator | Type | Description |
---|---|---|
keyword | Standalone | Matches a keyword within the body of a Post. This is a tokenized match, meaning that your keyword string will be matched against the tokenized text of the Post body. Tokenization splits words based on punctuation, symbols, and Unicode basic plane separator characters. For example, a Post with the text “I like coca-cola” would be split into the following tokens: I, like, coca, cola. These tokens would then be compared to the keyword string used in your query. To match strings containing punctuation (for example coca-cola), symbol, or separator characters, you must wrap your keyword in double-quotes. Example: pepsi OR cola OR "coca cola" |
emoji | Standalone | Matches an emoji within the body of a Post. Similar to a keyword, emojis are a tokenized match, meaning that your emoji will be matched against the tokenized text of the Post body. Note that if an emoji has a variant, you must wrap it in double quotes to add to a query. Example: (😃 OR 😡) 😬 |
"exact phrase match" | Standalone | Matches the exact phrase within the body of a Post. Example: ("X API" OR #v2) -"recent search" |
# | Standalone | Matches any Post containing a recognized hashtag, if the hashtag is a recognized entity in a Post. This operator performs an exact match, NOT a tokenized match, meaning the rule #thanku will match posts with the exact hashtag #thanku, but not those with the hashtag #thankunext.Example: #thankunext #fanart OR @arianagrande |
@ | Standalone | Matches any Post that mentions the given username, if the username is a recognized entity (including the @ character). Example: (@XDevelopers OR @API) -@X |
$ | Standalone | Matches any Post that contains the specified ‘cashtag’ (where the leading character of the token is the $ character). Note that the cashtag operator relies on X’s ‘symbols’ entity extraction to match cashtags, rather than trying to extract the cashtag from the body itself. Example: $twtr OR @XDevelopers -$fb |
from: | Standalone | Matches any Post from a specific user. The value can be either the username (excluding the @ character) or the user’s numeric user ID. You can only pass a single username/ID per from: operator.Example: from:XDevelopers OR from:API -from:X |
to: | Standalone | Matches any Post that is in reply to a particular user. The value can be either the username (excluding the @ character) or the user’s numeric user ID. You can only pass a single username/ID per to: operator.Example: to:XDevelopers OR to:API -to:X |
url: | Standalone | Performs a tokenized match on any validly-formatted URL of a Post. This operator matches on the contents of both the url or expanded_url fields. For example, a Post containing “You should check out X Developer Labs: https://t.co/c0A36SWil4” (with the short URL redirecting to https://developer.twitter.com) will match both the following rules:from:XDevelopers url:"https://developer.twitter.com" (because it will match the contents of entities.urls.expanded_url )from:XDevelopers url:"https://t.co" (because it will match the contents of entities.urls.url )Tokens and phrases containing punctuation or special characters should be double-quoted (for example, url:"/developer" ). Similarly, to match on a specific protocol, enclose in double-quotes (for example, url:"https://developer.twitter.com" ). |
retweets_of: | Standalone | Matches Posts that are Retweets of the specified user. The value can be either the username (excluding the @ character) or the user’s numeric user ID. You can only pass a single username/ID per retweets_of: operator.Example: retweets_of:twitterdev OR retweets_of:twitterapi |
in_reply_to_tweet_id: | Standalone | Available alias: in_reply_to_status_id: Matches on replies to the specified Post. Example: in_reply_to_tweet_id:1539382664746020864 |
retweets_of_tweet_id: | Standalone | Available alias: retweets_of_status_id: Matches on explicit (or native) Retweets of the specified Post. Note that the Post ID used should be the ID of an original Post and not a Retweet. Example: retweets_of_tweet_id:1539382664746020864 |
quotes_of_tweet_id: | Standalone | Available alias: quotes_of_status_id: Matches on Quote Tweets of the specified Post. Note that the Post ID used should be the ID of an original Post and not a Quote Tweet. Example: quotes_of_tweet_id:1539382664746020864 |
context: | Standalone | Matches Posts with a specific domain id/entity id pair. To learn more about this operator, please visit our page on annotations. You can only pass a single domain/entity per context: operator.context:domain_id.entity_id However, you can combine multiple domain/entities using the OR operator: (context:47.1139229372198469633 OR context:11.1088514520308342784) Examples: context:10.799022225751871488 (domain_id.entity_id returns Posts matching that specific domain-entity pair) |
entity: | Standalone | Matches Posts with a specific entity string value. To learn more about this operator, please visit our page on annotations. Please note that this is only available with recent search. You can only pass a single entity: operator.entity:"string declaration of entity/place" Examples: entity:"Michael Jordan" OR entity:"Barcelona" |
conversation_id: | Standalone | Matches Posts that share a common conversation ID. A conversation ID is set to the Post ID of a Post that started a conversation. As Replies to a Post are posted, even Replies to Replies, the conversation_id is added to its JSON payload.You can only pass a single conversation ID per conversation_id: operator.Example: conversation_id:1334987486343299072 (from:XDevelopers OR from:api) |
list: | Standalone | NEW Matches Posts posted by users who are members of a specified list. For example, if @XDevelopers and @api were members of List 123, and you included list:123 in your query, your response will only contain Posts that have been published by those accounts. You can find List IDs by using the List lookup endpoint.Please note that you can only use a single list: operator per query, and you can only specify a single List per list: operator.Example: list:123 |
place: | Standalone | Matches Posts tagged with the specified location or X place ID. Multi-word place names (“New York City”, “Palo Alto”) should be enclosed in quotes. You can only pass a single place per place: operator.Note: See the GET geo/search standard v1.1 endpoint for how to obtain X place IDs. Note: This operator will not match on Retweets, since Retweet’s places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet. Example: place:"new york city" OR place:seattle OR place:fd70c22040963ac7 |
place_country: | Standalone | Matches Posts where the country code associated with a tagged place/location matches the given ISO alpha-2 character code. You can find a list of valid ISO codes on Wikipedia. You can only pass a single ISO code per place_country: operator.Note: This operator will not match on Retweets, since Retweet’s places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet. Example: place_country:US OR place_country:MX OR place_country:CA |
point_radius: | Standalone | Matches against the place.geo.coordinates object of the Post when present, and in X, against a place geo polygon, where the Place polygon is fully contained within the defined region.point_radius:[longitude latitude radius] - Units of radius supported are miles (mi) and kilometers (km) - Radius must be less than 25mi - Longitude is in the range of ±180 - Latitude is in the range of ±90 - All coordinates are in decimal degrees - Rule arguments are contained within brackets, space delimited You can only pass a single geo polygon per point_radius: operator.Note: This operator will not match on Retweets, since Retweet’s places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet. Example: point_radius:[2.355128 48.861118 16km] OR point_radius:[-41.287336 174.761070 20mi] |
bounding_box: | Standalone | Available alias: geo_bounding_box: Matches against the place.geo.coordinates object of the Post when present, and in X, against a place geo polygon, where the place polygon is fully contained within the defined region. bounding_box:[west_long south_lat east_long north_lat] - west_long south_lat represent the southwest corner of the bounding box where west_long is the longitude of that point, and south_lat is the latitude.- east_long north_lat represent the northeast corner of the bounding box, where east_long is the longitude of that point, and north_lat is the latitude.- Width and height of the bounding box must be less than 25mi - Longitude is in the range of ±180 - Latitude is in the range of ±90 - All coordinates are in decimal degrees. - Rule arguments are contained within brackets, space delimited. You can only pass a single geo polygons per bounding_box: operator.Note: This operator will not match on Retweets, since Retweet’s places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet. Example: bounding_box:[-105.301758 39.964069 -105.178505 40.09455] |
is:retweet | Conjunction required | Matches on Retweets that match the rest of the specified rule. This operator looks only for true Retweets (for example, those generated using the Retweet button). Quote Tweets will not be matched by this operator. Example: data @XDevelopers -is:retweet |
is:reply | Conjunction required | Deliver only explicit replies that match a rule. Can also be negated to exclude replies that match a query from delivery. Note: This operator is also available with the filtered stream endpoint. When used with filtered stream, this operator matches on replies to an original Post, replies in quoted Tweets, and replies in Retweets. Example: from:XDevelopers is:reply |
is:quote | Conjunction required | Returns all Quote Tweets, also known as Posts with comments. Example: "sentiment analysis" is:quote |
is:verified | Conjunction required | Deliver only Posts whose authors are verified by X. Example: #nowplaying is:verified |
-is:nullcast | Conjunction required | Removes Posts created for promotion only on ads.twitter.com that have a "source":"Twitter for Advertisers (legacy)" or "source":"Twitter for Advertisers" .This operator must be negated. For more info on Nullcasted Posts, see our page on Post availability. Example: "mobile games" -is:nullcast |
has:hashtags | Conjunction required | Matches Posts that contain at least one hashtag. Example: from:XDevelopers -has:hashtags |
has:cashtags | Conjunction required | Matches Posts that contain a cashtag symbol (with a leading ‘tag).<br/><br/>Example: #stonks has:cashtags` |
has:links | Conjunction required | This operator matches Posts which contain links and media in the Post body. Example: from:XDevelopers announcement has:links |
has:mentions | Conjunction required | Matches Posts that mention another X user. Example: #nowplaying has:mentions |
has:media | Conjunction required | Available alias: has:media_link Matches Posts that contain a media object, such as a photo, GIF, or video, as determined by X. This will not match on media created with Periscope, or Posts with links to other media hosting sites. Example: (kittens OR puppies) has:media |
has:images | Conjunction required | Matches Posts that contain a recognized URL to an image. Example: #meme has:images |
has:video_link | Conjunction required | Available alias: has:videos Matches Posts that contain native X videos, uploaded directly to X. This will not match on videos created with Periscope, or Posts with links to other video hosting sites. Example: #icebucketchallenge has:video_link |
has:geo | Conjunction required | Matches Posts that have Post-specific geolocation data provided by the X user. This can be either a location in the form of a X place, with the corresponding display name, geo polygon, and other fields, or in rare cases, a geo lat-long coordinate. Note: Operators matching on place (Post geo) will only include matches from original Posts. Retweets do not contain any place data. Example: recommend #paris has:geo -bakery |
lang: | Conjunction required | Matches Posts that have been classified by X as being of a particular language (if, and only if, the Post has been classified). It is important to note that each Post is currently only classified as being of one language, so AND’ing together multiple languages will yield no results. You can only pass a single BCP 47 language identifier per lang: operator.Note: if no language classification can be made the provided result is ‘und’ (for undefined). Example: recommend #paris lang:en The list below represents the currently supported languages and their corresponding BCP 47 language identifier: Amharic: am | German: de | Malayalam: ml | Slovak: sk Arabic: ar | Greek: el | Maldivian: dv | Slovenian: sl Armenian: hy | Gujarati: gu | Marathi: mr | Sorani Kurdish: ckb Basque: eu | Haitian Creole: ht | Nepali: ne | Spanish: es Bengali: bn | Hebrew: iw | Norwegian: no | Swedish: sv Bosnian: bs | Hindi: hi | Oriya: or | Tagalog: tl Bulgarian: bg | Latinized Hindi: hi-Latn | Panjabi: pa | Tamil: ta Burmese: my | Hungarian: hu | Pashto: ps | Telugu: te Croatian: hr | Icelandic: is | Persian: fa | Thai: th Catalan: ca | Indonesian: in | Polish: pl | Tibetan: bo Czech: cs | Italian: it | Portuguese: pt | Traditional Chinese: zh-TW Danish: da | Japanese: ja | Romanian: ro | Turkish: tr Dutch: nl | Kannada: kn | Russian: ru | Ukrainian: uk English: en | Khmer: km | Serbian: sr | Urdu: ur Estonian: et | Korean: ko | Simplified Chinese: zh-CN | Uyghur: ug Finnish: fi | Lao: lo | Sindhi: sd | Vietnamese: vi French: fr | Latvian: lv | Sinhala: si | Welsh: cy Georgian: ka | Lithuanian: lt |