# X API

Search X (Twitter) posts, pull user profiles, fetch specific tweets, and read reply...

- Repository: https://github.com/ginlix-ai/LangAlpha (2232 stars)
- Category: Writing
- License: Apache-2.0
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add ginlix-ai/LangAlpha --skill x-api -g -a claude-code -y`
Codex: `npx skills add ginlix-ai/LangAlpha --skill x-api -g -a codex -y`
Cursor: `npx skills add ginlix-ai/LangAlpha --skill x-api -g -a cursor -y`
Gemini CLI: `npx skills add ginlix-ai/LangAlpha --skill x-api -g -a gemini-cli -y`

## Description

Search X (Twitter) posts, pull user profiles, fetch specific tweets, and read reply threads for sentiment, news, and event research. Triggers on 'X', 'Twitter', 'tweets about', 'sentiment on', 'what are people saying about', 'historical tweets', or any request to read public X content.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# X (Twitter) API

Read-only access to X content via five MCP tools. Use for sentiment on tickers, exec announcements, launches, event tracking, and qualitative research alongside SEC/market data.

> **Not for single-post URL lookups.** If the user hands you a specific X post URL and just wants its text or context, use `web_fetch` on the URL, no vault, no auth, no rate limit. Reach for this skill when the task is **search, aggregation, or thread traversal**.

## Auth

Every tool requires a `bearer_token`. Read it once per code block from the vault:

```python
from vault import get
token = get("X_BEARER_TOKEN")
```

If `token` is `None` or empty, the user hasn't added it yet. For the setup walkthrough and per-error fixes, see [TROUBLESHOOTING.md](./TROUBLESHOOTING.md).

## Tools at a glance

The primary use case is **search**, the first two tools are what you'll reach for most.

| Tool | Use for | Page size | Notes |
|---|---|---|---|
| `search_posts` | Posts from the last ~7 days | default 10, max 100 | Default choice. Query ≤512 chars. |
| `search_all_posts` | Posts older than 7 days (back to 2006) | default 10, max 500 | Paid-tier X plan only. Query ≤1024 chars. |
| `get_conversation` | Reply thread to a root tweet | default 50, max 100 | Uses recent search, thread must be ≤7 days old. Root tweet not included. |
| `get_user_by_username` | A user profile + metrics |, | Handle without `@`, ≤15 chars. |
| `get_tweet_by_id` | Hydrate a single post (mainly to find its `conversation_id` before `get_conversation`) |, | For a one-off URL the user already has, prefer `web_fetch`. |

## Examples

### Recent sentiment on a ticker

```python
res = search_posts(
    query="$NVDA -is:retweet lang:en",
    bearer_token=token,
    max_results=100,
)
posts = res["posts"]
posts.sort(key=lambda p: p["public_metrics"].get("impression_count", 0), reverse=True)
for p in posts[:10]:
    print(p["author"]["username"], p["public_metrics"].get("like_count"), p["text"][:140])
```

The rest: https://github.com/ginlix-ai/LangAlpha/blob/HEAD/plugins/alternative_data/skills/x-api/SKILL.md