Skip to main content
POST https://xquik.com/api/v1/x/tweets
30 credits text-only · attached media adds 2 credits per started MB across all filesA write that must sign in to your X account first adds 10 credits. Xquik refunds them if the sign-in fails. A sign-in that works keeps them, even if X then refuses the write. See the X sign-in fee.
Create a tweet or reply from one connected X account. The route accepts text, public media URLs, and uploaded media IDs. Put public HTTPS images or 1 MP4 URL in media. For a local file, call POST /x/media and put its mediaId in media_ids. Send media or media_ids, not both. Send a unique Idempotency-Key. Store the returned write action. Poll statusUrl while terminal is false. X’s Create Post guide covers its separate endpoint. Authenticate with Xquik credentials. Store the write fields listed below.

Choose the Twitter post request

Choose among 7 tweet request formats. Include only the fields required below. To post without code, use the tweet composer on the Xquik website. It posts from your connected account at the same credit cost.A Community post lands in its Community, or the write fails and costs nothing. The error code says whether the post is still public.Create one Idempotency-Key for each posting request. Reuse that key only when replaying the same network request. A new tweet, reply, caption, media URL, or account 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. For x_target_not_found, verify the post ID and your connected account’s access. For x_reply_not_allowed, choose a post that account can reply to. For x_reply_target_unavailable, X says the post is deleted or hidden from your account. Check the post on x.com or reply to another post. Xquik returns x_reply_not_allowed or x_reply_target_unavailable when X refuses a reply. That account’s later replies to the post get the same error for a while. Retry-After says when to try again. All 3 return HTTP 422 & charge nothing. Do not retry the unchanged request. See write error recovery.

Store the tweet write receipt

Store 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. Xquik shrinks images over 5 MiB. GIFs and videos go to X unchanged. To post an uploaded file by its ID, use media_ids as shown below. 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.

Post uploaded media by ID

Use media_ids for files that Upload Media returned. Upload each file from the account that posts. Each ID works for 24 hours after its upload. Send up to 4 image IDs or exactly 1 video ID. Send media or media_ids, never both. Text is optional with either field. Xquik drops a repeated ID, so each file posts and costs once. Attached media adds 2 credits per started MB across all files.
Uploaded video tweet
None of these 3 errors charges credits.

Headers

Body

Response

Durable write recovery

Send one unique Idempotency-Key per intended write. Replay the same account, target, payload, and media after a lost response. Keep the original key for that replay.
  1. Store id, the nested hash in request, billing, and statusUrl.
  2. Poll after Retry-After or pollAfterMs when terminal is false.
  3. Retry only when safeToRetry is true.
  4. Use a new key when nextAction.requiresNewIdempotencyKey is true.

200 terminal or 202 active

  • 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. Follow nextAction.
See Get Write Action Status for every lifecycle field and terminal state. That page also lists every billing field and retry rule.

Response examples

200 example

202 example

  • 400 { "error": "missing_idempotency_key", "message": "Idempotency-Key is required. Generate one unique key for this write.", "charged": false, "chargedCredits": "0", "retryable": false, "safeToRetry": true }
  • 401 { "error": "unauthenticated", "message": "Authentication required. Provide a valid API key or bearer token." }
  • 402 { "error": "insufficient_credits", "message": "Insufficient credits. Top up or subscribe to continue." }
  • 403 { "error": "api_key_paused", "message": "This API key is paused. Resume it at dashboard.xquik.com/api-keys to use it again." }
  • 404 { "error": "account_not_found", "message": "X account not found. Connect it first at /dashboard/x-accounts." }
  • 409 { "error": "idempotency_conflict", "message": "Idempotency-Key was already used with a different request.", "charged": false, "chargedCredits": "0", "retryable": false, "safeToRetry": true }
  • 413 { "error": "media_too_large", "message": "This image stays over X's size limit after shrinking. Send a smaller one." }
  • 415 { "error": "unsupported_media_type", "message": "Xquik couldn't read this image. Send a valid image file." }
  • 422 { "error": "x_rejected", "message": "X rejected this request. Check what you sent & the account on x.com before you try again." }
  • 429 { "error": "rate_limit_exceeded", "message": "Too many requests. Try again later.", "retryAfter": 60 }
  • 500 { "error": "x_write_failed", "message": "Write action failed unexpectedly. Contact support if this persists." }
  • 503 { "error": "write_tracking_unavailable", "message": "Write tracking unavailable. Try again.", "charged": false, "chargedCredits": "0", "retryable": true, "safeToRetry": true }