X API Skill

Product summary

The X API provides programmatic access to X's public conversation through modern REST endpoints. Agents use it to search posts, retrieve user data, publish content, manage lists and direct messages, stream real-time posts, and access trends. The API uses pay-per-usage pricing with no subscriptions. Key endpoints live at https://api.x.com/2/. Authentication requires a developer account, project, and app created in the Developer Console. Official SDKs exist for Python (xdk) and TypeScript (@xdevplatform/xdk). See the primary docs site for comprehensive reference.

When to use

Reach for this skill when:

• Searching posts: Find posts by keyword, hashtag, user, date, or language using recent search (7 days) or full-archive search (back to 2006)
• Retrieving user data: Look up user profiles, followers, following lists, or verify user information
• Publishing content: Create posts, replies, quotes, or posts with media, polls, or thread management
• Streaming real-time data: Set up filtered stream rules to receive posts matching specific criteria as they're published
• Managing user relationships: Follow, unfollow, block, or mute users; manage lists and bookmarks
• Accessing direct messages: Send, retrieve, or delete DMs
• Analyzing trends: Get trending topics by location or personalized trends
• Compliance: Track post edits, deletions, and user account changes via compliance streams
• Troubleshooting API errors: Handle 401 (auth), 403 (access), 429 (rate limit), or 404 (not found) responses

Quick reference

Authentication methods

Core endpoints

Field and expansion parameters

Request additional data with fields and expansions:

# Request specific fields
?tweet.fields=created_at,public_metrics,lang
?user.fields=created_at,description,public_metrics

# Include related objects
?expansions=author_id,attachments.media_keys
?media.fields=url,preview_image_url,alt_text

Rate limit headers

Every response includes:

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

Check x-rate-limit-reset (Unix timestamp) to know when to retry after a 429 error.

Common query operators

Decision guidance

When to use Bearer Token vs. OAuth 1.0a

When to use recent search vs. full-archive search

When to use filtered stream vs. search

Workflow

Typical task: Search posts and retrieve details

1. Authenticate: Get Bearer Token from Developer Console or generate OAuth tokens
2. Build query: Use operators to construct search query (keywords, hashtags, users, dates, language)
3. Make search request: Call /2/tweets/search/recent or /2/tweets/search/all with query parameter
4. Request fields: Add tweet.fields and expansions to get author, media, metrics
5. Handle pagination: Use next_token from response to fetch additional pages
6. Parse response: Extract data from data array; related objects in includes
7. Check rate limits: Monitor x-rate-limit-remaining header; implement backoff if approaching limit

Typical task: Create and publish a post

1. Authenticate: Use OAuth 1.0a User Context (requires user's access tokens)
2. Prepare payload: Build JSON with text, optional reply, media, poll, or quotetweetid
3. Upload media (if needed): Use /2/media/upload endpoint first, get media IDs
4. POST to /2/tweets: Send request with Authorization header
5. Parse response: Extract post ID and edit history from response
6. Verify: Check response status; handle 201 (success) or error codes

Typical task: Set up filtered stream

1. Define rules: Create filter rules using operators (e.g., from:xdevelopers has:images)
2. Add rules: POST to /2/tweets/search/stream/rules with rule value
3. Connect to stream: GET /2/tweets/search/stream with Authorization header
4. Handle streaming: Read JSON objects line-by-line as posts arrive
5. Implement reconnection: Detect disconnects; use exponential backoff to reconnect
6. Process posts: Parse each post object; extract fields based on request parameters

Common gotchas

• Missing fields in response: By default, endpoints return only id, text, and edithistorytweet_ids. Always request additional fields explicitly with tweet.fields, user.fields, etc.
• Expansions without fields: Using expansions=author_id includes the author object, but you must also request user.fields to get author details beyond ID.
• Bearer Token vs. User Token: Bearer Token (app-only) cannot post, like, or follow. Use OAuth 1.0a User Context for user actions.
• Rate limit window resets: Limits reset at the Unix timestamp in x-rate-limit-reset, not after a fixed delay. Calculate wait time as resettime - currenttime.
• Query length limits: Recent search allows 512 characters; full-archive allows 1024. Queries exceeding this fail silently or return truncated results.
• Filtered stream rules are persistent: Rules added to a stream remain until explicitly deleted. Reconnecting does not clear rules.
• Streaming disconnects are normal: Implement automatic reconnection with exponential backoff (start 1 minute, double each retry).
• Deleted/protected posts return 404: Posts deleted by user or withheld in regions return 404. Handle gracefully.
• Retweets and replies in search: By default, search includes retweets and replies. Use -is:retweet -is:reply to exclude them.
• Pagination tokens expire: next_token is valid for a limited time. Store and use immediately; don't cache for later.

Verification checklist

Before submitting work with the X API:

• Authentication: Verified correct token/credentials are in use; Bearer Token for read-only, OAuth 1.0a for user actions
• Fields requested: Added tweet.fields, user.fields, etc. for all data needed; not relying on defaults
• Expansions included: If requesting related objects (author, media), included both expansions and corresponding fields parameters
• Query syntax: Tested search query with operators; confirmed it returns expected posts
• Rate limits: Checked x-rate-limit-remaining header; implemented backoff for 429 errors
• Error handling: Handled 401 (auth), 403 (access), 404 (not found), 429 (rate limit) responses
• Pagination: For large result sets, implemented next_token handling; not fetching all pages unnecessarily
• Streaming: If using filtered stream, implemented reconnection logic and rule management
• Media upload: If posting with media, uploaded via /2/media/upload first; passed media IDs in post payload
• Compliance: For high-volume ingestion, subscribed to compliance streams to track post edits/deletions

Resources

• Comprehensive page listing: https://docs.x.com/llms.txt — Full navigation of all documentation pages
• Getting started: https://docs.x.com/x-api/introduction — Overview and quick start
• Make your first request: https://docs.x.com/make-your-first-request — Step-by-step guide with cURL examples
• Authentication overview: https://docs.x.com/fundamentals/authentication/overview — All auth methods explained
• Rate limits reference: https://docs.x.com/x-api/fundamentals/rate-limits — Per-endpoint limits and handling
• Search operators: https://docs.x.com/x-api/posts/search/integrate/build-a-query — Complete query syntax guide
• Official SDKs: https://docs.x.com/tools-and-libraries — Python and TypeScript SDK documentation

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