X Research
Agentic research over X/Twitter. Decompose research questions into targeted searches, iteratively refine, follow threads, deep-dive linked content, and synthesize sourced briefings.
For X API details (endpoints, operators, response format): read {baseDir}/skills/x-research/references/x-api.md .
Prerequisites
-
X API Bearer Token -- set X_BEARER_TOKEN (or XAI_API_KEY ) env var
-
Python 3.11+ and uv (pip install uv or https://docs.astral.sh/uv/)
CLI Tool
All commands use uv run for automatic dependency management:
Search
uv run {baseDir}/skills/x-research/scripts/x_search.py search "<query>" [options]
Options:
-
--sort likes|impressions|retweets|recent -- sort order (default: likes)
-
--since 1h|3h|12h|1d|7d -- time filter (default: last 7 days)
-
--min-likes N -- filter by minimum likes
-
--min-impressions N -- filter by minimum impressions
-
--pages N -- pages to fetch, 1-5 (default: 1, 100 tweets/page)
-
--limit N -- max results to display (default: 15)
-
--quick -- quick mode: 1 page, max 10 results, auto noise filter, 1hr cache
-
--from-user <username> -- shorthand for from:username in query
-
--quality -- filter low-engagement tweets (min 10 likes, post-hoc)
-
--no-replies -- exclude replies
-
--save -- save results to ~/x-research-output/
-
--json -- raw JSON output
-
--markdown -- markdown output for research docs
Auto-adds -is:retweet unless query already includes it. All searches display estimated API cost.
Examples:
uv run {baseDir}/skills/x-research/scripts/x_search.py search "claude code" --sort likes --limit 10 uv run {baseDir}/skills/x-research/scripts/x_search.py search "from:anthropic" --sort recent uv run {baseDir}/skills/x-research/scripts/x_search.py search "(cursor OR windsurf) AI editor" --pages 2 --save uv run {baseDir}/skills/x-research/scripts/x_search.py search "AI agents" --quick uv run {baseDir}/skills/x-research/scripts/x_search.py search "AI agents" --quality --quick
Profile
uv run {baseDir}/skills/x-research/scripts/x_search.py profile <username> [--count N] [--replies] [--json]
Fetches recent tweets from a specific user (excludes replies by default).
Thread
uv run {baseDir}/skills/x-research/scripts/x_search.py thread <tweet_id> [--pages N]
Fetches full conversation thread by root tweet ID.
Single Tweet
uv run {baseDir}/skills/x-research/scripts/x_search.py tweet <tweet_id> [--json]
Watchlist
uv run {baseDir}/skills/x-research/scripts/x_search.py watchlist # Show all uv run {baseDir}/skills/x-research/scripts/x_search.py watchlist add <user> [note] # Add account uv run {baseDir}/skills/x-research/scripts/x_search.py watchlist remove <user> # Remove uv run {baseDir}/skills/x-research/scripts/x_search.py watchlist check # Check recent
Watchlist stored in {baseDir}/skills/x-research/data/watchlist.json .
Cache
uv run {baseDir}/skills/x-research/scripts/x_search.py cache clear
15-minute TTL. Avoids re-fetching identical queries.
Research Loop (Agentic)
When doing deep research (not just a quick search), follow this loop:
- Decompose the Question into Queries
Turn the research question into 3-5 keyword queries using X search operators:
-
Core query: Direct keywords for the topic
-
Expert voices: from: specific known experts
-
Pain points: Keywords like (broken OR bug OR issue OR migration)
-
Positive signal: Keywords like (shipped OR love OR fast OR benchmark)
-
Links: url:github.com or url: specific domains
-
Noise reduction: -is:retweet (auto-added), add -is:reply if needed
-
Spam filter: Add -airdrop -giveaway -whitelist for crypto-adjacent topics
- 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?
-
Linked resources worth deep-diving with WebFetch ?
- Follow Threads
When a tweet has high engagement or is a thread starter:
uv run {baseDir}/skills/x-research/scripts/x_search.py thread <tweet_id>
- Deep-Dive Linked Content
When tweets link to GitHub repos, blog posts, or docs, fetch with WebFetch . Prioritize links that:
-
Multiple tweets reference
-
Come from high-engagement tweets
-
Point to technical resources directly relevant to the question
- Synthesize
Group findings by theme, not by query:
[Theme/Finding Title]
[1-2 sentence summary]
Resources shared:
- Resource title -- [what it is]
- Save
Use --save flag or save manually.
Refinement Heuristics
-
Too much noise? Add -is:reply , use --sort likes , narrow keywords
-
Too few results? Broaden with OR , remove restrictive operators
-
Spam flooding results? Add -$ -airdrop -giveaway -whitelist
-
Expert takes only? Use from: or --min-likes 50
-
Substance over hot takes? Search with has:links
When to Use
-
Researching what developers/experts/community thinks about a topic
-
Getting real-time perspectives on breaking news or product launches
-
Finding technical discussions about libraries, frameworks, or APIs
-
Monitoring what key accounts are posting about
-
Gathering sourced evidence for competitive analysis or market research
-
Quick pulse check on a topic before deeper investigation
When NOT to Use
-
Posting tweets, replying, or managing an X account (read-only tool)
-
Historical research beyond 7 days (uses recent search endpoint only)
-
Searching non-X platforms (use web search tools instead)
-
Tasks where web search provides better results (X is best for real-time opinions, discussions, and breaking news -- not reference docs)
Cost Awareness
X API uses pay-per-use pricing ($0.005/post read, $0.01/user lookup). Quick mode keeps costs under ~$0.50/search. Always check the cost display after each search. Cache prevents duplicate charges. See references/x-api.md for full pricing.
File Structure
skills/x-research/ SKILL.md (this file) scripts/ x_search.py (CLI entry point, run with uv) x_api.py (X API wrapper) x_cache.py (file-based cache, 15min TTL) x_format.py (terminal + markdown formatters) data/ watchlist.json (accounts to monitor) cache/ (auto-managed) references/ x-api.md (X API endpoint reference)