Twitter Cards help you richly represent your content on Twitter. Now use analytics to measure their effectiveness. Become an advertiser. Compliment your ad campaigns with more information about your Tweets, followers, and Twitter Cards. Search hashtags and trending topics to stay updated on your friends & other Twitter followers. Follow the tweets of your favorite influencers, alongside hundreds of interesting Twitter users, and read their content at a glance. Share your opinion. Engage your social network with noteworthy links, photos and videos. DM your friends or reply in a.
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 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.
- 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:
Twitter Search Operators
- 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
Twitter Sign In
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 Appcleaner mac catalina. | 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:
Tokens and phrases containing punctuation or special characters should be double-quoted (e.g. |
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 Example:
|
| 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 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:
|
Additional resources
Twitter Search Api
- 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.
Search Twitter Home
Response fields
Search Twitter Profiles
| Name | Type | Description |
|---|---|---|
idDefault | string | Unique identifier of this Tweet. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers. |
textDefault | string | The content of the Tweet. To return this field, add tweet.fields=text in the request's query parameter. |
created_at | date (ISO 8601) | Creation time of the Tweet. To return this field, add tweet.fields=created_at in the request's query parameter. |
author_id | string | Unique identifier of this user. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers. You can obtain the expanded object in includes.users by adding expansions=author_id in the request's query parameter. |
conversation_id | string | The Tweet ID of the original Tweet of the conversation (which includes direct replies, replies of replies). To return this field, add tweet.fields=conversation_id in the request's query parameter. |
in_reply_to_user_id | string | If this Tweet is a Reply, indicates the user ID of the parent Tweet's author. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers. You can obtain the expanded object in includes.users by adding expansions=in_reply_to_user_id in the request's query parameter. |
referenced_tweets | array | A list of Tweets this Tweet refers to. For example, if the parent Tweet is a Retweet, a Retweet with comment (also known as Quoted Tweet) or a Reply, it will include the related Tweet referenced to by its parent. To return this field, add tweet.fields=referenced_tweets in the request's query parameter. |
referenced_tweets.type | enum (retweeted, quoted, replied_to) | Indicates the type of relationship between this Tweet and the Tweet returned in the response: retweeted (this Tweet is a Retweet), quoted (a Retweet with comment, also known as Quoted Tweet), or replied_to (this Tweet is a reply). |
referenced_tweets.id | string | The unique identifier of the referenced Tweet. You can obtain the expanded object in includes.tweets by adding expansions=referenced_tweets.id in the request's query parameter. |
attachments | object | Specifies the type of attachments (if any) present in this Tweet. To return this field, add tweet.fields=attachments in the request's query parameter. |
attachments.media_keys | array | List of unique identifiers of media attached to this Tweet. These identifiers use the same media key format as those returned by the Media Library. You can obtain the expanded object in includes.media by adding expansions=attachments.media_keys in the request's query parameter. |
attachments.poll_ids | array | List of unique identifiers of polls present in the Tweets returned. These are returned as a string in order to avoid complications with languages and tools that cannot handle large integers. You can obtain the expanded object in includes.polls by adding expansions=attachments.polls_ids in the request's query parameter. |
geo | object | Contains details about the location tagged by the user in this Tweet, if they specified one. To return this field, add tweet.fields=geo in the request's query parameter. |
geo.coordinates | object | Contains details about the coordinates of the location tagged by the user in this Tweet, if they specified one. To return this field, add tweet.fields=geo.coordinates in the request's query parameter. |
geo.coordinates.type | string | Describes the type of coordinate. The only value supported at present is Point. |
geo.coordinates.coordinates | array | A pair of decimal values representing the precise location of the user (latitude, longitude). This value be null unless the user explicitly shared their precise location. |
geo.place_id | string | The unique identifier of the place, if this is a point of interest tagged in the Tweet. You can obtain the expanded object in includes.places by adding expansions=geo.place_id in the request's query parameter. |
context_annotations | array | Contains context annotations for the Tweet. To return this field, add tweet.fields=context_annotations in the request's query parameter. |
context_annotations.domain | object | Contains elements which identify detailed information regarding the domain classification based on Tweet text. |
context_annotations.domain.id | string | Contains the numeric value of the domain. |
context_annotations.domain.name | string | Domain name based on the Tweet text. |
context_annotations.domain.description | string | Long form description of domain classification. |
context_annotations.entity | object | Contains elements which identify detailed information regarding the domain classification bases on Tweet text. |
context_annotations.entity.id | string | Unique value which correlates to an explicitly mentioned Person, Place, Product or Organization |
context_annotations.entity.name | string | Name or reference of entity referenced in the Tweet. |
context_annotations.entity.description | string | Additional information regarding referenced entity. |
entities | object | Contains details about text that has a special meaning in a Tweet. To return this field, add tweet.fields=entities in the request's query parameter. |
entities.annotations | array | Contains details about annotations relative to the text within a Tweet. |
entities.annotations.start | integer | The start position (zero-based) of the text used to annotate the Tweet. |
entities.annotations.end | integer | The end position (zero based) of the text used to annotate the Tweet. |
entities.annotations.probability | number | The confidence score for the annotation as it correlates to the Tweet text. |
entities.annotations.type | string | The description of the type of entity identified when the Tweet text was interpreted. |
entities.annotations.normalized_text | string | The text used to determine the annotation type. |
entities.urls | array | Contains details about text recognized as a URL. |
entities.urls.start | integer | The start position (zero-based) of the recognized URL within the Tweet. |
entities.urls.end | integer | The end position (zero-based) of the recognized URL within the Tweet. |
entities.urls.url | string | The URL in the format tweeted by the user. |
entities.urls.expanded_url | string | The fully resolved URL. |
entities.urls.display_url | string | The URL as displayed in the Twitter client. |
entities.urls.unwound_url | string | The full destination URL. |
entities.hashtags | array | Contains details about text recognized as a Hashtag. |
entities.hashtags.start | integer | The start position (zero-based) of the recognized Hashtag within the Tweet. |
entities.hashtags.end | integer | The end position (zero-based) of the recognized Hashtag within the Tweet. |
entities.hashtags.tag | string | The text of the Hashtag. |
entities.mentions | array | Contains details about text recognized as a user mention. |
entities.mentions.start | integer | The start position (zero-based) of the recognized user mention within the Tweet. |
entities.mentions.end | integer | The end position (zero-based) of the recognized user mention within the Tweet. |
entities.mentions.username | string | The part of text recognized as a user mention. You can obtain the expanded object in includes.users by adding expansions=entities.mentions.username in the request's query parameter. |
entities.cashtags | array | Contains details about text recognized as a Cashtag. |
entities.cashtags.start | integer | The start position (zero-based) of the recognized Cashtag within the Tweet. |
entities.cashtags.end | integer | The end position (zero-based) of the recognized Cashtag within the Tweet. |
entities.cashtags.tag | string | The text of the Cashtag. |
withheld | object | Contains withholding details for withheld content. To return this field, add tweet.fields=withheld in the request's query parameter. |
withheld.copyright | boolean | Indicates if the content is being withheld for on the basis of copyright infringement. |
withheld.country_codes | array | Provides a list of countries where this content is not available. |
withheld.scope | enum (tweet, user) | Indicates whether the content being withheld is a Tweet or a user. |
public_metrics | object | Engagement metrics for the Tweet at the time of the request. To return this field, add tweet.fields=public_metrics in the request's query parameter. |
public_metrics.retweet_count | integer | Number of times this Tweet has been Retweeted. |
public_metrics.reply_count | integer | Number of Replies of this Tweet. |
public_metrics.like_count | integer | Number of Likes of this Tweet. |
public_metrics.quote_count | integer | Number of times this Tweet has been Retweeted with a comment (also known as Quote). |
non_public_metrics | object | Non-public engagement metrics for the Tweet at the time of the request. This is a private metric, and requires the use of OAuth 1.0a User Context authentication. To return this field, add tweet.fields=non_public_metrics in the request's query parameter. |
non_public_metrics.impression_count | integer | Number of times the Tweet has been viewed. This is a private metric, and requires the use of OAuth 1.0a User Context authentication. |
non_public_metrics.url_link_clicks | integer | Number of times a user clicks on a URL link or URL preview card in a Tweet. This is a private metric, and requires the use of OAuth 1.0a User Context authentication. |
non_public_metrics.user_profile_clicks | integer | Number of times a user clicks the following portions of a Tweet - display name, user name, profile picture. This is a private metric, and requires the use of OAuth 1.0a User Context authentication. |
organic_metrics | object | Organic engagement metrics for the Tweet at the time of the request. Requires user context authentication. |
organic_metrics.impression_count | integer | Number of times the Tweet has been viewed organically. This is a private metric, and requires the use of OAuth 1.0a User Context authentication. |
organic_metrics.url_link_clicks | integer | Number of times a user clicks on a URL link or URL preview card in a Tweet organically. This is a private metric, and requires the use of OAuth 1.0a User Context authentication. |
organic_metrics.user_profile_clicks | integer | Number of times a user clicks the following portions of a Tweet organically - display name, user name, profile picture. This is a private metric, and requires the use of OAuth 1.0a User Context authentication. |
organic_metrics.retweet_count | integer | Number of times the Tweet has been Retweeted organically. |
organic_metrics.reply_count | integer | Number of replies the Tweet has received organically. |
organic_metrics.like_count | integer | Number of likes the Tweet has received organically. |
promoted_metrics | object | Engagement metrics for the Tweet at the time of the request in a promoted context. Requires user context authentication. |
promoted_metrics.impression_count | integer | Number of times the Tweet has been viewed when that Tweet is being promoted. This is a private metric, and requires the use of OAuth 1.0a User Context authentication. |
promoted_metrics.url_link_clicks | integer | Number of times a user clicks on a URL link or URL preview card in a Tweet when it is being promoted. This is a private metric, and requires the use of OAuth 1.0a User Context authentication. |
promoted_metrics.user_profile_clicks | integer | Number of times a user clicks the following portions of a Tweet when it is being promoted - display name, user name, profile picture. This is a private metric, and requires the use of OAuth 1.0a User Context authentication. |
promoted_metrics.retweet_count | integer | Number of times this Tweet has been Retweeted when that Tweet is being promoted. |
promoted_metrics.reply_count | integer | Number of Replies to this Tweet when that Tweet is being promoted. |
promoted_metrics.like_count | integer | Number of Likes of this Tweet when that Tweet is being promoted. |
possibly_sensitive | boolean | Indicates if this Tweet contains URLs marked as sensitive, for example content suitable for mature audiences. To return this field, add tweet.fields=possibly_sensitive in the request's query parameter. |
lang | string | Language of the Tweet, if detected by Twitter. Returned as a BCP47 language tag. To return this field, add tweet.fields=lang in the request's query parameter. |
reply_settings | string | Shows who can reply to this Tweet. Fields returned are everyone, mentionedUsers, and following.To return this field, add tweet.fields=reply_settings in the request's query parameter. |
source | string | The name of the app the user Tweeted from. To return this field, add tweet.fields=source in the request's query parameter. |
includes | object | If you include an expansion parameter, the referenced objects will be returned if available. |
includes.tweets | array | When including the expansions=referenced_tweets.id parameter, this includes a list of referenced Retweets, Quoted Tweets, or replies in the form of Tweet objects with their default fields and any additional fields requested using the tweet.fields parameter, assuming there is a referenced Tweet present in the returned Tweet(s). |
includes.users | array | When including the expansions=author_id parameter, this includes a list of referenced Tweet authors in the form of user objects with their default fields and any additional fields requested using the user.fields parameter. |
includes.places | array | When including the expansions=geo.place_id parameter, this includes a list of referenced places in Tweets in the form of place objects with their default fields and any additional fields requested using the place.fields parameter, assuming there is a place present in the returned Tweet(s). |
includes.media | array | When including the expansions=attachments.media_keys parameter, this includes a list of images, videos, and GIFs included in Tweets in the form of media objects with their default fields and any additional fields requested using the media.fields parameter, assuming there is a media attachment present in the returned Tweet(s). |
includes.polls | string | When including the expansions=attachments.poll_ids parameter, this includes a list of polls that are attached to Tweets in the form of poll objects with their default fields and any additional fields requested using the poll.fields parameter, assuming there is a poll present in the returned Tweet(s). |
errors | object | Contains details about errors that affected any of the requested Tweets. See Status codes and error messages for more details. |