Search Operators

This page provides a complete list of operators available when building a query for the Search API endpoints.

Overview

Operators are used to match on specific Post attributes. There are two types:

Standalone operators — Can be used alone or with any other operators
Conjunction-required operators — Must be used with at least one standalone operator

Keyword and phrase operators

Operator	Type	Summary	Example
`keyword`	Standalone	Matches a keyword within the Post body (tokenized match)	`pepsi OR cola OR "coca cola"`
`emoji`	Standalone	Matches an emoji within the Post body	`(😃 OR 😡) 😬`
`"exact phrase"`	Standalone	Matches the exact phrase within the Post body	`("X API" OR #v2) -"recent search"`

Entity operators

Operator	Type	Summary	Example
`#`	Standalone	Matches Posts containing a hashtag (exact match)	`#thankunext #fanart`
`@`	Standalone	Matches Posts mentioning a username	`(@XDevelopers OR @API) -@X`
`$`	Standalone	Matches Posts containing a cashtag	`$twtr OR @XDevelopers -$fb`

User operators

Operator	Type	Summary	Example
`from:`	Standalone	Matches Posts from a specific user	`from:XDevelopers OR from:API`
`to:`	Standalone	Matches Posts in reply to a specific user	`to:XDevelopers OR to:API`
`retweets_of:`	Standalone	Matches Retweets of a specific user	`retweets_of:twitterdev`

URL operators

Operator	Type	Summary	Example
`url:`	Standalone	Tokenized match on URL (matches `url` or `expanded_url` fields)	`url:"https://developer.twitter.com"`

Context and entity operators

Operator	Type	Summary	Example
`context:`	Standalone	Matches Posts with a specific domain/entity pair	`context:10.799022225751871488`
`entity:`	Standalone	Matches Posts with a specific entity string value (recent search only)	`entity:"Michael Jordan"`
`conversation_id:`	Standalone	Matches Posts in a conversation thread	`conversation_id:1334987486343299072`

List operator

Operator	Type	Summary	Example
`list:`	Standalone	Matches Posts from members of a specific List	`list:123`

Post reference operators

Operator	Type	Summary	Example
`in_reply_to_tweet_id:`	Standalone	Matches replies to a specific Post	`in_reply_to_tweet_id:1539382664746020864`
`retweets_of_tweet_id:`	Standalone	Matches Retweets of a specific Post	`retweets_of_tweet_id:1539382664746020864`
`quotes_of_tweet_id:`	Standalone	Matches Quote Tweets of a specific Post	`quotes_of_tweet_id:1539382664746020864`

Location operators

Operator	Type	Summary	Example
`place:`	Standalone	Matches Posts tagged with a location	`place:"new york city" OR place:seattle`
`place_country:`	Standalone	Matches Posts with a country code	`place_country:US OR place_country:MX`
`point_radius:`	Standalone	Matches Posts within a radius of a point	`point_radius:[2.355128 48.861118 16km]`
`bounding_box:`	Standalone	Matches Posts within a bounding box	`bounding_box:[-105.301758 39.964069 -105.178505 40.09455]`

Post type operators

Operator	Type	Summary	Example
`is:retweet`	Conjunction required	Matches Retweets	`data @XDevelopers -is:retweet`
`is:reply`	Conjunction required	Matches replies	`from:XDevelopers is:reply`
`is:quote`	Conjunction required	Matches Quote Tweets	`"sentiment analysis" is:quote`
`is:verified`	Conjunction required	Matches Posts from verified authors	`#nowplaying is:verified`
`-is:nullcast`	Conjunction required	Excludes promotional Posts (must be negated)	`"mobile games" -is:nullcast`

Content type operators

Operator	Type	Summary	Example
`has:hashtags`	Conjunction required	Matches Posts with hashtags	`from:XDevelopers -has:hashtags`
`has:cashtags`	Conjunction required	Matches Posts with cashtags	`#stonks has:cashtags`
`has:links`	Conjunction required	Matches Posts with links	`from:XDevelopers has:links`
`has:mentions`	Conjunction required	Matches Posts with mentions	`#nowplaying has:mentions`
`has:media`	Conjunction required	Matches Posts with media (photo, GIF, video)	`(kittens OR puppies) has:media`
`has:images`	Conjunction required	Matches Posts with images	`#meme has:images`
`has:video_link`	Conjunction required	Matches Posts with native X videos	`#icebucketchallenge has:video_link`
`has:geo`	Conjunction required	Matches Posts with geolocation data	`recommend #paris has:geo`

Language operator

Operator	Type	Summary	Example
`lang:`	Conjunction required	Matches Posts classified as a specific language	`recommend #paris lang:en`

Logical operators

Operator	Summary	Example
`OR`	Logical OR between expressions	`cat OR dog`
Space (AND)	Logical AND between expressions	`cat dog` (both required)
`()`	Grouping for complex expressions	`(cat OR dog) -is:retweet`
`-`	Negation/exclusion	`cat -grumpy`

Supported languages

The lang: operator supports these BCP 47 language codes:

Language	Code	Language	Code	Language	Code
Amharic	`am`	Greek	`el`	Portuguese	`pt`
Arabic	`ar`	Gujarati	`gu`	Romanian	`ro`
Armenian	`hy`	Hebrew	`iw`	Russian	`ru`
Basque	`eu`	Hindi	`hi`	Serbian	`sr`
Bengali	`bn`	Hungarian	`hu`	Simplified Chinese	`zh-CN`
Bulgarian	`bg`	Indonesian	`in`	Slovak	`sk`
Catalan	`ca`	Italian	`it`	Slovenian	`sl`
Croatian	`hr`	Japanese	`ja`	Spanish	`es`
Czech	`cs`	Kannada	`kn`	Swedish	`sv`
Danish	`da`	Korean	`ko`	Tamil	`ta`
Dutch	`nl`	Latvian	`lv`	Telugu	`te`
English	`en`	Lithuanian	`lt`	Thai	`th`
Estonian	`et`	Malayalam	`ml`	Traditional Chinese	`zh-TW`
Finnish	`fi`	Marathi	`mr`	Turkish	`tr`
French	`fr`	Norwegian	`no`	Ukrainian	`uk`
German	`de`	Persian	`fa`	Urdu	`ur`
Georgian	`ka`	Polish	`pl`	Vietnamese	`vi`

Query limitations

Access level	Recent search	Full-archive search
Self-serve	512 characters	1,024 characters
Enterprise	4,096 characters	4,096 characters

Next steps

Build a query

Learn query syntax and best practices

Search introduction

Get started with Search

Query Builder Tool

Build and test queries interactively

​Overview

​Keyword and phrase operators

​Entity operators

​User operators

​URL operators

​Context and entity operators

​List operator

​Post reference operators

​Location operators

​Post type operators

​Content type operators

​Language operator

​Logical operators

​Supported languages

​Query limitations

​Next steps