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
1# Environment setup
2export X_BEARER_TOKEN="your-bearer-token"

python
1import os
2import requests
3
4bearer = os.environ["X_BEARER_TOKEN"]
5headers = {"Authorization": f"Bearer {bearer}"}
6
7# Search recent tweets
8resp = requests.get(
9    "https://api.x.com/2/tweets/search/recent",
10    headers=headers,
11    params={"query": "claude code", "max_results": 10}
12)
13tweets = resp.json()

OAuth 1.0a (User Context)

Required for: posting tweets, managing account, DMs.

bash
1# Environment setup — source before use
2export X_API_KEY="your-api-key"
3export X_API_SECRET="your-api-secret"
4export X_ACCESS_TOKEN="your-access-token"
5export X_ACCESS_SECRET="your-access-secret"

python
1import os
2from requests_oauthlib import OAuth1Session
3
4oauth = OAuth1Session(
5    os.environ["X_API_KEY"],
6    client_secret=os.environ["X_API_SECRET"],
7    resource_owner_key=os.environ["X_ACCESS_TOKEN"],
8    resource_owner_secret=os.environ["X_ACCESS_SECRET"],
9)

Core Operations

Post a Tweet

python
1resp = oauth.post(
2    "https://api.x.com/2/tweets",
3    json={"text": "Hello from Claude Code"}
4)
5resp.raise_for_status()
6tweet_id = resp.json()["data"]["id"]

Post a Thread

python
1def post_thread(oauth, tweets: list[str]) -> list[str]:
2    ids = []
3    reply_to = None
4    for text in tweets:
5        payload = {"text": text}
6        if reply_to:
7            payload["reply"] = {"in_reply_to_tweet_id": reply_to}
8        resp = oauth.post("https://api.x.com/2/tweets", json=payload)
9        tweet_id = resp.json()["data"]["id"]
10        ids.append(tweet_id)
11        reply_to = tweet_id
12    return ids

Read User Timeline

python
1resp = requests.get(
2    f"https://api.x.com/2/users/{user_id}/tweets",
3    headers=headers,
4    params={
5        "max_results": 10,
6        "tweet.fields": "created_at,public_metrics",
7    }
8)

Search Tweets

python
1resp = requests.get(
2    "https://api.x.com/2/tweets/search/recent",
3    headers=headers,
4    params={
5        "query": "from:affaanmustafa -is:retweet",
6        "max_results": 10,
7        "tweet.fields": "public_metrics,created_at",
8    }
9)

Get User by Username

python
1resp = requests.get(
2    "https://api.x.com/2/users/by/username/affaanmustafa",
3    headers=headers,
4    params={"user.fields": "public_metrics,description,created_at"}
5)

Upload Media and Post

python
1# Media upload uses v1.1 endpoint
2
3# Step 1: Upload media
4media_resp = oauth.post(
5    "https://upload.twitter.com/1.1/media/upload.json",
6    files={"media": open("image.png", "rb")}
7)
8media_id = media_resp.json()["media_id_string"]
9
10# Step 2: Post with media
11resp = oauth.post(
12    "https://api.x.com/2/tweets",
13    json={"text": "Check this out", "media": {"media_ids": [media_id]}}
14)

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
1import time
2
3remaining = int(resp.headers.get("x-rate-limit-remaining", 0))
4if remaining < 5:
5    reset = int(resp.headers.get("x-rate-limit-reset", 0))
6    wait = max(0, reset - int(time.time()))
7    print(f"Rate limit approaching. Resets in {wait}s")

Error Handling

python
1resp = oauth.post("https://api.x.com/2/tweets", json={"text": content})
2if resp.status_code == 201:
3    return resp.json()["data"]["id"]
4elif resp.status_code == 429:
5    reset = int(resp.headers["x-rate-limit-reset"])
6    raise Exception(f"Rate limited. Resets at {reset}")
7elif resp.status_code == 403:
8    raise Exception(f"Forbidden: {resp.json().get('detail', 'check permissions')}")
9else:
10    raise Exception(f"X API error {resp.status_code}: {resp.text}")

Security

• Never hardcode tokens. Use environment variables or .env files.
• Never commit .env files. Add to .gitignore.
• Rotate tokens if exposed. Regenerate at developer.x.com.
• Use read-only tokens when write access is not needed.
• Store OAuth secrets securely — not in source code or logs.

Integration with Content Engine

Use content-engine skill to generate platform-native content, then post via X API:

1. Generate content with content-engine (X platform format)
2. Validate length (280 chars for single tweet)
3. Post via X API using patterns above
4. Track engagement via public_metrics

Related Skills

• content-engine — Generate platform-native content for X
• crosspost — Distribute content across X, LinkedIn, and other platforms