Skip to content

Twitter/X Posting API

Use this Twitter/X Posting API guide to send individual posts, chained threads, polls, media attachments, Community posts, and reply tweets from one endpoint. You will connect an account, look up its identifier, shape each request with the documented fields, and check character, media, poll, permission, and credit rules before sending.

Overview

One endpoint handles the publishing work described here for Twitter/X, covering ordinary text, threads, polls, and media-rich posts. Authentication, token renewal, and throttling are handled behind that endpoint. Credit treatment differs on this platform from the flat pattern elsewhere: X charges by request, with link-bearing posts costing roughly thirteen times a plain post, and that spread is reflected directly in credits. Budget 5 credits for an X post without a URL, 50 when the body includes one, and 1 for a post on any other platform. Multi-platform sends will therefore be dominated by the X portion. Full figures appear in the Limits and Pricing section.

Quick Start

Three steps precede a successful send. First obtain an authorization link by calling the connect endpoint with your key in the x-access-key header, then send the user to the url field from the reply; completing that flow attaches the account to your project, with Connect Accounts describing the OAuth sequence in detail. Second, call the integrations listing and locate the entry whose platform equals twitter, recording its id for use as accountId. Third, submit a post containing content, a platforms entry naming twitter and that accountId, and publishNow set to true. On success the reply carries success true, status published, a postId, and per-platform detail including platformPostUrl. The examples titled Connect a Twitter/X account, Connect response, List connected integrations, Post a tweet, and Post response show each shape.

Features

Plain text posts stop at 280 characters. Attachments travel in mediaItems: still images may be JPG, PNG, GIF, or WebP, up to four in one post; video is MP4, one per post; animated GIF counts as one. Threads are built by adding platformSpecificData.threadItems, with the opening message taken from the top-level content and each extra entry becoming the next chained post. Polls use platformSpecificData.poll, which needs options plus durationMinutes, accepts two through four choices, and must not be paired with mediaItems or threadItems. Community placement is requested through platformSpecificData.communityId, with shareWithFollowers optionally true to mirror the post to followers. A reply through the posting route sets platformSpecificData.replyToTweetId to the target post; success depends on the original author's audience setting, which may be everyone, people you follow, verified accounts, or mentioned users only, and a mismatch causes failure. Audience control for your own post is set via platformSpecificData.replySettings: leave it out for everyone, or choose following, mentionedUsers, subscribers, or verified.

Comments

Here a comment means a reply tweet, and the /v1/comments surface supports four operations: reading replies, adding one, removing your own, and hiding one under your post. Two routes create a reply tweet and charge identically, 5 credits plain or 50 with a link. Choose the posting route with replyToTweetId when a post payload is already in hand. Choose POST /v1/comments when you also need to read or hide replies, since the posting route offers neither. Reading uses postId for the parent post and draws on X recent search, spanning about seven days and needing a plan that includes search; that read costs 1 credit. Writing a reply uses postId for a top-level reply or commentId for answering a reply, needs tweet.write, and costs 5 or 50 depending on links. Removal targets your own reply through commentId and costs 3. Hiding or unhiding another person's reply under your post also uses commentId plus a hidden flag, costs 2, and needs tweet.moderate.write; accounts linked before that permission existed must reconnect, and a permission error is the signal to do so.

Long Posts and Platform-Specific Data

Posts longer than 280 characters are refused unless the linked account holds X Premium or Premium+ and you set platformSpecificData.longPost to true, which allows one post up to 25,000 characters rather than a thread. Enabling it bypasses the early length check and leaves enforcement to X; an ineligible account gets a rejection from X that is passed back to you. Because it remains one write, pricing matches a normal post and undercuts a thread. Run these checks before dispatch: length against 280 unless longPost is true on an eligible account; mediaItems totals against four images, one video, and one animated GIF; poll shape against two to four options, durationMinutes from 5 to 10080, and no media or threadItems alongside; threadItems entries against the field map; and link presence, since http:// or https:// moves the budget from 5 to 50. Twitter/X-specific settings belong inside platformSpecificData on the platform target, including Community options, as detailed in the Platform-Specific Data field map table.

Limits and Pricing

Consult the tables below for hard limits and per-action credit charges. They are the quickest way to catch an oversized post, an over-limit attachment set, or an unexpected link surcharge before you send.

Community post fields
FieldTypeDescription
communityIdstringThe ID of the Twitter Community to post into
shareWithFollowersbooleanAlso share the Community post with your followers (default false)

Source table preserved; shareWithFollowers default false.

Platform-Specific Data field map
FieldTypeRequiredValues and constraintsDescription
communityIdstringNo—Community ID to publish this post into.
shareWithFollowersbooleanNo—When posting to a Community, also share the post with followers.
replyToTweetIdstringNo—Tweet ID to reply to.
replySettingsstringNofollowing, mentionedUsers, subscribers, verified—
threadItemsobject[]No—Additional tweets to chain as a thread. The root tweet uses post.content.
threadItems[].contentstringYes, in each threadItems[] item—Text of this thread tweet (max 280 chars)
threadItems[].mediaItemsobject[]No——
threadItems[].mediaItems[].typestringYes, in each threadItems[].mediaItems[] itemimage, video, gif, document—
threadItems[].mediaItems[].urlstringYes, in each threadItems[].mediaItems[] itemFormat: uriPublicly accessible URL for the media file. The provider must be able to fetch it without authentication.
threadItems[].mediaItems[].altTextstringNoLength: 1-1000Accessibility description for an image. Supported platforms forward it when publishing images; unsupported platforms and non-image media ignore it.
threadItems[].mediaItems[].thumbnailstringNoFormat: uriThumbnail image URL for Facebook videos and YouTube regular videos (not Shorts). YouTube accepts JPEG, PNG, or GIF, max 2 MB, min 640 px wide.
longPostbooleanNo—Opt in to long posts (over 280 characters). Skips the 280-character pre-check so X can accept up to 25,000 characters for eligible Premium / Premium+ accounts. If the connected account is not eligible, X rejects the post and the error is surfaced back. No extra API cost.
pollobjectNo—Cannot be combined with media or threadItems.
poll.optionsstring[]Yes, when poll is providedItems: 2-42-4 poll options.
poll.durationMinutesnumberYes, when poll is providedRange: 5-10080Poll duration in minutes (5 min - 7 days).

Source table preserved literally. Private hold: thread example uses threadItems[].text while this table specifies threadItems[].content as required.

Limits
LimitValue
Character limit280 per tweet
Images per tweet4
Videos per tweet1
Thread lengthNo hard limit
Poll options2-4

Source limits preserved.

Pricing in credits
ActionCreditsNotes
Post on X (no URL)5Text, image, video, GIF, poll, thread without links
Post on X with a URL50Body contains http:// or https://
Post on any other platform1Instagram, LinkedIn, TikTok, YouTube, Pinterest, Facebook, Threads, Bluesky
List replies (X)1X recent search, roughly the last 7 days
Create reply (X, no URL)5A reply is a tweet, so it is priced the same
Create reply (X with URL)50Reply text contains http:// or https://
Delete reply (X)3Deletes your own reply tweet
Hide reply (X)2Needs the tweet.moderate.write scope (reconnect if connected earlier)
Analytics request1One credit per call, regardless of how many posts come back

Source pricing preserved exactly; no free-offer or credential claims included.

X API rates behind the credit split
X API operationX's rateWhy it matters
Content: Create$0.015 per requestPlain tweet, no link
Content: Create (with URL)$0.200 per requestAny http(s):// in the body, ~13x the plain rate
Posts: Read$0.005 per resourceAnalytics lookups, post fetches

Source X rate table preserved; reference is the official X pricing page in official_references.

Connect a Twitter/X account
curl {{API_BASE_URL}}/v1/connect/twitter \
  -H "x-access-key: YOUR_API_KEY"
Connect response
{
	"url": "https://twitter.com/i/oauth2/authorize?..."
}
List connected integrations
curl {{API_BASE_URL}}/v1/connect/integrations \
  -H "x-access-key: YOUR_API_KEY"
Post response
{
	"success": true,
	"status": "published",
	"postId": "post_xyz789",
	"platforms": [
		{
			"platform": "twitter",
			"success": true,
			"platformPostUrl": "https://twitter.com/you/status/123456"
		}
	]
}
Post with mediaItems
curl -X POST "{{API_BASE_URL}}/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      { "platform": "twitter", "accountId": "abc123" }
    ],
    "mediaItems": [
      { "type": "image", "url": "https://example.com/photo.jpg" }
    ],
    "publishNow": true
  }'
Post a thread with threadItems
curl -X POST "{{API_BASE_URL}}/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "1/ Here'\''s a thread about our API...",
    "platforms": [
      {
        "platform": "twitter",
        "accountId": "abc123",
        "platformSpecificData": {
          "threadItems": [
            { "text": "An example comment." },
            { "text": "An example comment." }
          ]
        }
      }
    ],
    "publishNow": true
  }'
Post a poll
curl -X POST "{{API_BASE_URL}}/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      {
        "platform": "twitter",
        "accountId": "abc123",
        "platformSpecificData": {
          "poll": {
            "options": ["Analytics", "Webhooks", "Bulk upload"],
            "durationMinutes": 1440
          }
        }
      }
    ],
    "publishNow": true
  }'
Post to a Community
curl -X POST "{{API_BASE_URL}}/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      {
        "platform": "twitter",
        "accountId": "abc123",
        "platformSpecificData": {
          "communityId": "1234567890",
          "shareWithFollowers": true
        }
      }
    ],
    "publishNow": true
  }'
Reply via replyToTweetId
curl -X POST "{{API_BASE_URL}}/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      {
        "platform": "twitter",
        "accountId": "abc123",
        "platformSpecificData": {
          "replyToTweetId": "1234567890"
        }
      }
    ],
    "publishNow": true
  }'
List replies
curl "{{API_BASE_URL}}/v1/comments?platform=twitter&accountId=abc123&postId=1234567890" \
  -H "x-access-key: YOUR_API_KEY"
Create a reply
curl -X POST "{{API_BASE_URL}}/v1/comments" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "twitter",
    "accountId": "abc123",
    "postId": "1234567890",
    "text": "An example comment."
  }'
Delete a reply
curl -X DELETE "{{API_BASE_URL}}/v1/comments/1234567890?platform=twitter&accountId=abc123" \
  -H "x-access-key: YOUR_API_KEY"
Hide a reply
curl -X PATCH "{{API_BASE_URL}}/v1/comments/1234567890" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "twitter",
    "accountId": "abc123",
    "hidden": true
  }'
Long post payload with longPost
{
	"content": "A short example update.",
	"platforms": [
		{
			"platform": "twitter",
			"accountId": "YOUR_ACCOUNT_ID",
			"platformSpecificData": {
				"longPost": true
			}
		}
	]
}
Post a tweet
curl -X POST "{{API_BASE_URL}}/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      { "platform": "twitter", "accountId": "abc123" }
    ],
    "publishNow": true
  }'