🚀 X (Twitter) Advanced Search Actor

The most powerful and flexible Twitter search solution for Apify - Unlock the full potential of X (formerly Twitter) data collection with our sophisticated search capabilities and advanced filtering system.

LICENSE

---

🌟 What Makes Us Superior?

Our X (Twitter) Advanced Search Actor represents the pinnacle of social media data extraction technology. Unlike basic scrapers that offer limited functionality, we provide:

• ✅ No Twitter API key required - Scrapes directly from Twitter via Nitter instances
• 🎯 60+ advanced filters across 8 comprehensive categories
• 🔍 Dual search modes - Simple query or structured advanced filters
• ⚡ Enterprise-grade reliability - Built for scalability and performance
• 📊 Rich metadata extraction - Complete tweet data with engagement stats
• 🔄 Smart pagination - Automatic handling of large datasets
• 🛡️ Robust error handling - Comprehensive retry logic and validation

---

🎯 Dual Search Modes for Maximum Flexibility

Simple Query Mode

Use traditional X search syntax for quick, straightforward searches:

{
  "query": "artificial intelligence OR AI from:elonmusk since:2024-01-01",
  "queryType": "Latest",
  "numberOfTweets": 100
}

Advanced Filter Mode

Leverage our revolutionary structured filter system for precise, complex data collection:

{
  "query": "AI",
  "queryType": "Top",
  "numberOfTweets": 500,
  "engagementLevel": "high",
  "mediaTypes": ["image", "video"],
  "contentLanguage": "en",
  "timeSince": "2024-01-01",
  "timeUntil": "2024-12-31",
  "usersVerifiedOnly": true,
  "contentKeywords": ["machine learning", "neural networks"],
  "contentHashtags": ["AI", "MachineLearning"],
  "engagementMinLikes": 100,
  "engagementMinRetweets": 10
}

💡 Tip: You can use either query OR advanced filters — at least one must be provided.

---

🔍 Industry-Leading Filter System

Our proprietary filtering technology offers 8 comprehensive filter categories with 60+ individual filter options:

1. Content Filters

• Keywords: Search for specific words or phrases
• Exact Phrases: Match complete quoted phrases
• Hashtags: Include/exclude specific hashtags
• Cashtags: Stock symbols (e.g., $TSLA, $AAPL)
• Language: Filter by tweet language (26+ languages supported)
• Emoticons: Positive (:) :-) :P :D) or negative (:( :-() sentiment
• Question Marks: Find question-based tweets
• Exclude Keywords/Hashtags: Remove unwanted content

2. User Filters

• From Users: Tweets from specific accounts (from:username)
• To Users: Replies to specific users (to:username)
• Mention Users: Tweets mentioning users (@username)
• Exclude Users: Filter out specific accounts
• List Members: Tweets from Twitter list members (list:list_id)
• Verified Only: Blue checkmark or verified users
• Blue Verified Only: Twitter Blue subscribers

3. Geographic Filters

• Near Location: Geotagged tweets near a city (near:"San Francisco")
• Within Radius: Within specific distance (within:25km)
• Geocode: Precise coordinates (geocode:37.7764685,-122.4172004,10km)
• Place ID: Twitter Place Object ID (place:96683cc9126741d1)

4. Time Filters

• Date Range: Start and end dates (since:2024-01-01, until:2024-12-31)
• Relative Time: Last X time (within_time:24h, within_time:7d)
• Unix Timestamps: Precise time control
• Tweet ID Boundaries: Snowflake ID-based pagination (since_id:, max_id:)

5. Engagement Filters

• Minimum/Maximum Likes: Filter by like count (min_faves:100)
• Minimum/Maximum Retweets: Filter by retweet count (min_retweets:10)
• Minimum/Maximum Replies: Filter by reply count (min_replies:5)
• Smart Presets: low, medium, high, viral engagement levels
• Has Engagement: Must have any engagement

6. Media Filters

• Media Types: Images, videos, GIFs, native video, Spaces
• Has Links: Tweets containing URLs
• Has Mentions: Tweets with @mentions
• Has Hashtags: Tweets with hashtags
• News Only: Tweets linking to news sites
• Safe Content: Exclude potentially sensitive content

7. Tweet Type Filters

• Include Types: Original tweets, retweets, replies, quotes
• Exclude Types: Filter out specific tweet types
• Conversation ID: Thread/conversation tweets (conversation_id:)
• Quoted Tweet ID: Quotes of specific tweets (quoted_tweet_id:)
• Quoted User ID: Quotes from specific users (quoted_user_id:)
• Poll Types: Tweets containing polls (2-4 choice polls)

8. App/Source Filters

• Sources: Tweets from specific apps (source:twitter_for_iphone)
• Exclude Sources: Filter out specific apps
• Card Domain: Twitter Card domain (card_domain:youtube.com)
• Card URL: Twitter Card URL (card_url:)
• Card Name: Card types (audio, animated_gif, player, app, summary, etc.)

---

📦 Rich Data Extraction

Each result includes comprehensive metadata:

{
  "searchType": "post",
  "type": "tweet",
  "query": "python programming",
  "data": {
    "tweet_url": "https://x.com/username/status/123456789",
    "tweet_id": "123456789",
    "author": {
      "fullname": "Python Dev",
      "username": "pythondev",
      "verified": true,
      "profile_picture": "https://pbs.twimg.com/...",
      "bio": "Python enthusiast",
      "followers": 15000,
      "following": 500
    },
    "text": "Just released a new Python library! #python #coding",
    "timestamp": "2024-01-15T10:30:00Z",
    "stats": {
      "likes": 150,
      "retweets": 45,
      "comments": 12,
      "quotes": 3
    },
    "media": [
      {
        "type": "image",
        "url": "https://pbs.twimg.com/media/..."
      }
    ],
    "urls": ["https://github.com/..."],
    "hashtags": ["python", "coding"],
    "mentions": ["@pythonorg"]
  }
}

---

🚀 Three Search Modes

1. Global Search (Post Search)

Search tweets across all of Twitter using keywords, hashtags, time, geo, media, and engagement filters.

{
  "query": "climate change",
  "queryType": "Latest",
  "numberOfTweets": 500,
  "timeSince": "2024-01-01",
  "contentLanguage": "en"
}

2. Profile Search

Scrape tweets from a specific user profile with date range, keywords, and engagement filters.

{
  "query": "AI",
  "username": "elonmusk",
  "numberOfTweets": 200,
  "timeSince": "2024-01-01"
}

3. User Search

Discover Twitter user profiles based on search queries.

{
  "query": "python developer",
  "searchType": "user"
}

---

📋 Complete Input Schema

Core Parameters

Parameter	Type	Description	Example
query	string	Base search query	"artificial intelligence"
queryType	enum	Latest or Top	"Latest"
numberOfTweets	integer	Number of tweets (20-10000)	100
maxPages	integer	Maximum pages to scrape	50

Engagement Filters

Parameter	Type	Description
engagementLevel	enum	Preset: none, low, medium, high, viral
engagementMinLikes	integer	Minimum likes
engagementMaxLikes	integer	Maximum likes
engagementMinRetweets	integer	Minimum retweets
engagementMaxRetweets	integer	Maximum retweets
engagementMinReplies	integer	Minimum replies
engagementMaxReplies	integer	Maximum replies
engagementHasEngagement	boolean	Must have any engagement

Content Filters

Parameter	Type	Description
contentKeywords	array	Keywords to search for
contentExactPhrases	array	Exact phrases (quoted)
contentHashtags	array	Hashtags to include
contentExcludeHashtags	array	Hashtags to exclude
contentCashtags	array	Stock symbols
contentExcludeKeywords	array	Keywords to exclude
contentLanguage	enum	Language code (en, es, fr, etc.)
contentEmoticons	enum	positive or negative
contentQuestionMarks	boolean	Include question marks

User Filters

Parameter	Type	Description
usersFromUsers	array	Tweets from specific users
usersToUsers	array	Replies to specific users
usersMentionUsers	array	Tweets mentioning users
usersExcludeFromUsers	array	Exclude tweets from users
usersListMembers	array	From list members
usersVerifiedOnly	boolean	Verified users only
usersBlueVerifiedOnly	boolean	Blue verified users only

Time Filters

Parameter	Type	Description
timeSince	string	Start date (YYYY-MM-DD)
timeUntil	string	End date (YYYY-MM-DD)
timeWithinTime	string	Relative time (24h, 7d, 30s)
timeSinceUnix	integer	Start Unix timestamp
timeUntilUnix	integer	End Unix timestamp
timeSinceId	string	Since tweet ID (Snowflake)
timeMaxId	string	Max tweet ID (Snowflake)

Geo Filters

Parameter	Type	Description
geoNear	string	Near location
geoWithinRadius	string	Within radius (25km, 15mi)
geoGeocode	string	Coordinates (lat,long,radius)
geoPlaceId	string	Twitter Place ID

Media Filters

Parameter	Type	Description
mediaTypes	array	image, video, media, native_video, spaces
mediaHasLinks	boolean	Must contain links
mediaHasMentions	boolean	Must contain mentions
mediaHasHashtags	boolean	Must contain hashtags
mediaNewsOnly	boolean	News links only
mediaSafeContentOnly	boolean	Safe content only

Tweet Type Filters

Parameter	Type	Description
tweetTypes	array	Include types (retweet, reply, quote)
tweetTypesExclude	array	Exclude types
tweetConversationId	string	Conversation/thread ID
tweetQuotedTweetId	string	Quoted tweet ID
tweetQuotedUserId	string	Quoted user ID
tweetPollTypes	array	Poll types

App/Source Filters

Parameter	Type	Description
appsSources	array	App sources
appsExcludeSources	array	Exclude sources
cardDomain	string	Card domain
cardUrl	string	Card URL
cardName	enum	Card name (audio, animated_gif, player, etc.)

Additional Parameters

Parameter	Type	Description
proxyUrl	string	Optional proxy URL
baseUrl	string	Nitter instance URL (default: https://nitter.net)

---

📖 Advanced Search Operators Reference

Our actor supports the complete range of X's advanced search operators. Here's your comprehensive reference:

Content Operators

Operator	Description	Example
"exact phrase"	Search for exact phrases	"machine learning"
keyword1 keyword2	Both keywords (implicit AND)	AI technology
keyword1 OR keyword2	Either keyword	AI OR artificial intelligence
+forced_term	Force inclusion (prevent spelling correction)	+radiooooo
-excluded_term	Exclude terms	AI -spam
#hashtag	Hashtag search	#AI
$cashtag	Stock symbol search	$TSLA
?	Questions only	What ?
:) or :(	Positive/negative emoticons	:) OR :(
url:domain.com	URL content search	url:github.com
lang:en	Language filter	lang:en

User Operators

Operator	Description	Example
from:username	Tweets from specific user	from:elonmusk
to:username	Replying to specific user	to:support
@username	Mentioning specific user	@company_handle
list:list_id	Tweets from list members	list:715919216927322112
filter:verified	Verified users only	filter:verified
filter:blue_verified	Blue checkmark users	filter:blue_verified

Geographic Operators

Operator	Description	Example
near:"city"	Geotagged in location	near:"San Francisco"
within:radius	Within radius of location	within:10km
geocode:lat,long,radius	Precise coordinates	geocode:37.7764685,-122.4172004,10km
place:place_id	Specific place ID	place:96683cc9126741d1

Time Operators

Operator	Description	Example
since:2024-01-01	From date (inclusive)	since:2024-01-01
until:2024-12-31	Before date (exclusive)	until:2024-12-31
since_time:timestamp	Unix timestamp from	since_time:1640995200
until_time:timestamp	Unix timestamp until	until_time:1672531199
since_id:tweet_id	After Snowflake ID	since_id:1138872932887924737
max_id:tweet_id	At or before Snowflake ID	max_id:1144730280353247233
within_time:2d	Relative time window	within_time:24h

Engagement Operators

Operator	Description	Example
min_retweets:5	Minimum retweets	min_retweets:100
min_faves:10	Minimum likes	min_faves:1000
min_replies:100	Minimum replies	min_replies:50
filter:has_engagement	Has any engagement	filter:has_engagement

Media Operators

Operator	Description	Example
filter:media	All media types	filter:media
filter:images	Images only	filter:images
filter:videos	Videos only	filter:videos
filter:links	Contains links	filter:links
filter:news	News content	filter:news

Tweet Type Operators

Operator	Description	Example
filter:retweets	Retweets and quotes	filter:retweets
filter:replies	Reply tweets	filter:replies
filter:quote	Quote tweets	filter:quote
conversation_id:id	Conversation thread	conversation_id:1140437409710116865
quoted_tweet_id:id	Quotes of specific tweet	quoted_tweet_id:1138631847783608321
quoted_user_id:id	Quotes from specific user	quoted_user_id:11348282

App/Source Operators

Operator	Description	Example
source:client_name	From specific app	source:twitter_for_iphone
card_domain:domain	Card domain	card_domain:youtube.com
card_url:url	Card URL	card_url:pscp.tv
card_name:name	Card name	card_name:player

📚 Complete Reference: For the full list of operators, see Twitter Advanced Search Operators Documentation

---

🎯 Pre-Built Filter Presets

Viral Content

{
  "engagementLevel": "viral",
  "engagementMinLikes": 1000,
  "engagementMinRetweets": 100
}

News Content

{
  "mediaNewsOnly": true,
  "mediaHasLinks": true,
  "contentLanguage": "en"
}

Verified Users Only

{
  "usersVerifiedOnly": true
}

Recent Tweets (24 hours)

{
  "timeWithinTime": "24h"
}

Local News

{
  "geoNear": "New York",
  "geoWithinRadius": "50km",
  "mediaNewsOnly": true
}

---

💡 Pro Tips for Maximum Results

Optimization Strategies

1. Start Specific: Begin with targeted filters and expand as needed
2. Combine Filters: Use multiple filter types for precise results
3. Test Iteratively: Experiment with different combinations
4. Monitor Performance: Track query performance and adjust accordingly

Advanced Techniques

• Use Engagement Presets: Leverage smart presets for common use cases
• Time-Based Filtering: Combine date ranges with engagement filters for trending content
• Geographic Targeting: Use location filters for local market research
• Content Analysis: Combine language and sentiment filters for brand monitoring

Best Practices

• ✅ Validate Inputs: Our actor validates all filter combinations automatically
• ✅ Handle Pagination: Use cursor-based pagination for large datasets
• ✅ Monitor Rate Limits: Be aware of limitations for high-volume operations
• ✅ Data Quality: Use exclusion filters to improve result relevance

---

🛠️ Development

Tech Stack

• Python 3.8+
• Apify SDK
• httpx (HTTP/2 client)
• BeautifulSoup4 (HTML parsing)
• Nitter (Twitter frontend)

Local Setup

# Clone the repository
git clone <repo>
cd source-code

# Install dependencies
pip install -r requirements.txt

# Run locally
apify run

Project Structure

.
├── .actor/
│   ├── actor.json          # Actor configuration
│   ├── input_schema.json   # Input schema definition
│   └── output_schema.json  # Output schema definition
├── src/
│   ├── main.py            # Main entry point
│   ├── search_post.py     # Global tweet search
│   ├── profile_search.py  # Profile-specific search
│   └── search_user.py     # User search
├── storage/               # Local storage (mirrors Cloud)
│   ├── datasets/         # Output items
│   └── key_value_stores/ # Files, config, INPUT
├── Dockerfile            # Container image definition
└── requirements.txt      # Python dependencies

---

📊 Output

Results are stored in the default Apify dataset with multiple built-in views:

• 📄 All Tweets - Complete tweet data
• 👤 Users - User profile information
• 🔥 High Engagement Tweets - Filtered by engagement
• 🖼 Tweets with Media - Media-rich tweets

Export Formats

• JSON - Structured data format
• CSV - Spreadsheet-compatible
• Excel - Microsoft Excel format
• XML - XML format

---

⭐ Use Cases

• Social Listening & Trend Analysis - Monitor brand mentions and industry trends
• Brand Monitoring - Track your brand across Twitter
• Crypto & Stock Sentiment Tracking - Analyze market sentiment
• Lead Generation - Find potential customers and partners
• Academic & Research Datasets - Collect data for research
• Media & Journalism Research - Investigate stories and sources
• Competitor Analysis - Monitor competitor activities
• Influencer Discovery - Find relevant influencers
• Crisis Management - Track negative mentions
• Content Research - Find trending topics and content ideas

---

🛡️ Legal and Ethical Considerations

Our actor operates within ethical boundaries and legal frameworks:

• ✅ Public Data Only: We only collect publicly available information
• ✅ No Private Data: We do not access private accounts or DMs
• ✅ GDPR Compliant: Respects privacy regulations and user consent
• ✅ Rate Limiting: Built-in safeguards prevent excessive usage
• ✅ Transparent Operations: Clear documentation of data collection

⚠️ Important: Always respect Twitter's Terms of Service and robots.txt. Use responsibly and ethically.

---

📞 Support and Documentation

• Comprehensive Examples: Extensive code samples and use cases
• Filter Documentation: Detailed explanations of all filter options
• API Reference: Complete technical documentation
• Community Support: Active community and expert assistance

---

📄 License

Licensed under Apache License 2.0 - Free to use, modify, and integrate in commercial projects.

---

🚀 Getting Started

1. Set up your Apify account - Create an account at apify.com
2. Choose your search method - Simple Query or Advanced Filters
3. Configure your parameters - Use our comprehensive filter system
4. Execute the actor - Run and collect your structured data
5. Analyze and integrate - Export in multiple formats

---

🔥 Ready to unlock the full potential of X (Twitter) data? Start with our advanced search capabilities and experience the difference that superior technology makes.

Transform your social media intelligence with the most powerful X (Twitter) search solution available.