Create draw - Xquik

Metered draw execution · source lookup, replies, optional retweeters, and optional follow checks consume credits

Remaining credits cap how many replies and retweeters Xquik can inspect before filters run. totalEntries and validEntries describe that inspected candidate set, not necessarily every reply on the source tweet.

curl -X POST https://xquik.com/api/v1/draws \
  -H "x-api-key: xq_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "tweetUrl": "https://x.com/xquik/status/1893456789012345678",
    "winnerCount": 3,
    "backupCount": 2,
    "mustRetweet": true,
    "filterMinFollowers": 10,
    "requiredKeywords": ["giveaway"]
  }' | jq

Headers

x-api-key

string

required

Your API key. Session cookie authentication is also supported.

Content-Type

string

required

Must be application/json.

Body

tweetUrl

string

required

Full tweet URL to run the draw on. Accepts x.com and twitter.com formats (e.g. https://x.com/user/status/1893456789012345678).

winnerCount

number

Number of winners to draw. Defaults to 1 if omitted.

backupCount

number

Number of backup winners to draw. Backup winners are selected in case primary winners are disqualified.

uniqueAuthorsOnly

boolean

When true, each author can only win once regardless of how many replies they posted.

mustRetweet

boolean

When true, only entries from users who retweeted the original tweet are eligible.

mustFollowUsername

string

X username that entrants must follow to be eligible. The @ prefix is stripped if included.

filterMinFollowers

number

Minimum follower count required for eligible entries.

filterAccountAgeDays

number

Minimum account age in days. Accounts younger than this are excluded.

filterLanguage

string

Filter entries by tweet language code (e.g. en, tr, es).

requiredKeywords

string[]

Array of keywords that must appear in the reply text. Entries missing any keyword are excluded.

requiredHashtags

string[]

Array of hashtags that must appear in the reply text. Include the # prefix.

requiredMentions

string[]

Array of usernames that must be mentioned in the reply text. Include the @ prefix.

Response

string

Draw public ID returned by Xquik.

tweetId

string

X tweet ID extracted from the URL.

totalEntries

number

Candidate entries inspected for this draw after the credit-derived cap. This may be lower than the source tweet’s full reply count.

validEntries

number

Entries from the inspected candidate set that passed all filters.

winners

array

Selected winners and backup winners.

Show winner object

position

number

Winner position (1-indexed).

authorUsername

string

X username of the winner.

tweetId

string

Tweet ID of the winning reply.

isBackup

boolean

true if this is a backup winner.

{
  "id": "f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345",
  "tweetId": "1893456789012345678",
  "totalEntries": 847,
  "validEntries": 312,
  "winners": [
    {
      "position": 1,
      "authorUsername": "alice_web3",
      "tweetId": "1893456789012345700",
      "isBackup": false
    },
    {
      "position": 2,
      "authorUsername": "bob_dev",
      "tweetId": "1893456789012345701",
      "isBackup": false
    },
    {
      "position": 3,
      "authorUsername": "charlie_nft",
      "tweetId": "1893456789012345702",
      "isBackup": false
    },
    {
      "position": 4,
      "authorUsername": "diana_crypto",
      "tweetId": "1893456789012345703",
      "isBackup": true
    },
    {
      "position": 5,
      "authorUsername": "eve_trades",
      "tweetId": "1893456789012345704",
      "isBackup": true
    }
  ]
}

{ "error": "invalid_input", "message": "Missing or malformed request body" }

Missing or malformed request body. Ensure tweetUrl is a string.

{ "error": "invalid_tweet_url", "message": "Invalid tweet URL format" }

The tweetUrl could not be parsed. Must be a valid x.com or twitter.com status URL.

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

Missing or invalid API key / session cookie.

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

No active subscription, inactive subscription, no credits, or insufficient credits. Draws first check that the minimum draw cost is affordable. A later final deduction failure returns insufficient_credits and no draw result is persisted. Check your credit balance.

{ "error": "tweet_not_found", "message": "Tweet not found" }

The target tweet does not exist, was deleted, or the ID is invalid.

{
  "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.

{ "error": "rate_limit_exceeded", "message": "Too many requests. Try again later.", "retryAfter": 1 }

Too many requests. Wait for the Retry-After header before retrying.

{ "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/Markdown, or List Draws to see your draw history.

Documentation Index

​Headers

​Body

​Response

Headers

Body

Response