x-api

name: x-api 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."

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:

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.

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

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

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

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

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.

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.

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.

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