x

X API Skill

Product summary

The X API provides programmatic access to X's public conversation through modern REST endpoints. Use it to search posts, retrieve user data, publish content, manage relationships, access trends, and stream real-time data. The API uses pay-per-usage pricing with no commitments. Key endpoints live at https://api.x.com/2/. Authentication uses OAuth 1.0a (user context), OAuth 2.0 (app-only or user context), or Bearer tokens. Official SDKs exist for Python (xdk) and TypeScript (@xdevplatform/xdk). Primary documentation: https://docs.x.com/x-api/introduction

When to use

Reach for this skill when:

• Searching or retrieving posts: Full-archive search (back to 2006), recent search (7 days), filtered stream (real-time), post lookup by ID
• User operations: Look up users by ID or username, search users, manage follows/followers, blocks, mutes
• Publishing content: Create posts, delete posts, reply, quote posts, manage media attachments
• Timelines: Get user's posts, mentions, reverse-chronological timeline
• Lists & spaces: Create/manage lists, add members, search spaces, get space details
• Direct messages: Send/receive DMs, manage conversations
• Media: Upload images, videos, GIFs; create metadata and subtitles
• Real-time data: Filtered stream with rules, volume streams (enterprise), webhooks, activity subscriptions
• Analytics: Post metrics, engagement data (enterprise)
• Authentication issues: Bearer token generation, OAuth flow troubleshooting, rate limit handling
• Error debugging: 401/403/429 responses, partial errors, malformed requests

Quick reference

Authentication methods

Essential endpoints

Common query parameters

Rate limit headers (in every response)

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

Check x-rate-limit-remaining before making requests. When you hit a limit (429), wait until x-rate-limit-reset (Unix timestamp).

Decision guidance

When to use search vs. timeline endpoints

When to use OAuth 1.0a vs. OAuth 2.0

When to use fields vs. expansions

Workflow

Typical task: Search posts and retrieve author details

1. Construct the query: Use search operators (from:, lang:, has:media, etc.) to build your query string.
2. Make the search request: Call GET /2/tweets/search/recent or /all with query, expansions=author_id, and tweet.fields=created_at,public_metrics.
3. Parse the response: Extract posts from data[], author IDs from includes.users[]. Check meta.next_token for pagination.
4. Handle pagination: If meta.next_token exists and you need more results, repeat step 2 with pagination_token=<next_token>.
5. Verify results: Confirm post count matches expectations; check for partial errors in errors[] array.

Typical task: Create and publish a post

1. Prepare media (optional): If attaching images/video, upload via POST /2/media/upload or chunked upload endpoints. Capture media_id.
2. Build post payload: Create JSON with text (required), media.media_ids (if attaching), reply_settings, etc.
3. Send POST request: Call POST /2/tweets with Bearer token or OAuth 1.0a user context.
4. Capture post ID: Extract data.id from response for future reference (delete, reply, etc.).
5. Verify: Check data.text matches input; confirm no errors in response.

Typical task: Set up filtered stream for real-time monitoring

1. Add stream rules: POST to /2/tweets/search/stream/rules with rule objects (value, optional tag). Max 1,000 rules.
2. Verify rules: GET /2/tweets/search/stream/rules to confirm rules are active.
3. Connect to stream: Open persistent GET connection to /2/tweets/search/stream with tweet.fields and expansions.
4. Consume messages: Parse JSON objects as they arrive; each contains data (post), matching_rules, and includes.
5. Handle disconnections: Implement exponential backoff; reconnect automatically. Check recovery endpoints if needed.

Common gotchas

• Bearer token vs. user context: Bearer tokens (app-only) cannot access private metrics or perform user actions. Use OAuth for those.
• Missing fields by default: Endpoints return minimal fields. Always specify tweet.fields and user.fields to get data you need.
• Expansions without fields: expansions=author_id includes the author object, but you still need user.fields=username to get username. Expansions alone return only IDs.
• Pagination token format: Use pagination_token parameter (not next_token). The token is base32hex-encoded; don't modify it.
• Rate limits reset per endpoint: Each endpoint has separate limits. Hitting one limit doesn't affect others.
• 429 errors require waiting: Don't retry immediately. Check x-rate-limit-reset header and wait until that Unix timestamp.
• Post creation limits: 100 posts per 15 minutes (user context), 10,000 per 24 hours (app-only). Exceeding triggers 429.
• Filtered stream rules are persistent: Rules survive disconnections. Delete old rules before adding new ones to avoid hitting the 1,000-rule cap.
• Protected accounts: Posts from protected accounts are only visible if you're authorized. Unauthenticated requests return 403.
• Deleted posts return 404: Don't assume a post exists; handle 404 gracefully.
• Partial errors in 200 responses: Check the errors[] array even in successful (200) responses when requesting multiple resources.
• Character counting: Use the twitter-text library to count characters correctly (URLs, emoji, etc.). Don't rely on string length.
• Media upload duration limits: Video duration depends on the posting account's X Premium status (20 min default, 125 min for Premium). Uploads that exceed limits fail at post creation.

Verification checklist

Before submitting work with the X API:

• Authentication: Confirm Bearer token or OAuth credentials are valid and not expired.
• Endpoint correctness: Verify endpoint path, HTTP method (GET/POST/DELETE), and required parameters.
• Fields and expansions: Confirm you're requesting all needed fields; check that expansions are paired with field parameters.
• Rate limits: Check x-rate-limit-remaining in response headers; implement backoff for 429s.
• Error handling: Parse both data and errors arrays; handle partial failures gracefully.
• Pagination: If results are paginated, verify meta.next_token logic and loop termination.
• Response parsing: Confirm JSON structure matches endpoint documentation; test with sample data.
• Credentials security: Never log or expose Bearer tokens, API keys, or OAuth secrets.
• Query syntax: For search, validate query operators (e.g., from:, lang:, has:media) are correct.
• Media attachments: If posting with media, confirm media_id from upload step is included in post payload.

Resources

Comprehensive navigation: https://docs.x.com/llms.txt — Feed this to your AI tool for full page-by-page documentation.

Critical pages:

• Make Your First Request — Quickstart with cURL examples
• Authentication Overview — Choose auth method, generate tokens
• Response Codes & Errors — Troubleshoot 401, 403, 429, and other errors

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