X-Cavator

---

TL;DR

X-Cavator scrapes X.com at 600+ tweets per minute. It can optionally enrich each tweet with a decimal AI Sentiment Score from 0.00 to 1.00, where 0.50 means objective or neutral.

Quick start:

{
  "searchTerms": ["from:NASA"],
  "sort": "Latest",
  "maxItems": 1000
}

---

AI Sentiment Score

When Premium AI is enabled, each tweet gets a decimal sentimentScore.

Score	Meaning
1.00	Extremely positive
0.75	Positive
0.50	Neutral / objective
0.25	Negative
0.00	Extremely negative

Implementation notes:

• Shorter sentence-level analysis improves precision.
• Objective content stays at 0.50.
• Mixed tweets are aggregated from sentence scores.
• The prompt is kept compact to reduce token usage.

Example output:

{
  "type": "tweet",
  "id": "1728108619189874825",
  "text": "This product completely changed my workflow, absolutely love it!",
  "sentimentScore": 0.91,
  "likeCount": 8400,
  "retweetCount": 1230,
  "lang": "en",
  "author": {
    "userName": "techreviewer",
    "followers": 58200,
    "isBlueVerified": true
  }
}

---

Query Builder

You can pass full raw queries directly:

artemis (from:NASA OR from:SpaceX OR from:elonmusk)

Or build the same search with structured input:

{
  "searchTerms": ["artemis"],
  "tweetAuthors": ["NASA", "SpaceX", "elonmusk"],
  "sort": "Latest",
  "maxItems": 200
}

twitterHandles still scrapes profile timelines directly. tweetAuthors is for filtering search queries across multiple authors.

---

Input Parameters

Field	Type	Description	Default
searchTerms	array	Keywords, hashtags, or full advanced search queries	[]
twitterHandles	array	Profiles to scrape directly; if there are multiple handles, the quota is split evenly between them	[]
maxItems	number	Max tweets to extract across all queries and profiles; for multiple twitterHandles, this total is divided evenly	100
sort	string	Latest or Top	Latest
tweetLanguage	string	ISO 639-1 language code	all
startDate	string	Only get tweets after this date	null
endDate	string	Only get tweets before this date	null
onlyVerifiedUsers	boolean	Restrict to verified accounts	false
onlyTwitterBlue	boolean	Restrict to Twitter Blue accounts	false
onlyImage	boolean	Only tweets with images	false
onlyVideo	boolean	Only tweets with video	false
onlyQuote	boolean	Only quote tweets	false
tweetAuthor	string	Filter by one author handle; comma-separated handles are also accepted	null
tweetAuthors	array	Filter search results to multiple author handles joined with OR	[]
mentioning	string	Only tweets mentioning this handle	null
inReplyTo	string	Only replies to this handle	null
minimumFavorites	number	Min likes threshold	null
minimumRetweets	number	Min retweets threshold	null
minimumReplies	number	Min replies threshold	null
geotaggedNear	string	Location name	null
withinRadius	string	Radius for geotaggedNear	null
geocode	string	Strict geo via lat,long,radius	null
enablePremiumAi	boolean	Add decimal AI sentiment scoring per tweet	false

---

Usage Examples

Scrape a profile:

{ "twitterHandles": ["NASA"], "maxItems": 500 }

Scrape multiple profiles with an even split:

{ "twitterHandles": ["NASA", "elonmusk", "SpaceX"], "maxItems": 100 }

This runs as 34 + 33 + 33.

Search with date range:

{
  "searchTerms": ["artificial intelligence since:2024-01-01 until:2024-12-31"],
  "sort": "Top",
  "maxItems": 2000
}

Brand sentiment monitoring:

{
  "searchTerms": ["Tesla", "@Tesla"],
  "sort": "Latest",
  "maxItems": 5000,
  "enablePremiumAi": true
}

Search a topic across multiple authors:

{
  "searchTerms": ["artemis"],
  "tweetAuthors": ["NASA", "SpaceX", "elonmusk"],
  "sort": "Latest",
  "maxItems": 200
}

---

Output Schema

{
  "type": "tweet",
  "id": "1728108619189874825",
  "url": "https://x.com/elonmusk/status/1728108619189874825",
  "text": "More than 10 per human on average",
  "sentimentScore": 0.34,
  "likeCount": 104121,
  "retweetCount": 11311,
  "replyCount": 6526,
  "quoteCount": 2915,
  "bookmarkCount": 702,
  "lang": "en",
  "createdAt": "Fri Nov 24 17:49:36 +0000 2023",
  "isReply": false,
  "isRetweet": false,
  "isQuote": true,
  "author": {
    "userName": "elonmusk",
    "name": "Elon Musk",
    "followers": 172669889,
    "isVerified": true,
    "isBlueVerified": true,
    "profilePicture": "https://pbs.twimg.com/profile_images/..."
  }
}

sentimentScore is only present when Premium AI is enabled. 0.50 means objective or neutral.

---

Troubleshooting

Problem	Solution
Getting 0 results	Check if your query is too restrictive. Test it on twitter.com/search first.
Fewer results than expected	Try Top instead of Latest. Some periods have lower search coverage.
AI not running	Make sure enablePremiumAi is true.
Missing tweets	X may suppress or limit some content. Try a different date range or sort mode.

---

Ethical Use

X-Cavator extracts publicly available data only. Users are responsible for complying with applicable privacy and data protection rules when handling results.