Search Tweets: recent search

Integrate contents

Building queries for the recent search endpoint

Operator syntax

With the recent search endpoints, 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, a boolean syntax is used to group multiple operators. Standalone operators are supported, but are generally not recommended due to the massive volume of matching Tweets. Here are the building blocks of the query syntax:

  • Successive operators with a space between them will result in AND logic, meaning that Tweets will match only if both conditions are met. For example, snow day #NoSchool will match Tweets containing the keywords snow and day and the hashtag #NoSchool.
  • Successive operators with OR between them will result in OR logic, meaning that Tweets will match if either condition is met. For example, specifying grumpy OR cat OR #meme will match any Tweets containing at least one of grumpy, cat, 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. Note that ANDs are applied first, then ORs are applied.  
  • 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
     

Twitter API v2 introduces new features that expand ways to match on Tweets of interest:

  • Twitter annotations: The recent search endpoint provides entity and context operators to match on contextual information about the Tweet itself.  
  • Conversation IDs: To help make it easier to thread together conversations on Twitter, a new 'conversation_id' operator is available.  When a Tweet is part of a conversation thread, the conversation ID for that Tweet will match the parent Tweet ID.
     

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 (for example, 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 (for example, url:"/developer"). Similarly, to match on a specific protocol, enclose in double-quotes (for example, 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:

NEW 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
Example:

  • context:10.799022225751871488
    (domain_id.entity_id returns Tweets matching that specific domain-entity pair)
entity:

NEW 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"
conversation_id: NEW Matches Tweets that share a common conversation ID. A conversation ID is set to the Tweet ID of a Tweet that started a conversation. As Replies to a Tweet are posted, even Replies to Replies, the conversation_id is added to its JSON payload.


Non-standalone 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). Quote Tweets will not be matched by this operator.
is:quote Returns all Quote Tweets, also known as Tweets with comments. 
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:

Amharic: am Greek: el Malayalam: ml Slovak: sk
Arabic: ar Gujarati: gu Maldivian: dv Slovenian: sl
Armenian: hy Haitian: ht Marathi: mr Sorani Kurdish: ckb
Bengali: bn Hebrew: iw Nepali: ne Spanish: es
Bulgarian: bg Hindi: hi Norwegian: no Swedish: sv
Burmese: my Hungarian: hu Oriya: or Tagalog: tl
Chinese: zh Icelandic: is Panjabi: pa Tamil: ta
Czech: cs Indonesian: in Pashto: ps Telugu: te
Danish: da Italian: it Persian: fa Thai: th
Dutch: nl Japanese: ja Polish: pl Tibetan: bo
English: en Kannada: kn Portuguese: pt Turkish: tr
Estonian: et Khmer: km Romanian: ro Ukrainian: uk
Finnish: fi Korean: ko Russian: ru Urdu: ur
French: fr Lao: lo Serbian: sr Uyghur: ug
Georgian: ka Latvian: lv Sindhi: sd Vietnamese: vi
Georgian: ka: Latvian: lv: Sindhi: sd: Welsh: cy:

Was this document helpful?

Thank you for the feedback. We’re really glad we could help!

Thank you for the feedback. How could we improve this document?

Thank you for the feedback. Your comments will help us improve our documents in the future.