PostEverywhere X (Twitter) API Guide

PostEverywhere API reference for X (Twitter): request fields, reply permissions, alt text, polls, threads and auto first comments.

Publish tweets, image posts, video posts, and multi-tweet threads to X (formerly Twitter). PostEverywhere handles media uploads, reply settings, and thread composition through a single API call. For a general overview of all supported platforms, see the Introduction.

Connect your X (Twitter) account to PostEverywhere

Connect X (Twitter) from the dashboard with OAuth, or headlessly from code: mint a connect link and hand it to the account owner - no dashboard session needed. Both flows are covered in Connecting Accounts.

What you can post to X (Twitter)

Content Type	Media Required	Description
Text post	None	Standard tweet, up to 280 characters (25,000 on X Premium).
Image post	Image(s)	Tweet with up to 4 attached images.
Video post	Video (MP4)	Tweet with a single video attachment.
Thread	Optional	Multi-tweet thread using the `thread_posts` parameter.
Poll	None (media not allowed)	Tweet with 2 to 4 poll options. See Adding a poll.
X Article	Optional (one image, used as the cover)	Long-form article with a title, set with `settings.post_type: "article"`. Requires X Premium on the connected account.

X (Twitter)-specific options in the API

Use the platform_content.x object to customise your tweet:

{
  "platform_content": {
    "x": {
      "content": "Tweet text (max 280 chars)",
      "settings": {
        "replySettings": "everyone",
        "mediaAltText": "Image description for accessibility",
        "firstComment": "Reply text posted as first reply"
      }
    }
  }
}

Settings Reference

Setting	Type	Default	Description
`content`	string	N/A	Override the default text. Max 280 characters on accounts without X Premium, 25,000 with it (X counts each link as 23 and each emoji as 2). Longer is refused with `400 content_too_long`.
`settings.replySettings`	string	`"everyone"`	Who can reply to this tweet. See values below. `reply_settings` is also accepted.
`settings.mediaAltText`	string	N/A	Accessibility description for attached images. Max 1,000 characters. `media_alt_text` is also accepted.
`settings.firstComment`	string	N/A	Text posted as a reply to your tweet immediately after publishing. X is the only platform where the API posts a first comment today.
`settings.pollEnabled`	boolean	`false`	Set to `true` to add a poll. See Adding a poll.
`settings.pollOptions`	array	N/A	2 to 4 options, each up to 25 characters. Strings or `{ "text": "..." }` objects.
`settings.pollDuration`	integer	`1440`	How long the poll runs, in minutes: 5 to 10,080 (7 days).
`settings.post_type`	string	N/A	Set to `"article"` to publish an X Article. See Publishing an X Article.
`settings.title`	string	N/A	Article title, up to 100 characters. Articles only.
`settings.made_with_ai`	boolean	`false`	Adds X's "Made with AI" disclosure. Posts and threads (applies to the first post of a thread); not available on articles.
`settings.paid_partnership`	boolean	`false`	Adds X's "Paid partnership" disclosure. Posts and threads; not available on articles.
`settings.community_id`	string	N/A	Numeric ID of an X Community to post into. The account must be a member. Posts and threads.

Reply Settings

Value	Description
`everyone`	Anyone can reply.
`following`	Only accounts you follow can reply.
`mentionedUsers`	Only users mentioned in the tweet can reply.

Publish to X (Twitter): a working request

Schedule a Tweet with an Image

curl -X POST https://app.posteverywhere.ai/api/v1/posts \
  -H "Authorization: Bearer $POSTEVERYWHERE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Default text for other platforms",
    "account_ids": [2270],
    "media_ids": ["b8c9d0e1-f2a3-4567-8901-bcdef0123456"],
    "scheduled_for": "2026-04-15T13:00:00Z",
    "timezone": "America/New_York",
    "platform_content": {
      "x": {
        "content": "We just shipped something big.\n\nDetails in the thread below 👇",
        "settings": {
          "replySettings": "everyone",
          "mediaAltText": "Screenshot of the new dashboard feature showing real-time analytics"
        }
      }
    }
  }'

Schedule a Tweet with a First Reply

curl -X POST https://app.posteverywhere.ai/api/v1/posts \
  -H "Authorization: Bearer $POSTEVERYWHERE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Launching our new API today.",
    "account_ids": [2270],
    "platform_content": {
      "x": {
        "content": "We just launched our public API.\n\nSchedule posts to all top platforms from one endpoint.\n\n7-day trial, cancel anytime.",
        "settings": {
          "firstComment": "Full docs: https://posteverywhere.ai/docs\n\nNode.js SDK: npm install @posteverywhere/sdk"
        }
      }
    }
  }'

Publishing a thread to X (Twitter)

To create a multi-tweet thread, use the thread_posts array at the top level of your request (not inside platform_content). content is the first tweet, and each string in thread_posts becomes the next tweet in the thread, replying to the one before it. You can add up to 25 parts after content. Every part is checked against the account's text limit before anything is posted, so a part that is too long returns 400 invalid_thread_posts instead of failing halfway through. Threads cannot be combined with an X Article.

curl -X POST https://app.posteverywhere.ai/api/v1/posts \
  -H "Authorization: Bearer $POSTEVERYWHERE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Here are 5 things I learned this quarter:",
    "account_ids": [2270],
    "scheduled_for": "2026-04-15T15:00:00Z",
    "timezone": "UTC",
    "thread_posts": [
      "1/ Focus on one metric at a time. Spreading attention across 10 dashboards means you optimize nothing.",
      "2/ Ship weekly. Monthly releases create anxiety. Weekly releases create momentum.",
      "3/ Talk to customers before writing code. 80% of our best features came from support tickets.",
      "4/ Delete more than you add. We removed 3 features this quarter and NPS went up.",
      "5/ Document decisions, not just outcomes. Future-you will thank present-you.\n\nWhat would you add to this list?"
    ]
  }'

Adding a poll to a tweet

Set settings.pollEnabled to true with 2 to 4 pollOptions (each up to 25 characters) and a pollDuration in minutes, from 5 to 10,080 (7 days). If pollDuration is left out, the poll runs for 24 hours.

{
  "platform_content": {
    "x": {
      "content": "Which day do you post most?",
      "settings": {
        "pollEnabled": true,
        "pollOptions": ["Monday", "Wednesday", "Friday", "Weekend"],
        "pollDuration": 1440
      }
    }
  }
}

A poll cannot go with images, a video or a quoted post. PostEverywhere checks the poll when the post is created or edited: a poll outside these limits, or one with media or a quote, is refused with 400 x_poll_invalid and a plain message ("X polls need 2 to 4 options of up to 25 characters, and a duration between 5 minutes and 7 days." or "X polls cannot have images, videos or a quoted post."). It is never posted without the poll.

Publishing an X Article

X Articles are X's native long-form format: a title, a formatted body and a cover image. Set settings.post_type to "article" in platform_content.x. Articles schedule like any other post, through the REST API, the SDK or the MCP server.

{
  "content": "Article body",
  "account_ids": [123],
  "media_ids": ["<cover image media id>"],
  "scheduled_for": "2026-10-01T09:00:00Z",
  "platform_content": {
    "x": {
      "content": "## Why we rebuilt onboarding\n\nThree things changed...",
      "settings": {
        "post_type": "article",
        "title": "What 38 seconds taught us about onboarding"
      }
    }
  }
}

Body: platform_content.x.content, or the top-level content if there is no X override. Up to 25,000 characters. Headings, bullet and numbered lists, quotes, bold, italic and links are supported.
Title: settings.title, up to 100 characters. If it is omitted, a leading # Heading line in the body becomes the title.
Cover: there is no separate field. The first attached image becomes the cover, and 2000x800 pixels (5:2) looks best. One image only; video is not allowed in an article.
Requirements: the connected X account needs X Premium, which is X's rule.
Fair-use limit: 2 published articles per X account in any rolling 24 hours, checked when the article publishes. Failed attempts do not count. Over the limit, the post fails with X_ARTICLE_DAILY_LIMIT.
X's own limit: X allows 10 article actions per X account per 24 hours. If it is reached, the post is held rather than failed and publishes automatically 5 minutes after X's reset (the message gives the time in UTC). While held it shows as publishing and cannot be edited, but it can be deleted. It fails with X_ARTICLE_X_DAILY_LIMIT only if X still refuses after three holds.
Single posts only: create articles with POST /v1/posts or the MCP create_post and schedule_post tools. Bulk create cannot carry platform_content, so it cannot create articles.
Errors: validation problems (non-X accounts, a missing or long title, an empty body) return HTTP 400 x_article_invalid with every problem listed in details.errors[]. A non-Premium account fails at publish time with a message saying so.
Not yet supported inside articles: inline images, embedded posts, code blocks, tables and dividers.

Labels and X Communities

Two disclosure labels and community posting work on standard posts and threads, scheduled or immediate. On a thread they apply to the first post. They are not available on X Articles.

{
  "platform_content": {
    "x": {
      "content": "Our new template pack is out.",
      "settings": {
        "made_with_ai": true,
        "paid_partnership": false,
        "community_id": "1234567890123456789"
      }
    }
  }
}

made_with_ai and paid_partnership add X's own disclosure to the published post.
community_id posts into an X Community. The connected account must already be a member.

X (Twitter) limits: characters, media and video

Requirement	Limit
Tweet text length	280 characters without X Premium, 25,000 with it (links count 23, emoji count 2). Longer is refused with `400 content_too_long`.
X Article body	25,000 characters
X Article title	100 characters
X Articles published	2 per X account per rolling 24 hours
Alt text length	1,000 characters
Images per tweet	Up to 4
Poll options	2 to 4, each up to 25 characters; no media or quote with a poll
Poll duration	5 minutes to 7 days
Image formats	JPEG, PNG, WebP, GIF
Image max file size	5 MB (X limit)
GIF max file size	15 MB
Video format	MP4 (H.264)
Video max file size	512 MB
Video duration	Up to 2 minutes 20 seconds
Thread length	Up to 25 parts in `thread_posts`, after `content`
X posting caps	Fixed caps enforced when a post publishes to X, independent of your plan: 100 per hour and 500 per day per organization, and 50 per 15 minutes per account. See rate limits for the API request limits.

Getting better results on X (Twitter)

Use firstComment to add links. Tweets with links get less algorithmic reach on X. Post the tweet without a link, then use firstComment to reply with the URL. Your followers still see the link, but the original tweet gets better distribution.
Always add mediaAltText for images. Alt text improves accessibility and can boost search visibility. X supports up to 1,000 characters per image: use it to describe what is in the image for screen reader users.
Mind X's posting caps. Publishing to X is capped at 500 posts per day and 100 per hour per organization; the caps are fixed, not plan-based. Spread scheduled posts across the day to stay under them.

Common questions about posting to X (Twitter)

Can I publish an X Article through the API?

Yes. Set settings.post_type to "article" in platform_content.x, give it a title of up to 100 characters, and attach one image to use as the cover. The connected account needs X Premium, and each X account can publish 2 articles in any rolling 24 hours.

Can I add the "Made with AI" or "Paid partnership" label?

Yes, on posts and threads. Set settings.made_with_ai or settings.paid_partnership to true and X shows the disclosure on the published post. The labels are not available on X Articles.

How do I create a Twitter thread via the API?

Use the thread_posts array (threadPosts is accepted as an alias) at the top level of your Create Post request. Each string in the array becomes a separate tweet in the thread. The main content field is the first tweet, and thread_posts contains the replies, up to 25 of them.

Can I attach multiple images to a single tweet?

Yes. Include up to 4 media_ids in your post request. Upload each image first using the Upload Media endpoint, then pass all returned media IDs in the media_ids array. Note that you cannot mix images and video in a single tweet.

How do I restrict who can reply to my tweet?

Set settings.replySettings in the platform_content.x object. Options are "everyone" (default), "following" (only accounts you follow), or "mentionedUsers" (only accounts mentioned in the tweet).

What are the daily posting limits on X?

Publishing to X has fixed caps that do not depend on your plan: 100 posts per hour and 500 per day per organization, and 50 per 15 minutes per account. Spread scheduled posts across the day to stay under them. See Rate Limits for the API request limits.

Can I edit a tweet after it's published?

X allows post owners to edit tweets in their own UI for a limited window (the "Edit tweet" feature on Premium), but their API does not expose tweet editing to third-party tools. PATCH /v1/posts/:id only accepts posts in scheduled or draft status: once a tweet publishes, our API returns 400 invalid_post_status. To change a tweet's text, delete it (in X) and recreate via the API.

Other platforms you can publish to

Threads -- short-form text posts with a similar conversational style
LinkedIn -- professional text posts and thought leadership
Facebook -- cross-post announcements and link shares

Building on the API?See plansAPI overviewConnect an AI agent