Skip to main content
POST https://xquik.com/api/v1/draws Use this Twitter giveaway picker API to select primary and backup winners. Filter replies by reposts, follows, keywords, hashtags, mentions, or language. Add account-age, follower-count, or unique-author rules.
Metered draw execution · source lookup, replies, optional retweeters, and optional follow checks consume credits
Xquik reads every direct reply and retweeter X shows. It stops at what your remaining credits cover. totalEntries and validEntries count the inspected direct replies. X hides some replies, so the post can report more. A draw on a busy post takes about 1 minute. To allow for that, keep the request open for 100 seconds. Xquik runs & charges follow checks only for authors who pass your other filters.

Headers

Body

Response

201 Created

An exact retry returns the original draw with Idempotency-Replayed: true.

400 Invalid input

{ "error": "invalid_input", "message": "Missing or malformed request body" } Missing or malformed request body. Send tweetUrl as a string.

400 Invalid tweet URL

{ "error": "invalid_tweet_url", "message": "Invalid tweet URL format" } Xquik could not parse the tweetUrl. Must be a valid x.com or twitter.com status URL.

400 Invalid idempotency key

{ "error": "invalid_idempotency_key", "message": "Idempotency-Key invalid. Use 1-255 visible ASCII characters." } The Idempotency-Key header is empty, longer than 255 characters, or not visible ASCII.

401 Unauthenticated

{ "error": "unauthenticated", "message": "Missing or invalid API key" } Missing or invalid API key / session cookie.

402 Insufficient credits

{ "error": "insufficient_credits", "message": "Insufficient credits. Top up or subscribe to continue." } The available balance cannot cover the minimum draw cost. A later final deduction failure also returns insufficient_credits. Xquik stores no draw result and charges nothing after that failure. Check your credit balance.

404 Not found

{ "error": "tweet_not_found", "message": "Tweet not found" } The target tweet does not exist, was deleted, or the ID is invalid.

409 Idempotency conflict

Reuse a key only for the same request. Exact retries return the original draw. Xquik reads nothing and charges nothing for this request.

409 Idempotency in progress

{ "error": "idempotency_in_progress", "message": "Idempotency-Key belongs to a running request. Retry later." } The first request with this key is still running. Retry with the same key after it finishes. Xquik charges nothing for this request.

424 Short read

{ "error": "draw_too_large", "message": "The post has more replies than 1 draw reads. Contact support." } X failed or stopped early. Retry after replies_incomplete or retweeters_incomplete. draw_too_large means the post has more entries than 1 draw reads. Contact support. Xquik saves & charges nothing.

424 X API dependency failed

{ "error": { "type": "dependency_error", "code": "x_api_unavailable", "message": "X data source temporarily unavailable" } } Send xquik-api-contract: 2026-04-29 to receive this status for dependency failures that return 502 by default.

429 Rate limited

{ "error": "rate_limit_exceeded", "message": "Too many requests. Try again later.", "retryAfter": 1 } Too many requests. Wait for the Retry-After header before retrying.

502 X API unavailable

{ "error": "x_api_unavailable", "message": "X data source temporarily unavailable" } The read service returned an error. Retry after a short delay.
Next steps.
  • Get Draw to retrieve full draw details including tweet metadata.
  • Export Draw to download results as CSV, XLSX or Markdown.
  • List Draws to see your draw history.

Response examples

  • 400 { "error": "invalid_input", "message": "Invalid input. Check the request body." }
  • 401 { "error": "unauthenticated", "message": "Authentication required. Provide a valid API key or bearer token." }
  • 402 { "error": "insufficient_credits", "message": "Insufficient credits" }
  • 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": "not_found", "message": "Resource not found." }
  • 409 { "error": "idempotency_conflict", "message": "Idempotency-Key belongs to another request. Use a new key." }
  • 424 { "error": "replies_incomplete", "message": "X stopped before every reply loaded. Retry the draw later." }
  • 429 { "error": "rate_limit_exceeded", "message": "Too many requests. Try again later.", "retryAfter": 60 }
  • 502 { "error": "x_api_unavailable", "message": "X data source temporarily unavailable. Try again later." }