Skip to main content
POST
/
draws
Create draw
curl --request POST \
  --url https://xquik.com/api/v1/draws \
  --header 'Content-Type: <content-type>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "tweetUrl": "<string>",
  "winnerCount": 123,
  "backupCount": 123,
  "uniqueAuthorsOnly": true,
  "mustRetweet": true,
  "mustFollowUsername": "<string>",
  "filterMinFollowers": 123,
  "filterAccountAgeDays": 123,
  "filterLanguage": "<string>",
  "requiredKeywords": [
    "<string>"
  ],
  "requiredHashtags": [
    "<string>"
  ],
  "requiredMentions": [
    "<string>"
  ]
}
'

Documentation Index

Fetch the complete documentation index at: https://docs.xquik.com/llms.txt

Use this file to discover all available pages before exploring further.

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

​
id
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.
{
  "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
    }
  ]
}
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.
Last modified on May 9, 2026