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 withIdempotency-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." }