Skip to content

operators.mdx

Latest commit

 

History

History
207 lines (151 loc) · 8.94 KB

operators.mdx

File metadata and controls

207 lines (151 loc) · 8.94 KB
title Search Operators
sidebarTitle Operators
description Reference for X API v2 Search operators — keywords, users, URLs, hashtags, engagement thresholds, language, geo, and Post type filters with examples.
keywords
search operators
query operators
search syntax
search filters
operators guide
query syntax

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

Engagement Operators

These precision operators filter Posts by minimum engagement counts. They are available on /2/tweets/search/recent, /2/tweets/search/all, /2/tweets/counts/recent, and /2/tweets/counts/all following the May 4, 2026 migration to the new X core platform search index.

Use them to narrow results to Posts that crossed an engagement threshold. For example, surface higher-signal content during a real-time event or filter long-tail noise from a broad topic query.

Operator Type Summary Example
min_likes: Conjunction required Matches Posts with at least the specified number of likes coffee min_likes:100
min_replies: Conjunction required Matches Posts with at least the specified number of replies from:XDevelopers min_replies:10
min_reposts: Conjunction required Matches Posts with at least the specified number of reposts #launch min_reposts:50
Engagement counts are evaluated at query time and may lag real-time activity by a short interval. These operators require at least one other standalone operator in the query (they are conjunction-required).

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

Learn query syntax and best practices Get started with Search Build and test queries interactively