> ## Documentation Index > Fetch the complete documentation index at: https://docs.social-api.ai/llms.txt > Use this file to discover all available pages before exploring further. # X / Twitter > Connect and interact with X (Twitter) accounts via the X API v2. Available **BYOK connector** - Twitter requires you to bring your own Twitter Developer app. Setup takes about ten minutes. See [Platform credentials](/guides/platform-credentials) for why Twitter is the only platform that works this way. ## At a glance | Field | Value | | ------------- | ------------------------------------------------------------ | | Platform slug | `twitter` | | Auth type | OAuth 2.0 (BYOK) | | API | X API v2 | | Best for | Real-time conversation: tweets, replies, DMs, mentions on X. | ## Setup Before you can connect any Twitter account, register a Twitter Developer app and paste your Client ID and Client Secret into your SocialAPI dashboard. See the [Twitter BYOK setup guide](/connectors/twitter-byok) for the ten-minute walkthrough. ## Capabilities | Feature | Supported | Notes | | ------------------------------ | --------- | -------------------------------------------------------------------- | | List posts | Yes | Returns user tweets | | Comments | Yes | Replies to a specific tweet | | Reply to comment | Yes | | | Comment replies (thread) | Yes | | | Moderate comment (hide/delete) | Yes | Hide a reply, or delete your own reply | | Like comment | No | X removed like/unlike writes from self-serve tiers (Enterprise only) | | Private reply | No | Not applicable | | DMs | Yes | Direct Messages via X API v2 | | Send DM | Yes | | | Reviews | No | Not applicable | | Mentions | Yes | Tweets mentioning the authenticated user | | Create post | Yes | Text tweets only (no media upload today) | | Update post | No | Edits are gated to Enterprise; not available to self-serve apps | | Delete post | Yes | | ## Connecting ```bash theme={null} curl -X POST https://api.social-api.ai/v1/accounts/connect \ -H "Authorization: Bearer $SOCAPI_KEY" \ -H "Content-Type: application/json" \ -d '{ "platform": "twitter", "redirect_uri": "https://app.example.com/oauth/callback", "state": "session_abc123" }' ``` Response: ```json theme={null} { "auth_url": "https://x.com/i/oauth2/authorize?client_id=...&state=...", "state": "4a8f2c1e9b3d7f06a5c2e8b4d1f3a7e2" } ``` Redirect your user to `auth_url`. After they authorize, SocialAPI exchanges the code with X and redirects the user to your `redirect_uri` with the connection result. See [OAuth flows](/guides/oauth#step-3-receive-the-result-at-your-redirect_uri) for the redirect parameters. ## Reading samples ### List posts ```bash theme={null} curl "https://api.social-api.ai/v1/posts?account_ids={id}&limit=10" \ -H "Authorization: Bearer $SOCAPI_KEY" ``` ### List comments on a post ```bash theme={null} curl "https://api.social-api.ai/v1/accounts/{id}/posts/{pid}/comments?limit=10" \ -H "Authorization: Bearer $SOCAPI_KEY" ``` ### List DMs ```bash theme={null} curl "https://api.social-api.ai/v1/inbox/conversations?account_id={id}" \ -H "Authorization: Bearer $SOCAPI_KEY" ``` ### List mentions ```bash theme={null} curl "https://api.social-api.ai/v1/accounts/{id}/mentions?limit=10" \ -H "Authorization: Bearer $SOCAPI_KEY" ``` ## Publishing Create a tweet with optional X-specific settings: ```bash theme={null} curl -X POST https://api.social-api.ai/v1/posts \ -H "Authorization: Bearer $SOCAPI_KEY" \ -H "Content-Type: application/json" \ -d '{ "text": "Hello from SocialAPI!", "targets": [ { "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "platform_data": { "reply_settings": "following" } } ] }' ``` ### Platform data fields Pass these inside the target's `platform_data` when creating a post. All fields are optional. | Field | Type | Description | | ------------------------------ | --------------- | ----------------------------------------------------------------------------------------------------- | | `reply_settings` | string | Who can reply to this tweet. One of `"following"`, `"mentionedUsers"`, `"subscribers"`, `"verified"`. | | `geo_place_id` | string | Attach a location by X place ID. | | `community_id` | string | Post into an X Community. | | `for_super_followers_only` | boolean | Restrict the post to Super Followers. | | `nullcast` | boolean | Promoted-only post (does not appear in the timeline). | | `made_with_ai` | boolean | Flag the post as AI-generated content. | | `paid_partnership` | boolean | Disclose branded content. | | `in_reply_to_tweet_id` | string | Publish the post as a reply to an existing tweet. | | `auto_populate_reply_metadata` | boolean | Auto-include @mentions from the tweet being replied to. Only meaningful with `in_reply_to_tweet_id`. | | `exclude_reply_user_ids` | array of string | User IDs to exclude from auto-populated @mentions. Only meaningful with `in_reply_to_tweet_id`. | | `thread` | array of string | Continuation tweets chained after the root, posted in order. See [Threads](#threads). | Invalid values (a bad `reply_settings` enum, a wrong field type, an empty or over-length thread entry) are rejected by `POST /v1/posts/validate` and by create with a validation error, before any tweet is published. Unrecognized `platform_data` keys are ignored with a warning. ### Threads Set `thread` to an array of strings to publish a chained thread. The target's `text` is the root tweet (tweet 1) and each `thread` entry is posted as a reply to the one before it. Continuation tweets are text-only: the `platform_data` settings above apply to the root tweet only. ```json theme={null} { "text": "1/ A thread about our launch.", "targets": [ { "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "platform_data": { "thread": [ "2/ First, the backstory.", "3/ And here is what is next." ] } } ] } ``` The published post's ID is the root tweet's ID. Continuation tweet IDs are returned in the post metadata under `thread_post_ids`. If a continuation tweet fails partway through, publishing stops: the tweets posted so far stay live (X has no batch rollback), the metadata records `thread_failed_at_index`, and the request returns an error. Each tweet in a thread is a separate billable X write. Posts containing a URL cost significantly more per X's pay-per-use pricing, so keep links minimal. ## Limitations and gotchas * **Text-only posts.** Posts carry text plus the `platform_data` settings above, and can be chained into threads. Media upload is not implemented yet, so image and video attachments are ignored. Polls and quote tweets are also unsupported. * **No post editing.** X's edit capability (`edit_options.previous_post_id`) is gated to Enterprise on the pay-per-use tier, so it is not available to self-serve BYOK apps. `UpdatePost` returns `501`. Delete and re-create if needed. * **No webhook handler.** X does not push real-time events via this integration. Posts and comments are fetched on demand. * **Comment moderation.** Hide toggles reply visibility. Delete removes your own replies. Liking is not available: X removed like/unlike writes from all self-serve tiers (April 2026), so `can_like` is `false`. * **Token refresh.** X OAuth 2.0 tokens expire after two hours. SocialAPI proactively refreshes the access token when fewer than 5 minutes remain on the current token, so most requests complete without interruption. If you receive `401` with `code: "invalid_token"`, the refresh itself failed (for example, the refresh token was revoked): reconnect the account. * **Required scopes.** Your X Developer App must have the appropriate OAuth 2.0 scopes for reading tweets, posting, DMs, and user lookup. ## Permissions Because Twitter is BYOK, you control the OAuth scopes on your own Twitter Developer app. We recommend enabling these scopes for full functionality: read and write tweets, read and send DMs, user lookup. See the [Twitter BYOK setup guide](/connectors/twitter-byok) for the exact scope list to select in the X Developer Portal. ## Related * [Twitter BYOK setup guide](/connectors/twitter-byok) * [Platform credentials](/guides/platform-credentials) * [OAuth flows](/guides/oauth) * [Errors](/guides/errors) * [Interaction IDs](/guides/interaction-ids)