Sign in

v11

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-0112893437.0 KB
X Write

Create tweet

post/x/tweets

Headers

Idempotency-Keystring required

Generate one unique value for each intended write. Reuse it only when retrying the exact same account, action, target, and payload. A reused key returns the original action. Reusing it with different input returns 409. Replay protection remains active for at least 90 days.

Request body

accountstring required

X account (@username or account ID)

textstring

Tweet text (optional when media is provided)

reply_to_tweet_idstring
community_idstring
is_note_tweetboolean
mediastring[]

Array of public media URLs to attach. Supports up to 4 images or exactly 1 MP4 video up to 100 MB. Each URL must be publicly reachable. Attached media adds 2 credits per started MB across all files.

Example request

{
  "account": "@elonmusk",
  "text": "Just launched our new feature!",
  "reply_to_tweet_id": "1234567890",
  "community_id": "1500000000000000000",
  "media": [
    "https://example.com/video.mp4"
  ]
}

Response

Write reached a terminal state.

object'x_write_action' required
idstring required
writeActionIdstring required
action'create_tweet' | 'delete_tweet' | 'like' | 'unlike' | 'retweet' | 'unretweet' | 'follow' | 'unfollow' | 'remove_follower' | 'send_dm' | 'upload_media' | 'update_profile' | 'update_avatar' | 'update_banner' | 'create_community' | 'delete_community' | 'join_community' | 'leave_community' required
status'accepted' | 'dispatching' | 'pending_confirmation' | 'success' | 'failed' | 'expired' required
terminalboolean required
retryableboolean required

True only when a new attempt can reasonably succeed.

safeToRetryboolean required

True only when no write was dispatched and a new idempotency key may be used.

statusUrlstring required
pollAfterMsinteger nullable required
chargedboolean required
chargedCreditsstring required
targetIdstring nullable required
requestHashstring
requestIdstring
idempotentboolean
errorstring
messagestring
sendDispatchedboolean required
sendDispatchedAtstring date-time

Dispatch timestamp when the write reached execution.

createdAtstring date-time
updatedAtstring date-time
completedAtstring date-time
expiresAtstring date-time

Deadline for resolving a non-terminal write. This is not the Idempotency-Key retention deadline.

confirmedAtstring date-time
confirmationCheckedAtstring date-time
confirmationAttemptsinteger
tweetIdstring

Compatibility field for a confirmed tweet result ID.

messageIdstring

Compatibility field for a confirmed direct message ID.

mediaIdstring

Compatibility field for a confirmed media upload ID.

mediaUrlstring uri

Public media URL when the upload creates one.

communityIdstring

Compatibility field for a confirmed community ID.

communityNamestring

Confirmed community name when available.

resultIdstring

Compatibility result ID for other write actions.

mediaobject

Media count, kind, size, and billing details when used.

detailsobject

Structured recovery context for a failed write.

successboolean required

Example response

{
  "id": "12345",
  "writeActionId": "12345",
  "action": "like",
  "status": "success",
  "terminal": true,
  "statusUrl": "/api/v1/x/write-actions/12345",
  "charged": true,
  "chargedCredits": "10",
  "billing": {
    "status": "charged",
    "charged": true,
    "plannedCredits": "10",
    "chargedCredits": "10"
  },
  "request": {
    "hash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "payload": {
      "tweet_id": "9876543210"
    }
  },
  "account": {
    "id": "42",
    "username": "example"
  },
  "target": {
    "type": "tweet",
    "id": "9876543210"
  },
  "targetId": "9876543210",
  "result": {
    "type": "state_change",
    "id": "9876543210",
    "state": "liked"
  },
  "nextAction": {
    "type": "poll",
    "url": "/api/v1/x/write-actions/12345",
    "afterMs": 2000
  },
  "requestHash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "requestId": "01JZ8R7QSC9QKT0V7JX4M2A6B8",
  "error": "x_write_ambiguous",
  "message": "Invalid input. Check request fields.",
  "sendDispatched": true,
  "sendDispatchedAt": "2026-07-21T05:00:00Z",
  "createdAt": "2026-07-21T05:00:00Z",
  "updatedAt": "2026-07-21T05:00:02Z",
  "completedAt": "2026-07-21T05:00:02Z",
  "expiresAt": "2026-07-22T05:00:00Z",
  "confirmedAt": "2026-07-21T05:00:02Z",
  "confirmationCheckedAt": "2026-07-21T05:00:02Z",
  "confirmationAttempts": 1,
  "tweetId": "9876543210",
  "messageId": "1234567890",
  "mediaId": "2345678901",
  "mediaUrl": "https://media.xquik.com/example.jpg",
  "communityId": "3456789012",
  "communityName": "Builders",
  "resultId": "9876543210",
  "media": {
    "count": 1,
    "kind": "image"
  },
  "details": {
    "suggestion": "Poll the action status URL."
  },
  "success": true
}