Search X

---

name: search-x

description: Search X/Twitter in real-time using Grok or X API. Find tweets, trends, and discussions with citations.

homepage: https://docs.x.ai

user-invocable: true

disable-model-invocation: true

triggers:

- search x

- search twitter

- find tweets

- what's on x about

- x search

- twitter search

metadata:

clawdbot:

emoji: "🔍"

primaryEnv: XAI_API_KEY

requires:

bins: [node]

env: [XAI_API_KEY]

---

# Search X

Real-time X/Twitter search with two modes:

1. **xAI Grok** (default) — AI-powered search with x_search tool, up to 30 days

2. **X API** (`--x-api`) — Native X search, up to 7 days, pay-per-use

Setup

Option 1: xAI API (default)

export XAI_API_KEY="xai-YOUR-KEY"

Get your key at: https://console.x.ai

Option 2: X API (native)

export X_BEARER_TOKEN="YOUR-BEARER-TOKEN"

Get your token at: https://console.x.com

**Note:** X API uses pay-per-usage pricing. No subscription needed.

Commands

Basic Search (xAI Grok)

node {baseDir}/scripts/search.js "AI video editing"

Native X API Search

node {baseDir}/scripts/search.js --x-api "AI video editing"
node {baseDir}/scripts/search.js --x-api --max 50 "trending topic"  # More results

Filter by Time

node {baseDir}/scripts/search.js --days 7 "breaking news"
node {baseDir}/scripts/search.js --days 1 "trending today"
node {baseDir}/scripts/search.js --x-api --days 7 "news"  # X API max is 7 days

Filter by Handles

node {baseDir}/scripts/search.js --handles @elonmusk,@OpenAI "AI announcements"
node {baseDir}/scripts/search.js --exclude @bots "real discussions"

Output Options

node {baseDir}/scripts/search.js --json "topic"        # Full JSON response
node {baseDir}/scripts/search.js --compact "topic"     # Just tweets, no fluff
node {baseDir}/scripts/search.js --links-only "topic"  # Just X links

Example Usage in Chat

**User:** "Search X for what people are saying about Claude Code"

**Action:** Run search with query "Claude Code"

**User:** "Find tweets from @remotion_dev in the last week"

**Action:** Run search with --handles @remotion_dev --days 7

**User:** "What's trending about AI on Twitter today?"

**Action:** Run search with --days 1 "AI trending"

**User:** "Search X for Remotion best practices, last 30 days"

**Action:** Run search with --days 30 "Remotion best practices"

How It Works

xAI Grok Mode (default)

Uses xAI's Responses API (`/v1/responses`) with the `x_search` tool:

X API Mode (--x-api)

Uses X's native search API (`/2/tweets/search/recent`):

Response Format

Each result includes:

Environment Variables

**xAI Mode:**

**X API Mode:**

Security & Permissions

**What this skill does:**

**What this skill does NOT do:**

Review `scripts/search.js` before first use to verify behavior.