Use this skill when building applications with the X API (formerly Twitter API). Covers posts, users, spaces, direct messages, lists, trends, media, webhooks, authentication, rate limits, and SDKs for Python and TypeScript.
The X API provides access to X's real-time global data. Key capabilities include:
The X API uses pay-per-usage pricing. No monthly subscriptions — pay only for what you use.
[!IMPORTANT] Earn free xAI API credits when you purchase X API credits — up to 20% back based on your spend.
# Set Authorization header
Authorization: Bearer YOUR_BEARER_TOKEN
# For user actions, use OAuth 2.0 with appropriate scopes
Authorization: Bearer YOUR_ACCESS_TOKEN
tweet.read - Read tweetstweet.write - Create tweetstweet.moderate.write - Moderate tweetsusers.read - Read user profilesfollows.read - Read followsfollows.write - Follow/unfollowoffline.access - Refresh access tokensspace.read - Read Spacesspace.write - Create Spacesdm.read - Read DMsdm.write - Send DMsInstall with pip install x-python (official SDK coming soon, use requests for now)
import requests
def get_user_tweets(username, bearer_token):
url = f"https://api.x.com/2/tweets/by/username/{username}"
headers = {"Authorization": f"Bearer {bearer_token}"}
response = requests.get(url, headers=headers)
return response.json()
Install with npm install x-sdk (official SDK coming soon, use fetch for now)
async function getUserTweets(username: string, bearerToken: string) {
const response = await fetch(
`https://api.x.com/2/tweets/by/username/${username}`,
{
headers: { Authorization: `Bearer ${bearerToken}` }
}
);
return response.json();
}
# Get your own user info
curl "https://api.x.com/2/users/me" \
-H "Authorization: Bearer YOUR_BEARER_TOKEN"
import requests
# Post a tweet
def post_tweet(text, bearer_token):
url = "https://api.x.com/2/tweets"
headers = {
"Authorization": f"Bearer {bearer_token}",
"Content-Type": "application/json"
}
data = {"text": text}
response = requests.post(url, headers=headers, json=data)
return response.json()
# Usage
result = post_tweet("Hello from X API!", "YOUR_BEARER_TOKEN")
print(result)
https://api.x.com/2/ prefix for most endpointsPOST /2/tweets - Create a postGET /2/tweets/:id - Get a post by IDDELETE /2/tweets/:id - Delete a postGET /2/tweets/search/recent - Search recent postsGET /2/tweets/search/all - Search all posts (premium)GET /2/users/:id - Get user by IDGET /2/users/by/username/:username - Get user by usernameGET /2/users/:id/tweets - Get user's tweetsGET /2/users/:id/followers - Get followersGET /2/users/:id/following - Get followingPOST /2/users/:id/following - Follow a userDELETE /2/users/:id/following/:target_user_id - UnfollowGET /2/spaces/:id - Get Space by IDGET /2/spaces/search - Search SpacesGET /2/spaces/:id/tweets - Get Space tweetsGET /2/lists/:id - Get list by IDGET /2/users/:id/lists - Get user's listsPOST /2/lists - Create a listPOST /2/lists/:id/members - Add member to listGET /2/dm_conversations - Get DM conversationsPOST /2/dm_conversations - Create DM conversationGET /2/dm_conversations/:id/messages - Get messagesGET /2/trends/by/woeid/:woeid - Get trends by WOEIDPOST /2/media/upload - Upload mediaGET /2/media/:id - Get media infoRate limits vary by endpoint and your plan. Check the API Reference for specific limits.
General guidelines:
Documentation Index: https://docs.x.com/llms.txt
Fetch this index to discover all available documentation pages.
Set up webhooks to receive real-time events:
Events available:
tweet_createtweet_deletefollowunfollowfavoritedm_receivedConnect to real-time streams:
import sseclient
import requests
def stream_tweets(bearer_token):
url = "https://api.x.com/2/tweets/search/stream"
headers = {"Authorization": f"Bearer {bearer_token}"}
response = requests.get(url, headers=headers, stream=True)
client = sseclient.SSEClient(response)
for event in client.events():
print(event.data)