Skip to content

operators.mdx

Latest commit

 

History

History
205 lines (150 loc) · 8.55 KB

operators.mdx

File metadata and controls

205 lines (150 loc) · 8.55 KB
title Search Operators
sidebarTitle Operators
description Complete list of operators for Search queries
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

Use engagement operators to filter Posts by minimum likes, replies, or reposts. These operators are available on the /2/tweets/search/recent and /2/tweets/search/all endpoints.

Operator Type Summary Example
min_likes: Conjunction required Matches Posts with at least the specified number of likes from:XDevelopers min_likes:100
min_replies: Conjunction required Matches Posts with at least the specified number of replies #announcement min_replies:50
min_reposts: Conjunction required Matches Posts with at least the specified number of reposts lang:en min_reposts:25
Combine engagement operators to surface high-signal Posts. For example, `from:XDevelopers min_likes:100 min_reposts:25` returns Posts from `@XDevelopers` with at least 100 likes and 25 reposts.

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