Skip to main content
POST
Twitter post API for tweet & reply automation
30 credits text-only · attached media adds 2 credits per started MB across all files
Create a tweet or reply from one connected X account. This Twitter API for posting tweets accepts text and public media URLs. Put public HTTPS images or one MP4 URL in media. When POST /x/media hosts a local file, use its mediaUrl. Never send mediaId or media_ids to this endpoint. Send a unique Idempotency-Key. Store the durable action. Poll statusUrl while terminal is false. X’s Create Post guide covers its separate endpoint. Use Xquik authentication. Store its durable write fields.

Choose the Twitter post request

Choose among 6 tweet request formats. Include only the fields required below. Create one Idempotency-Key for each automatic Twitter posting request. Reuse that key only when replaying the same network request. A new tweet, reply, caption, media URL, account, or community requires a new key. This endpoint starts the write immediately. It does not schedule future delivery. Let your scheduler call it at the approved time. One request publishes 1 tweet on X. Create replies with reply_to_tweet_id. Create each thread tweet with a separate approved request.

Store the tweet write receipt

Persist the write receipt before another worker posts. Keep these field groups:
  • Store id and request.hash for request matching.
  • Store account and target for the selected account and destination.
  • Store status, terminal, and statusUrl for polling.
  • Store safeToRetry for retry decisions.
  • Store result.result?.id or tweetId for the published Tweet ID.
  • Store billing.chargedCredits for billing checks.

Post with public media URLs

Use media for an image or MP4 at a public HTTPS URL. For local files, call Upload Media first. Pass its returned mediaUrl in media. Send up to 4 image URLs or exactly 1 MP4 URL. Keep the MP4 at 100 MB or less. Never send media_ids; that field is for DMs only. Attached media adds 2 credits per started MB across all files.
Store 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
Send your Xquik API key in this header. Alternatively, send an OAuth 2.1 bearer token.
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
Choose the connected X account by username or account ID. Xquik removes an optional @ prefix.
string
Send up to 280 characters for a standard tweet. Note tweets accept up to 25,000 characters. Omit text only when media exists.
string
Set the parent Tweet ID. Xquik posts the new tweet inside that thread.
string
Set the target X Community ID. Confirm that the connected account is a member.
boolean
Set true for a note tweet with up to 25,000 characters. The default is false.
string[]
Attach public media URLs directly.
  • Send up to 4 JPEG, PNG, GIF, WebP, or AVIF image URLs.
  • Send exactly 1 public MP4 URL up to 100 MB.
  • Never mix video with other media.
  • Use Upload Media to host a local file.
  • Pass its returned mediaUrl in media.
  • Never pass uploaded mediaId values or media_ids.
  • Attached media adds 2 credits per started MB across all files.

Response

Durable write recovery

Send one unique Idempotency-Key per intended write. Reuse it only for the same account, target, payload, and media.
  1. Store id, the nested hash in request, billing, and statusUrl.
  2. Poll after Retry-After or pollAfterMs when terminal is false.
  3. Trust safeToRetry and nextAction before any new write.

200 Terminal or 202 active

Store terminal results. Poll active actions without creating another write.
  • After HTTP 200, store the result and settled billing.
  • After HTTP 202, poll the same action. Never submit another write.
  • After HTTP 400, fix the named field. Use a new idempotency key.
  • After HTTP 401, fix authentication. Do not retry unchanged.
  • After HTTP 402, fund the account before another write.
  • After HTTP 403, reconnect the account.
  • After HTTP 409, keep the original action. Use a new key for new input.
  • After HTTP 422, fix the rejected request before retrying.
  • After HTTP 429, wait for Retry-After. Preserve the same key.
  • After HTTP 500, retry only when safeToRetry is true.
  • After HTTP 503, poll while terminal is false.
See Get Write Action Status for every lifecycle field, terminal state, billing field, and retry rule.