x

X API Skill Reference

Product summary

The X API is a modern REST API providing programmatic access to X's public conversation. Agents use it to read posts, retrieve user data, search trends, stream real-time posts, manage lists, send direct messages, and publish content. The API uses pay-per-usage pricing with no subscriptions. Key endpoints live at https://api.x.com/2/ and require Bearer Token (app-only) or OAuth authentication. Official SDKs exist for Python and TypeScript. Primary docs: https://docs.x.com/x-api/introduction

When to use

Reach for this skill when:

• Building integrations that read or publish posts, retrieve user profiles, or search X data
• Creating real-time monitoring tools using filtered stream
• Implementing analytics dashboards that need engagement metrics
• Building automation workflows (likes, follows, list management)
• Agents need to understand API authentication, rate limits, pagination, or error handling
• Debugging API integration issues (401, 403, 429 errors)
• Choosing between search endpoints (recent vs. full-archive) or authentication methods
• Working with SDKs (Python XDK, TypeScript XDK) for faster development

Quick reference

Authentication methods

Method	Use case	Scope
Bearer Token (app-only)	Read public data, no user context	App-level rate limits
OAuth 1.0a User Context	Act on behalf of a user, access private data	User-level rate limits
OAuth 2.0 Authorization Code	User sign-in flows, user-context requests	User-level rate limits
OAuth 2.0 App-Only	Alternative to Bearer Token	App-level rate limits

Core endpoints

Resource	Common endpoints
Posts	/2/tweets/search/recent, /2/tweets/search/all, /2/tweets/{id}, /2/tweets (create)
Users	/2/users/by/username/{username}, /2/users/{id}, /2/users/search
Timelines	/2/users/{id}/tweets, /2/users/{id}/mentions
Streams	/2/tweets/search/stream (filtered), /2/tweets/search/stream/rules (manage rules)
Lists	/2/lists/{id}, /2/lists (create), /2/lists/{id}/members
Direct Messages	/2/dm_conversations, /2/dm_events
Trends	/2/trends/by/woeid/{woeid}

Request parameters

Parameter	Purpose	Example
tweet.fields	Request post data fields	created_at,public_metrics,lang
user.fields	Request user data fields	created_at,description,public_metrics
expansions	Include related objects	author_id,referenced_tweets.id
max_results	Results per page	100 (varies by endpoint)
pagination_token	Navigate pages	From previous response meta.next_token
query	Search filter (search endpoints)	from:xdevelopers lang:en

Rate limit headers (in every response)

x-rate-limit-limit: 900
x-rate-limit-remaining: 847
x-rate-limit-reset: 1705420800

Decision guidance

When to use Bearer Token vs. OAuth user context

Scenario	Use Bearer Token	Use OAuth User Context
Read public posts, users, trends	✓	✓
Publish posts on behalf of user	✗	✓
Access user's private bookmarks/likes	✗	✓
Simple app-only automation	✓	✗
User sign-in required	✗	✓

When to use search endpoints

Need	Endpoint	Access	Time range
Quick search, testing	/2/tweets/search/recent	All developers	Last 7 days
Historical analysis, research	/2/tweets/search/all	Pay-per-use, Enterprise	Back to 2006
Real-time monitoring	/2/tweets/search/stream	All developers	Ongoing

When to use SDKs vs. raw HTTP

Scenario	Use SDK	Use raw HTTP
Production application	✓	✗
Quick testing/prototyping	✗	✓ (cURL)
Automatic pagination needed	✓	✗
Streaming with reconnection	✓	✗
Custom HTTP client required	✗	✓

Workflow

Making an API request

1. Get credentials: In Developer Console (console.x.com), create an app and copy the Bearer Token from Keys and tokens section.

2. Choose endpoint: Identify what data you need (posts, users, trends, etc.) and find the appropriate endpoint in API reference.

3. Build request URL: Start with https://api.x.com/2/ + endpoint path. Add query parameters for fields, expansions, pagination.

4. Add authentication: Include Authorization: Bearer YOUR_TOKEN header.

5. Make request: Use cURL, SDK, or HTTP client.

6. Parse response: Check HTTP status code. On success (2xx), data is in data field. On error, check title and detail fields.

7. Handle pagination: If response includes meta.next_token, use it as pagination_token for next request.

Streaming real-time posts

1. Add stream rules: POST to /2/tweets/search/stream/rules with rule definitions (e.g., {"add": [{"value": "from:xdevelopers"}]}).

2. Connect to stream: GET /2/tweets/search/stream with Bearer Token. Connection stays open, posts arrive as newline-delimited JSON.

3. Handle disconnections: Implement exponential backoff. Stream sends keep-alive every 20 seconds; reconnect if no data for 20+ seconds.

4. Process posts: Parse each line as JSON. Each object is a post matching your rules.

Using the Python SDK

from xdk import Client

client = Client(bearer_token="YOUR_TOKEN")

# Look up user
user = await client.users.get_by_username("xdevelopers")

# Search posts
posts = await client.posts.search_recent(query="from:xdevelopers", max_results=10)

# Paginate automatically
async for post in client.posts.search_recent(query="AI", max_results=100):
    print(post.text)

Common gotchas

• Missing fields in response: By default, endpoints return minimal fields. Always add tweet.fields or user.fields parameters to get the data you need.

• 401 Unauthorized: Verify Bearer Token is correct, hasn't been regenerated, and header format is Authorization: Bearer TOKEN (not Bearer: TOKEN).

• 403 Forbidden: App may lack access to endpoint. Check Developer Console for enrollment status. Some endpoints require specific approval.

• 429 Too Many Requests: You've hit rate limits. Check x-rate-limit-reset header for Unix timestamp when limit resets. Implement exponential backoff: wait 1 minute, then double wait time on each retry.

• Pagination tokens expire: Don't store tokens for later use. If resuming pagination, start fresh request.

• Stream disconnects silently: Always implement reconnection logic with exponential backoff. Stream sends keep-alive every 20 seconds; if you don't receive data or keep-alive for 20+ seconds, reconnect.

• Mutable data in search results: User handles and post metrics can change after indexing. Search returns data as indexed, not real-time. Use numeric user IDs instead of @handles for consistent filtering.

• Partial errors in batch requests: A 200 response may include both data and errors arrays. Always check for errors even on success.

• JSON body not signed in OAuth 1.0a: When signing OAuth 1.0a requests, only URL parameters go into signature base string, not JSON body. This is the most common cause of 401 errors.

Verification checklist

Before submitting work with X API integration:

• Authentication credentials are stored securely (not in code)
• Bearer Token or OAuth tokens are valid and not regenerated
• Request includes correct Authorization header
• Endpoint URL is correct and uses https://api.x.com/2/
• Required query parameters are present (e.g., query for search)
• Field parameters are included to request needed data
• Error handling covers 401, 403, 404, 429 status codes
• Rate limit headers are checked before hitting limits
• Pagination logic handles next_token correctly
• For streaming: reconnection logic with exponential backoff is implemented
• Response parsing checks for both data and errors fields
• Tests pass with actual API calls (not mocked)

Resources

Comprehensive navigation: https://docs.x.com/llms.txt

Critical documentation:

• X API Introduction — Overview, pricing, key features
• Make Your First Request — Quickstart with cURL and code examples
• Authentication Overview — All auth methods explained
• Response Codes & Errors — Error reference and troubleshooting
• Rate Limits — Rate limit behavior and best practices
• Fields & Expansions — Customize response data
• Pagination — Page through results
• Filtered Stream — Real-time post streaming
• Python SDK — Official Python library
• TypeScript SDK — Official TypeScript library

---

For additional documentation and navigation, see: https://docs.x.com/llms.txt