X API

--- name: x-api description: X/Twitter API integration for posting tweets, threads, reading timelines, search, and analytics. Covers OAuth auth patterns, rate limits, and platform-native content posting. Use when the user wants to interact with X programmatically. --- # X API Programmatic interaction with X (Twitter) for posting, reading, searching, and analytics. ## When to Activate - User wants to post tweets or threads programmatically - Reading timeline, mentions, or user data from X - Searching X for content, trends, or conversations - Building X integrations or bots - Analytics and engagement tracking - User says "post to X", "tweet", "X API", or "Twitter API" ## Authentication ### OAuth 2.0 Bearer Token (App-Only) Best for: read-heavy operations, search, public data. ``bash # Environment setup export X_BEARER_TOKEN="your-bearer-token" ` `python import os import requests bearer = os.environ["X_BEARER_TOKEN"] headers = {"Authorization": f"Bearer {bearer}"} # Search recent tweets resp = requests.get( "https://api.x.com/2/tweets/search/recent", headers=headers, params={"query": "claude code", "max_results": 10} ) tweets = resp.json() ` ### OAuth 1.0a (User Context) Required for: posting tweets, managing account, DMs, and any write flow. `bash # Environment setup : source before use export X_CONSUMER_KEY="your-consumer-key" export X_CONSUMER_SECRET="your-consumer-secret" export X_ACCESS_TOKEN="your-access-token" export X_ACCESS_TOKEN_SECRET="your-access-token-secret" ` Legacy aliases such as XAPIKEY, XAPISECRET, and XACCESSSECRET may exist in older setups. Prefer the XCONSUMER* and XACCESSTOKEN_SECRET names when documenting or wiring new flows. `python import os from requests_oauthlib import OAuth1Session oauth = OAuth1Session( os.environ["X_CONSUMER_KEY"], client_secret=os.environ["X_CONSUMER_SECRET"], resource_owner_key=os.environ["X_ACCESS_TOKEN"], resource_owner_secret=os.environ["X_ACCESS_TOKEN_SECRET"], ) ` ## Core Operations ### Post a Tweet `python resp = oauth.post( "https://api.x.com/2/tweets", json={"text": "Hello from Claude Code"} ) resp.raise_for_status() tweet_id = resp.json()["data"]["id"] ` ### Post a Thread `python def post_thread(oauth, tweets: list[str]) -> list[str]: ids = [] reply_to = None for text in tweets: payload = {"text": text} if reply_to: payload["reply"] = {"in_reply_to_tweet_id": reply_to} resp = oauth.post("https://api.x.com/2/tweets", json=payload) tweet_id = resp.json()["data"]["id"] ids.append(tweet_id) reply_to = tweet_id return ids ` ### Read User Timeline `python resp = requests.get( f"https://api.x.com/2/users/{user_id}/tweets", headers=headers, params={ "max_results": 10, "tweet.fields": "created_at,public_metrics", } ) ` ### Search Tweets `python resp = requests.get( "https://api.x.com/2/tweets/search/recent", headers=headers, params={ "query": "from:affaanmustafa -is:retweet", "max_results": 10, "tweet.fields": "public_metrics,created_at", } ) ` ### Pull Recent Original Posts for Voice Modeling `python resp = requests.get( "https://api.x.com/2/tweets/search/recent", headers=headers, params={ "query": "from:affaanmustafa -is:retweet -is:reply", "max_results": 25, "tweet.fields": "created_at,public_metrics", } ) voice_samples = resp.json() ` ### Get User by Username `python resp = requests.get( "https://api.x.com/2/users/by/username/affaanmustafa", headers=headers, params={"user.fields": "public_metrics,description,created_at"} ) ` ### Upload Media and Post `python # Media upload uses v1.1 endpoint # Step 1: Upload media media_resp = oauth.post( "https://upload.twitter.com/1.1/media/upload.json", files={"media": open("image.png", "rb")} ) media_id = media_resp.json()["media_id_string"] # Step 2: Post with media resp = oauth.post( "https://api.x.com/2/tweets", json={"text": "Check this out", "media": {"media_ids": [media_id]}} ) ` ## Rate Limits X API rate limits vary by endpoint, auth method, and account tier, and they change over time. Always: - Check the current X developer docs before hardcoding assumptions - Read x-rate-limit-remaining and x-rate-limit-reset headers at runtime - Back off automatically instead of relying on static tables in code `python import time remaining = int(resp.headers.get("x-rate-limit-remaining", 0)) if remaining < 5: reset = int(resp.headers.get("x-rate-limit-reset", 0)) wait = max(0, reset - int(time.time())) print(f"Rate limit approaching. Resets in {wait}s") ` ## Error Handling ``python resp = oauth.post("https://api.x.com/2/tweets", json={"text": content}) if resp.statuscode == 201: return resp.json()["data"]["id"] elif resp.statuscode == 429: reset =