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.
| Field | Type | Description |
|---|---|---|
| communityId | string | The ID of the Twitter Community to post into |
| shareWithFollowers | boolean | Also share the Community post with your followers (default false) |
Source table preserved; shareWithFollowers default false.
| Field | Type | Required | Values and constraints | Description |
|---|---|---|---|---|
| communityId | string | No | — | Community ID to publish this post into. |
| shareWithFollowers | boolean | No | — | When posting to a Community, also share the post with followers. |
| replyToTweetId | string | No | — | Tweet ID to reply to. |
| replySettings | string | No | following, mentionedUsers, subscribers, verified | — |
| threadItems | object[] | No | — | Additional tweets to chain as a thread. The root tweet uses post.content. |
| threadItems[].content | string | Yes, in each threadItems[] item | — | Text of this thread tweet (max 280 chars) |
| threadItems[].mediaItems | object[] | No | — | — |
| threadItems[].mediaItems[].type | string | Yes, in each threadItems[].mediaItems[] item | image, video, gif, document | — |
| threadItems[].mediaItems[].url | string | Yes, in each threadItems[].mediaItems[] item | Format: uri | Publicly accessible URL for the media file. The provider must be able to fetch it without authentication. |
| threadItems[].mediaItems[].altText | string | No | Length: 1-1000 | Accessibility description for an image. Supported platforms forward it when publishing images; unsupported platforms and non-image media ignore it. |
| threadItems[].mediaItems[].thumbnail | string | No | Format: uri | Thumbnail image URL for Facebook videos and YouTube regular videos (not Shorts). YouTube accepts JPEG, PNG, or GIF, max 2 MB, min 640 px wide. |
| longPost | boolean | No | — | 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. |
| poll | object | No | — | Cannot be combined with media or threadItems. |
| poll.options | string[] | Yes, when poll is provided | Items: 2-4 | 2-4 poll options. |
| poll.durationMinutes | number | Yes, when poll is provided | Range: 5-10080 | Poll 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.
| Limit | Value |
|---|---|
| Character limit | 280 per tweet |
| Images per tweet | 4 |
| Videos per tweet | 1 |
| Thread length | No hard limit |
| Poll options | 2-4 |
Source limits preserved.
| Action | Credits | Notes |
|---|---|---|
| Post on X (no URL) | 5 | Text, image, video, GIF, poll, thread without links |
| Post on X with a URL | 50 | Body contains http:// or https:// |
| Post on any other platform | 1 | Instagram, LinkedIn, TikTok, YouTube, Pinterest, Facebook, Threads, Bluesky |
| List replies (X) | 1 | X recent search, roughly the last 7 days |
| Create reply (X, no URL) | 5 | A reply is a tweet, so it is priced the same |
| Create reply (X with URL) | 50 | Reply text contains http:// or https:// |
| Delete reply (X) | 3 | Deletes your own reply tweet |
| Hide reply (X) | 2 | Needs the tweet.moderate.write scope (reconnect if connected earlier) |
| Analytics request | 1 | One credit per call, regardless of how many posts come back |
Source pricing preserved exactly; no free-offer or credential claims included.
| X API operation | X's rate | Why it matters |
|---|---|---|
| Content: Create | $0.015 per request | Plain tweet, no link |
| Content: Create (with URL) | $0.200 per request | Any http(s):// in the body, ~13x the plain rate |
| Posts: Read | $0.005 per resource | Analytics lookups, post fetches |
Source X rate table preserved; reference is the official X pricing page in official_references.
curl {{API_BASE_URL}}/v1/connect/twitter \
-H "x-access-key: YOUR_API_KEY"{
"url": "https://twitter.com/i/oauth2/authorize?..."
}curl {{API_BASE_URL}}/v1/connect/integrations \
-H "x-access-key: YOUR_API_KEY"{
"success": true,
"status": "published",
"postId": "post_xyz789",
"platforms": [
{
"platform": "twitter",
"success": true,
"platformPostUrl": "https://twitter.com/you/status/123456"
}
]
}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
}'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
}'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
}'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
}'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
}'curl "{{API_BASE_URL}}/v1/comments?platform=twitter&accountId=abc123&postId=1234567890" \
-H "x-access-key: YOUR_API_KEY"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."
}'curl -X DELETE "{{API_BASE_URL}}/v1/comments/1234567890?platform=twitter&accountId=abc123" \
-H "x-access-key: YOUR_API_KEY"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
}'{
"content": "A short example update.",
"platforms": [
{
"platform": "twitter",
"accountId": "YOUR_ACCOUNT_ID",
"platformSpecificData": {
"longPost": true
}
}
]
}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
}'