\r \r

Felo X Search Skill\r

\r

When to Use\r

\r Trigger this skill when the user wants to:\r \r

• Look up X (Twitter) user profiles by username\r
• Search for X users by keyword\r
• Get tweets from a specific X user\r
• Search tweets by keyword or advanced query\r
• Get replies to specific tweets\r \r Trigger keywords (examples):\r \r
• English: twitter, tweet, X user, X search, tweets from, replies to, trending on X\r
• 简体中文: 推特, 推文, X用户, X搜索, 推文回复\r
• 日本語: ツイッター, ツイート, Xユーザー, X検索\r \r Explicit commands: /felo-x-search, "search X", "search twitter"\r \r Do NOT use for:\r \r
• General web search (use felo-search)\r
• Webpage extraction (use felo-web-extract)\r
• Generating slides (use felo-slides)\r \r

Setup\r

\r

1. Get API key\r

\r

1. Visit felo.ai\r
2. Open Settings -> API Keys\r
3. Create and copy your API key\r \r

2. Configure environment variable\r

\r Linux/macOS:\r \r

export FELO_API_KEY="your-api-key-here"\r
```\r
\r
Windows PowerShell:\r
\r
```powershell\r
$env:FELO_API_KEY="your-api-key-here"\r
```\r
\r
## How to Execute\r
\r
### Option A: Use the bundled script or packaged CLI\r
\r
**Packaged CLI** (after `npm install -g felo-ai`):\r
\r
```bash\r
felo x [query] [options]\r
```\r
\r
**Script** (from repo):\r
\r
```bash\r
node felo-x-search/scripts/run_x_search.mjs [query] [options]\r
```\r
\r
### Usage Pattern\r
\r
The `x` command uses parameter combinations to infer intent — no subcommands needed.\r
\r
**With query (search mode):**\r
\r
| Usage | Behavior |\r
|-------|----------|\r
| `felo x "AI news"` | Search tweets (default) |\r
| `felo x -q "AI news"` | Same as above |\r
| `felo x "OpenAI" --user` | Search users |\r
\r
**With --id (lookup mode):**\r
\r
| Usage | Behavior |\r
|-------|----------|\r
| `felo x --id "1234567890"` | Get tweet replies (default) |\r
| `felo x --id "elonmusk" --user` | Get user info |\r
| `felo x --id "elonmusk" --user --tweets` | Get user tweets |\r
\r
### Options\r
\r
| Option | Description |\r
|--------|-------------|\r
| `[query]` | Positional arg, search keyword (equivalent to -q) |\r
| `-q, --query \x3Ctext>` | Search keyword |\r
| `--id \x3Cvalues>` | Tweet IDs or usernames (comma-separated) |\r
| `--user` | Switch to user mode |\r
| `--tweets` | Get user tweets (with --id --user) |\r
| `-l, --limit \x3Cn>` | Number of results |\r
| `--cursor \x3Cstr>` | Pagination cursor |\r
| `--include-replies` | Include replies (with --tweets) |\r
| `--query-type \x3Ctype>` | Query type filter (tweet search) |\r
| `--since-time \x3Cval>` | Start time filter |\r
| `--until-time \x3Cval>` | End time filter |\r
| `-j, --json` | Output raw JSON |\r
| `-t, --timeout \x3Cseconds>` | Timeout in seconds (default: 30) |\r
\r
### Option B: Call API with curl\r
\r
```bash\r
# Search tweets\r
curl -X POST "https://openapi.felo.ai/v2/x/tweet/search" \\r
  -H "Authorization: Bearer $FELO_API_KEY" \\r
  -H "Content-Type: application/json" \\r
  -d '{"query": "AI news", "limit": 20}'\r
\r
# Search users\r
curl -X POST "https://openapi.felo.ai/v2/x/user/search" \\r
  -H "Authorization: Bearer $FELO_API_KEY" \\r
  -H "Content-Type: application/json" \\r
  -d '{"query": "artificial intelligence"}'\r
\r
# Get user info\r
curl -X POST "https://openapi.felo.ai/v2/x/user/info" \\r
  -H "Authorization: Bearer $FELO_API_KEY" \\r
  -H "Content-Type: application/json" \\r
  -d '{"usernames": ["elonmusk", "OpenAI"]}'\r
\r
# Get user tweets\r
curl -X POST "https://openapi.felo.ai/v2/x/user/tweets" \\r
  -H "Authorization: Bearer $FELO_API_KEY" \\r
  -H "Content-Type: application/json" \\r
  -d '{"username": "elonmusk", "limit": 20}'\r
\r
# Get tweet replies\r
curl -X POST "https://openapi.felo.ai/v2/x/tweet/replies" \\r
  -H "Authorization: Bearer $FELO_API_KEY" \\r
  -H "Content-Type: application/json" \\r
  -d '{"tweet_ids": ["1234567890"]}'\r
```\r
\r
## Output Format\r
\r
### User Info (default, non-JSON)\r
\r
```markdown\r
## @elonmusk (Elon Musk 🔵)\r
- User ID: `44196397`\r
- Followers: 100.0M\r
- Following: 500\r
- Total Tweets: 30.0K\r
- Bio: ...\r
- Location: Mars\r
- Account Created: 2009-06-02T00:00:00Z\r
\r
---\r
```\r
\r
### Tweet (default, non-JSON)\r
\r
```markdown\r
### @elonmusk(Elon Musk ✓)\r
- Posted: 2026-03-09T12:00:00Z ｜ Tweet ID: `1234567890`\r
\r
Tweet content here...\r
\r
Engagement: 5.0K likes ｜ 1.0K retweets ｜ 200 replies\r
\r
---\r
```\r
\r
## Error Handling\r
\r
### Common Error Codes\r
\r
- `INVALID_API_KEY` — API Key is invalid or revoked\r
- `X_SEARCH_FAILED` — X search request failed (check parameters or downstream error)\r
\r
### Missing API Key\r
\r
If `FELO_API_KEY` is not set, display setup instructions and stop.\r
\r
## API Reference (summary)\r
\r
- **Base URL**: `https://openapi.felo.ai`. Override with `FELO_API_BASE` env if needed.\r
- **Auth**: `Authorization: Bearer YOUR_API_KEY`\r
- **Endpoints**:\r
  - `POST /v2/x/user/info` — Batch get user profiles\r
  - `POST /v2/x/user/search` — Search users\r
  - `POST /v2/x/user/tweets` — Get user tweets\r
  - `POST /v2/x/tweet/search` — Search tweets\r
  - `POST /v2/x/tweet/replies` — Get tweet replies\r
\r
## Important Notes\r
\r
- Always check `FELO_API_KEY` before calling; if missing, return setup instructions.\r
- Format output as readable Markdown by default; use `--json` for raw API response.\r
- Use pagination cursors (`next_cursor`) for fetching more results.\r
- For tweet search, advanced query syntax is supported (same as X advanced search).\r
\r
## References\r
\r
- [Felo X Search API](https://openapi.felo.ai/docs/api-reference/v2/x-search.html)\r
- [Felo Open Platform](https://openapi.felo.ai/docs/)\r