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 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_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