Interested in exploring Labs?
The endpoints we release in Labs are previews of tools that may be released more broadly in the future, but will likely undergo changes before then. We encourage you to take that into consideration as you explore. Before getting started, please read more about Twitter Developer Labs.

Still using v1?
This page documents the current version of this endpoints, however you can still reference the previous version. You should also check out our version migration guide and review our changelog.

 

Building queries for the recent search endpoint

Operator syntax

With the Labs recent search endpoint, a single query (also referred to as a 'rule' or 'filter') is submitted with a GET request and matching Tweets are returned. Queries are made up of operators that are used to match on a variety of Tweet attributes.

To create a query, you can specify a single "standalone" operator, or combine multiple operators.

  • Operators specified together will be combined in a single AND clause. For example, snow day #NoSchool will match Tweets containing the keywords snow and day and the hashtag #NoSchool.
  • You can also match Tweets based on the presence of any of the operators by using the OR conjunction. For example, specifying grumpy OR cat OR #meme will match any Tweets containing at least one of grumpycat, or the hashtag #meme.
  • You can use parentheses to group operators together. For example, (grumpy cat) OR (#meme has:images) will return either Tweets containing the terms grumpy and cat, or Tweets with images containing the hashtag #meme.
  • Prepend a dash to a keyword (or any operator) to negate it (NOT). For example, cat #meme -grumpy will match Tweets containing the hashtag #meme and the term cat, but only if they do not contain the term grumpy. You can also negate operators grouped using parenthesis. One common query clause is -is:retweet, which will not match on Retweets, thus matching only on original Tweets. 
     

Please note the following important details about building queries:

  • Queries can be 512 characters long.
  • All operators can 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 -(grumpy OR cat OR meme), we suggest that you use -grumpy -cat -meme
     

To learn more about building queries for the recent search endpoint, please review our tutorial on translating plain language to queries.

 

Standalone operators

These operators can be used alone or together with any other operators (including those from the Entity operators list).

 Operator

Description

keyword

Matches a keyword within the body of a Tweet. This is a tokenized match, meaning that your keyword string will be matched against the tokenized text of the Tweet body. Tokenization splits words based on punctuation, symbols, and Unicode basic plane separator characters.

For example, a Tweet 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 rule. To match strings containing punctuation (e.g. coca-cola), symbol, or separator characters, you must wrap your keyword in double-quotes.

emoji

Matches an emoji within the body of a Tweet. Similar to a keyword, emojis are a tokenized match, meaning that your emoji will be matched against the tokenized text of the Tweet body.

Note that if an emoji has a variant, you must wrap it in double quotes to add to a rule.

"exact phrase match"

Matches the exact phrase within the body of a Tweet.

#

Matches any Tweet containing a recognized hashtag, if the hashtag is a recognized entity in a Tweet.

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.

@

Matches any Tweet that mentions the given username, if the username is a recognized entity (including  the @ character).

from:

Matches any Tweet from a specific user.

The value can be either the username (excluding the @ character) or the user’s numeric user ID.

to:

Matches any Tweet 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.

url:

Performs a tokenized match on any validly-formatted URL of a Tweet.

This operator can matches on the contents of both the url or expanded_url. For example, a Tweet containing "You should check out Twitter Developer Labs: https://t.co/c0A36SWil4" (with the short URL redirecting to https://developer.twitter.com) will match both the following rules:

  • from:TwitterDev url:"https://developer.twitter.com" (because it will match the contents of entities.urls.expanded_url)
  • from:TwitterDev 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 (e.g. url:"/developer"). Similarly, to match on a specific protocol, enclose in double-quotes (e.g. url:"https://developer.twitter.com").

retweets_of:

Matches Tweets that are Retweets of the specified user. The value can be either the username (excluding the @ character) or the user’s numeric user ID.

context:

Matches tweets with a specific domain id and/or domain id, enitity id pair where * represents a wildcard. To learn more about this operator, please visit our page on Annotations

context: domain_id.entity_id || *.entity_id || domain_id.*

Examples:

  • context:10.799022225751871488 (domain_id.entity_id returns Tweets matching that specific domain-entity pair)
  • context:47.* (domain_id.* returns Tweets matching that domain ID, with any domain-entity pair)
  • context:*.799022225751871488 (*.entity_id returns Tweets matching that entity ID, with any domain-entity pair)
entity:

Matches tweets with a specific entity string value. To learn more about this operator, please visit our page on Annotations.

entity:"string declaration of entity/place"

Examples:

  • entity:"Michael Jordan"
  • entity:"Barcelona" 

 

Entity operators

The following operators cannot be used as an independent clause in a query; they can only be used together with at least one operator from the Standalone operators list.

For example, the following query is not supported since it contains only Entity operators, would be far too general, and would likely match on an extreme volume of Tweets.

has:mentions (has:media OR has:links)

If we add in a standalone operator, such as the keyword 'snow', the following query is supported.

snow has:mentions (has:media OR has:links)

 

 Operator

Description

is:retweet 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). Tweets with comments (also known as Quoted Tweets) and modified Tweets will not be matched by this operator. This operator can be negated to match original Tweets only, e.g. -is:retweet.
is:verified Deliver only Tweets whose authors are verified by Twitter.
has:hashtag Matches Tweets that contain at least one hashtag.

has:links

This operator matches Tweets which contain links in the Tweet body.

has:mentions

Matches Tweets that mention another Twitter user.

has:media

Matches Tweets that contain a media URL recognized by Twitter.

has:images

Matches Tweets that contain a recognized URL to an image.

has:videos

Matches Tweets that contain native Twitter videos, uploaded directly to Twitter. This will not match on videos created with Periscope, or Tweets with links to other video hosting sites.

lang:

Matches Tweets that have been classified by Twitter as being of a particular language (if, and only if, the tweet has been classified). It is important to note that each Tweet is currently only classified as being of one language, so AND’ing together multiple languages will yield no results.

Note: if no language classification can be made the provided result is ‘und’ (for undefined).

The list below represents the currently supported languages and their corresponding BCP 47 language identifier:

am Amharic

hu Hungarian

pt Portuguese

ar Arabic

is Icelandic

ro Romanian

hy Armenian

in Indonesian

ru Russian

bn Bengali

it Italian

sr Serbian

bg Bulgarian

ja Japanese

sd Sindhi

my Burmese

kn Kannada

si Sinhala

zh Chinese

km Khmer

sk Slovak

cs Czech

ko Korean

sl Slovenian

da Danish

lo Lao

ckb Sorani Kurdish

nl Dutch

lv Latvian

es codeish

en English

lt Lithuanian

sv Swedish

et Estonian

ml Malayalam

tl Tagalog

fi Finnish

dv Maldivian

ta Tamil

fr French

mr Marathi

te Telugu

ka Georgian

ne Nepali

th Thai

de German

no Norwegian

bo Tibetan

el Greek

or Oriya

tr Turkish

gu Gujarati

pa Panjabi

uk Ukrainian

ht Haitian

ps Pashto

ur Urdu

iw Hebrew

fa Persian

ug Uyghur

hi Hindi

pl Polish

vi Vietnamese

cy Welsh

 


 

Additional resources

  • Learn more about the new Developer Labs on the "About Labs" page
  • Learn more about What’s new.
  • Give feedback on Twitter Developer Labs.
  • Tell us about your experience using the Twitter Developer Labs endpoints by filling out this survey.