x-research

x-research

Research X/Twitter via xAI Grok API. Grok's x_search tool searches X in real-time and returns synthesized analysis with citations.

Config

Get an xAI API key at console.x.ai, then:

cp config/.env.example config/.env

Edit config/.env: paste your key into XAI_API_KEY, configure accounts and topics.

Without .env: skill works with explicit --accounts, --query, --topics.

With .env: digests and trending ready out of the box.

Category registry (same pattern as telegram-channel-parser):

X_CATEGORIES=ai,crypto         # available categories
X_DEFAULT_CATEGORY=ai           # default for "digest" without specifying

X_ACCOUNTS_AI_LABEL="AI & ML"
X_ACCOUNTS_AI=elonmusk,sama,AndrewYNg

X_TOPICS_AI=AI,LLM,GPT,Claude,agents,AGI

Agent algorithm for digest/trending:

1. Read config/.env
2. Parse X_CATEGORIES to get available categories
3. For each: X_ACCOUNTS_<ID> = handles, X_TOPICS_<ID> = topics, X_ACCOUNTS_<ID>_LABEL = name
4. Match user request to category label or use X_DEFAULT_CATEGORY
5. Pass to script via --accounts / --topics

Priority: --accounts/--topics explicit > category from .env > agent asks.

Details: config/README.md.

Philosophy

1. Live-first — every call makes a fresh API request. Real-time data, never stale.
2. Artifact store — each run saves an immutable snapshot in cache/runs/. Use --prefer-cache to reuse.
3. Structured output — digest/trending/search return JSON with individual items for machine consumption.
4. Context hygiene — stdout limited to 30 lines. Full data in artifact file.
5. Config-driven model — model set in .env, auto-fallback if unavailable.

Workflow

Digest of subscribed accounts

# Default category from .env
bash scripts/digest.sh --period today

# Specific category
bash scripts/digest.sh --category crypto --period week

# Explicit accounts (no .env needed)
bash scripts/digest.sh --accounts "elonmusk,sama" --period today

Returns: structured items (author, date, summary, engagement, URL, topic) + Telegram post ideas.

Analyze a post/thread/topic

# By description
bash scripts/analyze.sh --query "Elon Musk's thread about open source AI"

# By URL
bash scripts/analyze.sh --url "https://x.com/elonmusk/status/123456" --query "context about the post"

# With time period
bash scripts/analyze.sh --query "debate about AI regulation" --period week

Returns: main thesis, key arguments, community reaction, sentiment, interesting findings, Telegram post angles.

Trending topics

# Default topics from .env
bash scripts/trending.sh --period today

# Specific topics
bash scripts/trending.sh --topics "Bitcoin,Ethereum,DeFi" --period today

# Category
bash scripts/trending.sh --category ai --period week

Returns: structured items (topic, summary, sentiment, key voices, engagement) + Telegram post ideas.

Custom search

# Free search
bash scripts/search.sh --query "Claude 4 reactions" --period week

# Search within specific accounts
bash scripts/search.sh --query "AI safety" --accounts "sama,ylecun" --period today

Returns: structured items + narrative summary + Telegram post ideas.

Reuse previous results

# Read last digest without making an API call
bash scripts/digest.sh --category ai --period today --prefer-cache

# Find artifact manually
bash scripts/find_latest.sh --script digest --category ai --period today

Scripts

bash scripts/<script>.sh [params]

Script	Description	Key params
digest.sh	Digest of subscribed accounts	--category, --accounts, --period
analyze.sh	Deep analysis of post/thread/topic	--query, --url, --period
trending.sh	Trending topics by interests	--category, --topics, --period
search.sh	Custom search query	--query, --accounts, --period
find_latest.sh	Find latest cached artifact	--script, --category, --query, --period

Common parameters

Param	Required	Default	Description
--accounts	no	from .env	X handles, comma-separated (without @)
--category	no	from .env	Category ID from X_CATEGORIES
--period	no	today	Time range: 1h, today, yesterday, week, Nd
--query	varies	—	Search query or post description
--topics	no	from .env	Topics for trending, comma-separated
--url	no	—	X post URL for analyze
--limit	no	30	Max output lines
--prefer-cache	no	—	Use latest cached artifact if available
--refresh	no	—	Force live request (default behavior)

Artifact store

Each run saves a JSON artifact in cache/runs/ with full metadata:

{
  "meta": {
    "script": "digest",
    "category": "ai",
    "handles": ["elonmusk", "sama"],
    "period": "today",
    "from_date": "2026-04-01",
    "to_date": "2026-04-01",
    "model": "grok-4-1-fast-reasoning",
    "created_at": "2026-04-01T14:30:22Z",
    "run_id": "a1b2c3"
  },
  "items": [...],
  "ideas": [...],
  "summary": "...",
  "text": "...",
  "citations": [...]
}

Index: cache/index.jsonl — one JSON line per run for fast lookup.

API limits

• x_search: max 10 handles per allowed_x_handles (auto-batched if more)
• Rate limits: tier-based, see docs.x.ai/developers/rate-limits
• Tool pricing: x_search invocations billed separately from tokens
• Model fallback: if primary model unavailable (HTTP 422/400), auto-retry with grok-4.20-reasoning

Limitations

• Only public posts (x_search does not access private/protected accounts)
• x_search is a server-side Grok tool — we get synthesized analysis, not raw post data
• Structured JSON output depends on model compliance; fallback to plain text if parsing fails
• No DM access, no analytics data (only public engagement metrics)

Advanced scenarios: references/API_REFERENCE.md