X Research But Cheaper

X Research

General-purpose X/Twitter research agent powered by TwitterAPI.io. Search, filter, monitor — all from the terminal. No X Developer Portal account needed. For API details: read references/twitterapi-io.md.

Why TwitterAPI.io?

X API OfficialTwitterAPI.ioCost$100+/mo (Basic plan)~$0.15/1k tweets (pay-per-use)SetupDeveloper Portal applicationJust an API keyRate limit10 req/15min200 QPSArchive7 days (recent)Full archive

Setup

Get a TwitterAPI.io key from twitterapi.io Set the env var: export TWITTERAPI_KEY="your-key-here" Or add to your .env file. Node.js 18+ required (for native fetch). No npm install needed — zero dependencies.

CLI Tool

All commands run from the scripts directory: cd <skill-dir>/scripts

Search

npx tsx x-search.ts search "<query>" [options] Options: --sort likes|retweets|impressions|recent — sort order (default: likes) --since 1h|3h|12h|1d|7d — time filter --min-likes N — filter minimum likes --min-impressions N — filter minimum views --pages N — pages to fetch, 1-5 (default: 1) --limit N — max results to display (default: 15) --quick — fast mode: 1 page, max 10 results, noise filter, 1hr cache --from <username> — shorthand for from:username in query --quality — filter low-engagement tweets (≥10 likes) --no-replies — exclude replies --save — save results to file --type Top|Latest — search mode (default: Latest; Top returns algorithmic ranking) --json — raw JSON output --markdown — markdown formatted output Auto-adds -is:retweet unless query already includes it. Cost estimate shown after each search. Examples: npx tsx x-search.ts search "AI agents Base chain" --sort likes --limit 10 npx tsx x-search.ts search "BNKR" --quick npx tsx x-search.ts search "from:frankdegods" --sort recent npx tsx x-search.ts search "(opus OR claude) trading" --pages 2 --save npx tsx x-search.ts search "$SOL memecoin" --min-likes 50 --since 1d Search operators (passed through to X): OperatorExampleNoteskeywordbun 2.0Implicit ANDORbun OR denoMust be uppercase--is:retweetNegation()(fast OR perf)Groupingfrom:from:elonmuskPosts by userto:to:elonmuskReplies to user##buildinpublicHashtag$$AAPLCashtaglang:lang:enLanguage filteris:retweet-is:retweetFilter retweetsis:reply-is:replyFilter replieshas:mediahas:mediaContains mediahas:linkshas:linksContains linksmin_faves:min_faves:100Min likes (native)

Profile

npx tsx x-search.ts profile <username> [--count N] [--replies] [--json] Fetches user info and recent tweets. Excludes replies by default.

Single Tweet

npx tsx x-search.ts tweet <tweet_id> [--json]

Thread

npx tsx x-search.ts thread <tweet_id> Fetches root tweet, author thread continuations, and replies in chronological order.

Replies

npx tsx x-search.ts replies <tweet_id> [--sort likes|recent] [--limit N] Get replies to a specific tweet, sorted by engagement.

Quote Tweets

npx tsx x-search.ts quotes <tweet_id> [--sort likes|recent] [--limit N] See who quoted a tweet and what they said.

Mentions

npx tsx x-search.ts mentions <username> [--since 1d|7d] [--sort recent|likes] [--limit N] Get tweets that mention a user. Great for tracking what people are saying about someone.

Followers / Following

npx tsx x-search.ts followers <username> [--limit N] npx tsx x-search.ts following <username> [--limit N] List a user's followers or who they follow. Shows name, follower count, and bio snippet.

Search Users

npx tsx x-search.ts users "<query>" [--limit N] Search for user accounts by keyword.

Trending

npx tsx x-search.ts trending [--woeid N] [--count N] Get trending topics. Default: worldwide (woeid=1). Common WOEIDs: US=23424977, UK=23424975, Italy=23424853.

Community

npx tsx x-search.ts community <id> # Community info npx tsx x-search.ts community tweets <id> # Community tweets Research X Communities by ID.

Watchlist

npx tsx x-search.ts watchlist # Show all npx tsx x-search.ts watchlist add <user> [note] # Add account npx tsx x-search.ts watchlist remove <user> # Remove account npx tsx x-search.ts watchlist check # Check recent from all Watchlist stored in data/watchlist.json. Use for periodic monitoring — check if key accounts posted anything notable.

Cache

npx tsx x-search.ts cache clear # Clear all cached results Default 15-minute TTL. Quick mode uses 1-hour TTL. Avoids repeat API charges.

Research Loop (Agentic)

When doing deep research (not just a quick search), follow this loop:

1. Decompose the Question into Queries

Turn the research question into 3-5 keyword queries: Core query: Direct keywords for the topic Expert voices: from: specific known experts Pain points: Keywords like (broken OR bug OR issue) Positive signal: Keywords like (shipped OR love OR fast) Links: has:links for resource-rich tweets Crypto spam: Add -airdrop -giveaway -whitelist if needed

2. Search and Extract

Run each query via CLI. After each, assess: Signal or noise? Adjust operators. Key voices worth searching from: specifically? Threads worth following via thread command?

3. Follow Threads

When a tweet has high engagement or is a thread starter: npx tsx x-search.ts thread <tweet_id>

4. Synthesize

• Group findings by theme, not by query:
• ### [Theme/Finding Title]
• [1-2 sentence summary]
• @username: "[key quote]" (♥ N, 👁 N) [Tweet](url)
• @username2: "[another perspective]" (♥ N, 👁 N) [Tweet](url)

5. Save

Use --save flag or --markdown for research docs.

Refinement Heuristics

Too much noise? Add --no-replies, use --sort likes, narrow keywords Too few results? Broaden with OR, remove restrictive operators Crypto spam? Add -airdrop -giveaway -whitelist to query Expert takes only? Use from: or --min-likes 50 Substance over hot takes? Search with has:links

Heartbeat Integration

On heartbeat, run watchlist check to see if key accounts posted anything notable. Flag only if genuinely interesting/actionable.

Cost

TwitterAPI.io pay-per-use pricing: ~$0.15 per 1,000 tweets fetched ~$0.18 per profile lookup Cost estimate shown after each command Cache prevents redundant charges

File Structure

skills/x-research/ ├── SKILL.md # This file ├── package.json # Zero dependencies ├── scripts/ │ ├── x-search.ts # CLI entry point │ └── lib/ │ ├── api.ts # TwitterAPI.io wrapper │ ├── cache.ts # File-based cache (15min/1hr TTL) │ └── format.ts # Terminal + markdown formatters ├── data/ │ ├── watchlist.json # Accounts to monitor │ └── cache/ # Auto-managed └── references/ └── twitterapi-io.md # API endpoint reference

Requirements

Node.js 18+ (for native fetch) A TwitterAPI.io API key No npm install needed — zero dependencies