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`

Engagement operators

Operator	Type	Summary	Example
`min_likes:`	Standalone	Matches Posts with at least the specified number of Likes	`#SuperBowl min_likes:100`
`min_replies:`	Standalone	Matches Posts with at least the specified number of replies	`from:XDevelopers min_replies:10`
`min_reposts:`	Standalone	Matches Posts with at least the specified number of Reposts	`"breaking news" min_reposts:50`

Each operator takes a non-negative integer value and is available with both recent search and full-archive search.

The equivalent operators on X web search are named min_faves: and min_retweets:. Those names are not valid in the X API and will be rejected with a 400 error. Use min_likes: and min_reposts: instead.

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

Posts

Articles

Users

Direct Messages

Likes

Lists

Spaces

Communities

Community Notes

Trends

News

Media

X Activity

Usage

Stream Connections

Compliance

Webhooks

Search Operators

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

Engagement operators

Language operator

Logical operators

Supported languages

Query limitations

Next steps

Build a query

Search introduction

Query Builder Tool

​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

​Engagement operators

​Language operator

​Logical operators

​Supported languages

​Query limitations

​Next steps

Build a query

Search introduction

Query Builder Tool

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

Engagement operators

Language operator

Logical operators

Supported languages

Query limitations

Next steps