Create tweet

10 credits text-only · attached media adds 2 credits per started MB across all files

Create a tweet or reply from one connected X account. Put public HTTPS image URLs or one public MP4 URL in media; when POST /x/media hosts a local file, use the returned mediaUrl here, not mediaId. Do not send media_ids to this endpoint. Store tweetId on 200 Success, or store writeActionId and poll when the response is 202 x_write_unconfirmed.

curl -X POST https://xquik.com/api/v1/x/tweets \
  -H "x-api-key: xq_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "elonmusk",
    "text": "Hello from Xquik!"
  }' | jq

Post with public media URLs

Use media 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.

curl -X POST https://xquik.com/api/v1/x/tweets \
  -H "x-api-key: xq_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "brand_account",
    "text": "Launch notes are live.",
    "media": ["https://cdn.example.com/product-screenshot.png"]
  }' | jq

Store tweetId, charged, and chargedCredits on a 200 Success response. If the API returns 202 x_write_unconfirmed, store writeActionId, poll Get Write Action Status, and do not retry-send the same body. Keep reply_to_tweet_id and media in your downstream record.

Headers

x-api-key

string

required

Your API key. Session cookie authentication is also supported.

Content-Type

string

required

Must be application/json.

Body

account

string

required

X username or account ID identifying which connected X account to post as. The @ prefix is automatically stripped if included.

text

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.

reply_to_tweet_id

string

Tweet ID to reply to. When set, the new tweet is posted as a reply in that tweet’s thread.

attachment_url

string

URL to attach to the tweet as a card. Must be a valid HTTP or HTTPS URL.

community_id

string

X Community ID to post the tweet into. The connected account must be a member of the community.

is_note_tweet

boolean

Set to true to post a long-form note tweet (up to 25,000 characters). Defaults to false.

media

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

tweetId

string

ID of the newly created tweet.

success

boolean

Always true on success.

charged

boolean

Whether credits were charged for the confirmed write.

chargedCredits

string

Credits charged for this tweet. Text-only tweets cost 10 credits; attached media adds 2 credits per started MB.

writeActionId

string

Write action ID when the write was logged for later reconciliation.

{
  "tweetId": "1895432178065391234",
  "success": true,
  "charged": true,
  "chargedCredits": "12"
}

{
  "error": "x_write_unconfirmed",
  "status": "pending_confirmation",
  "writeActionId": "42",
  "charged": false,
  "chargedCredits": "0",
  "retryable": false,
  "message": "Action may have completed, but confirmation is still pending."
}

The write was dispatched but final confirmation is still pending. writeActionId identifies the action to poll with Get write action status. charged is false and chargedCredits is "0" while confirmation is pending, and retryable is false; do not retry-send the same tweet blindly.

{ "error": "invalid_input", "message": "Either text or media is required" }

Missing text and media, invalid account format, or other validation failure.

{
  "error": "unsupported_field",
  "message": "media_ids is not supported on POST /x/tweets. Pass media as an array of public image or MP4 video URLs.",
  "retryable": false,
  "charged": false,
  "chargedCredits": "0",
  "details": {
    "action": "create_tweet",
    "suggestion": "Use the media field with public URLs instead of media_ids. Send up to 4 images or exactly 1 MP4 video up to 100 MB."
  }
}

The request body contains a field the endpoint does not accept (for example media_ids).

{ "error": "unauthenticated", "message": "Missing or invalid API key" }

Missing or invalid API key.

{ "error": "no_subscription", "message": "No active subscription" }

An active subscription is required. Subscribe from the dashboard.

{ "error": "insufficient_credits", "message": "Insufficient credits" }

Insufficient credits for this operation. Top up your credit balance from the dashboard.

{ "error": "account_needs_reauth" }

The connected X account failed a recent login attempt and needs to be reconnected. Reconnect it from the dashboard.

{ "error": "account_restricted" }

The connected X account is locked, suspended, recovering, or temporarily restricted. Resolve the restriction on X before retrying.

{ "error": "x_content_too_long", "message": "..." }

X rejected the write. Possible codes: x_content_too_long, x_duplicate_action, x_account_suspended, x_account_protected, x_target_not_found, x_account_feature_required, x_rejected. See error handling for details.

{ "error": "rate_limit_exceeded", "retryAfter": 60 }

The request hit an Xquik tier limit, or X throttled the write. Possible codes: rate_limit_exceeded, x_rate_limited, or x_daily_limit. Respect the Retry-After header when present.

{ "error": "x_transient_error", "message": "..." }

A transient write service issue occurred. Safe to retry with exponential backoff.

{ "error": "x_write_failed", "message": "Failed to post tweet" }

The tweet could not be posted. The connected account may be suspended, rate-limited, or the content may violate platform policies. Try again later.

Store the post handoff

Store a compact record after every tweet or reply so queues, CRMs, support tools, and agents can reconcile the write without scraping the timeline.

Posted
Pending Confirmation

{
  "status": "posted",
  "tweet_id": "1895432178065391234",
  "account": "brand_account",
  "reply_to_tweet_id": "1893456789012345678",
  "media": ["https://cdn.example.com/release-card.png"],
  "charged": true,
  "charged_credits": "12",
  "media_credits": "2"
}

Copy tweetId from the response into tweet_id. Keep reply_to_tweet_id when the post is a reply, and store chargedCredits as charged_credits. Store the public media URLs you sent in media. If you uploaded first, store the returned mediaUrl, not the upload mediaId.

{
  "status": "pending_confirmation",
  "write_action_id": "42",
  "account": "brand_account",
  "reply_to_tweet_id": "1893456789012345678",
  "charged": false,
  "charged_credits": "0",
  "retryable": false,
  "poll": "GET /x/write-actions/{id}"
}

Store writeActionId as write_action_id, poll Get Write Action Status, and do not retry-send the same body while status is pending_confirmation. If polling later returns status: "success" with tweetId, update the same record to posted.

Next steps: Upload Media to get a mediaUrl for a local file, Get Write Action Status to poll pending confirmations, Delete Tweet to remove a posted tweet, Like or Retweet to engage with tweets.

Documentation Index

​Post with public media URLs

​Headers

​Body

​Response

​Store the post handoff

Post with public media URLs

Headers

Body

Response

Store the post handoff