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:

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.

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_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_daily_prices — cross-reference X sentiment with price action
• get_sec_filing — pair chatter with official disclosures
• scrape scrape_page / scrape_pages — fallback for public pages when the API is blocked
• web_search — broader news search that also indexes X posts