x-api

# 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 workspace 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])
```

### Historical reaction to a past event

```python
res = search_all_posts(
    query="$TSLA earnings -is:retweet lang:en",
    bearer_token=token,
    max_results=500,
    start_time="2020-03-13T00:00:00Z",
    end_time="2020-03-20T00:00:00Z",
)
```

### Full thread on a specific tweet

```python
root = get_tweet_by_id(tweet_id="1700000000000000001", bearer_token=token)
thread = get_conversation(
    conversation_id=root["post"]["conversation_id"],
    bearer_token=token,
    max_results=100,
)
all_posts = [root["post"], *thread["posts"]]
```

### Paginate through a large result

```python
posts, next_tok = [], None
while len(posts) < 500:
    res = search_posts(
        query="from:FedSpeakers",
        bearer_token=token,
        max_results=100,
        next_token=next_tok,
    )
    if "error" in res:
        break
    posts.extend(res["posts"])
    next_tok = res.get("next_token")
    if not next_tok:
        break
```

## Post shape

Each post: `id`, `text`, `created_at`, `lang`, `conversation_id`, `author_id`, `edit_history_tweet_ids`, `public_metrics` (retweet/reply/like/quote/bookmark/impression counts), `author` — which is `{id, username, name, verified}`, `{id, unresolved: true}` for suspended/deleted users, or `None` if the tweet has no author_id.

Full per-tool response schemas (including user shape and error variants): [reference.md](./reference.md).

## Query syntax

`$TSLA` (cashtag), `#hashtag`, `from:elonmusk`, `to:@SEC_News`, `-is:retweet`, `is:verified`, `has:links`, `has:media`, `lang:en`, `"exact phrase"`, parentheses + `OR` for alternation. Full list: https://docs.x.com/x-api/posts/search/introduction.

## Errors

Every tool returns `{"error": "...", ...}` on failure — they never raise. Always check for `error` before accessing `posts` / `user` / `post`. For the per-error playbook (including setup fixes and tier gotchas), read [TROUBLESHOOTING.md](./TROUBLESHOOTING.md).

## Do / Don't

- **Do** read `token = get("X_BEARER_TOKEN")` once and reuse it across calls.
- **Do** cross-reference with `get_stock_daily_prices` and `get_sec_filing` when investigating price moves or disclosures.
- **Don't** hardcode tokens. Ever.
- **Don't** cache `next_token` across sessions — cursors can expire.
- **Don't** assume every author is resolved — check for `{unresolved: true}` before reading `username`.

## Related

- `get_stock_daily_prices` — cross-reference X sentiment with price action
- `get_sec_filing` — pair chatter with official disclosures
- `scrapling` `get` / `fetch` — fallback for public pages when the API is blocked
- `web_search` — broader news search that also indexes X posts