X Write
Create tweet
Post tweets and replies from a connected X account with public image URLs or 1 MP4 video URL, write-status polling, and audit handoff
POST
Create tweet
30 credits text-only · attached media adds 2 credits per started MB across all files
media; when POST /x/media hosts a local file, use the returned mediaUrl here, not mediaId. Do not send media_ids to this endpoint. Send a unique Idempotency-Key, store the durable action, and poll statusUrl while terminal is false.
Post with public media URLs
Usemedia when your image or MP4 video is already a public HTTPS URL or when Upload Media returned mediaUrl. Send up to 4 image URLs or exactly 1 MP4 video URL up to 100 MB. Do not send media_ids; that field is for DMs only. Attached media adds 2 credits per started MB across all files.
id, request.hash, billing, result, reply_to_tweet_id, and media. Poll Get Write Action Status while terminal is false. Retry only when safeToRetry is true, using a new key.
Headers
string
required
Your API key. Session cookie authentication is also supported.
string
required
Unique key for this intended write. Reuse it only for an exact network replay.
string
required
Must be
application/json.Body
string
required
X username or account ID identifying which connected X account to post as. The
@ prefix is automatically stripped if included.string
Tweet text content. Maximum 280 characters for standard tweets, or up to 25,000 characters if
is_note_tweet is true. Optional when media is provided.string
Tweet ID to reply to. When set, the new tweet is posted as a reply in that tweet’s thread.
string
X Community ID to post the tweet into. The connected account must be a member of the community.
boolean
Set to
true to post a long-form note tweet (up to 25,000 characters). Defaults to false.string[]
Array of public media URLs to attach directly. Send up to 4 JPEG, PNG, GIF, WebP, or AVIF image URLs, or exactly 1 MP4 video URL up to 100 MB. Do not mix video with other media. Use Upload Media first if you need Xquik to host a local file, then pass the returned
mediaUrl in media. Do not pass uploaded mediaId values or media_ids. Attached media adds 2 credits per started MB across all files.Response
Durable lifecycle responses
Store the
X-Request-Id response header with every action record.- Store
id,request.hash,account,target, andbilling. - Stop only when
terminalistrue. - Poll
statusUrlafterRetry-AfterorpollAfterMs. - Retry only when
safeToRetryistrue. - Use a new key only for a newly approved write.
- 200 Terminal
- 202 Active
- 400 Invalid Input
- 401 Unauthenticated
- 402 Billing Required
- 403 Account Blocked
- 409 Idempotency conflict
- 422 Write Rejected
- 429 Rate Limited
- 500 Write Failed
The action reached
success, failed, or expired. Trust terminal,
result, billing, and nextAction over the HTTP class.string
Always
x_write_action.string
Durable action ID.
string
Compatibility alias for
id.string
Exact write operation.
string
Current lifecycle status.
boolean
Whether polling can stop.
boolean
Whether a later attempt could succeed.
boolean
Whether a new attempt is safe.
string
Relative polling URL.
number | null
Recommended polling delay.
boolean
Whether billing settled as charged.
string
Settled credits charged.
object
Planned and settled billing state.
object
Stable hash and exact sanitized payload.
object
Exact connected account selected.
object | null
Exact target type and ID.
string | null
Compatibility target ID.
object | null
Confirmed result or desired state.
object | null
Required poll, retry, or verification step.
string
Stable request fingerprint.
string
Correlation ID.
boolean
Whether this response replayed an existing action.
string
Machine-readable error code.
string
Actionable status or error message.
boolean
Whether dispatch occurred.
string
ISO 8601 dispatch time.
string
ISO 8601 creation time.
string
ISO 8601 latest update time.
string
ISO 8601 terminal time.
string
Nonterminal resolution deadline.
string
ISO 8601 confirmation time.
string
ISO 8601 latest confirmation check.
number
Confirmation attempt count.
string
Confirmed tweet ID when available.
string
Confirmed direct message ID when available.
string
Confirmed media ID when available.
string
Public media URL when available.
string
Confirmed community ID when available.
string
Confirmed community name when available.
string
Compatibility result ID.
object
Media details when used.
object
Structured recovery context.
boolean
Whether status is
success.Last modified on July 21, 2026
Previous
Get write action statusPoll the durable lifecycle, result, billing, and retry state of any X write action
Next
Create tweet