Draws
Twitter giveaway winner API & draw verification
Retrieve one Twitter giveaway draw by ID. Verify source tweet metrics, entry counts, ordered primary and backup winners, timestamps, and result status.
- 200
- 401
- 404
- 429
GET
Twitter giveaway winner API & draw verification
Retrieve one Twitter giveaway result with its draw ID. Inspect the source tweet
snapshot, candidate counts, timestamps, and ordered winner rows. Separate
primary winners from backup winners before publishing results.
This endpoint does not return create-time eligibility rules or exclusion
reasons. Preserve the original
Use Giveaway History to find a
draw ID. Use Export Draw for winner or entry
files.
Do not promote a backup winner by changing the existing row. Record the
replacement decision separately. This preserves the original draw result.
Store winner rows separately from this summary. Keep
The API key or OAuth bearer token is missing or invalid. Replace it before
retrying.
No draw exists with this ID, or it belongs to a different account.
Too many requests. Wait for the
POST /draws request when an audit needs those
rules.
Verify one Twitter giveaway draw
Use this route to review one completed or pending draw. Keep its draw ID with winner announcements, support records, and exports.Free - does not consume credits
Source tweet snapshot
Read the tweet ID, URL, text, author, and engagement counts captured for
the draw.
Candidate counts
Compare
totalEntries with validEntries. Neither value reports the
number of winners.Ordered winners
Preserve
position, authorUsername, tweetId, and isBackup for every
selected account.Draw timing
Store
createdAt for creation. Store drawnAt when winner selection has
finished.Interpret Twitter giveaway winner rows
Winner order is part of the result. Preserve each 1-indexedposition instead
of sorting by username or tweet ID.
Primary winner
isBackup is false. Use the original position in announcements and
fulfillment records.Backup winner
isBackup is true. Keep the row separate until replacement approval is
recorded.Winning reply
tweetId identifies the selected reply. Store it beside the winner’s X
username.Winner account
authorUsername identifies the selected X account at draw time. Keep the
tweet ID as the stable join value.Preserve eligibility rules separately
GET /draws/{id} returns the draw snapshot and winners. It does not repeat the
eligibility filters sent to POST /draws.
Store the original create request when reviews need these settings:
- required repost and followed-account rules
- required keywords, hashtags, mentions, or language
- minimum account age and follower count
- primary, backup, and unique-author settings
Build a giveaway verification handoff
Join the draw summary, winner rows, and export location with one draw ID:position and isBackup
on every row. Never infer filter rules from entry counts.
Path parameters
string
required
The draw public ID. Returned when you create a draw or list draws.
Headers
string
Send
Bearer <token> instead of x-api-key when using OAuth 2.1.Response
200 OK
object
Draw details including tweet metadata.
Draw object fields.
string
Draw public ID returned by Xquik.
string
X tweet ID.
string
Original tweet URL.
string
Full text content of the tweet.
string
Username of the tweet author.
number
Like count at time of draw.
number
Retweet count at time of draw.
number
Reply count at time of draw.
number
Quote tweet count at time of draw.
string
Draw status (e.g.
completed).number
Inspected candidate entries.
number
Entries that passed all filters.
string
ISO 8601 creation timestamp.
string
ISO 8601 timestamp of when winners were selected. Present only for completed draws.
array
401 Unauthenticated
404 Not found
429 Rate limited
Retry-After header before retrying.
Handle giveaway draw responses
200 Draw result
Read
draw and winners. Split primary and backup winners before handoff.401 Authentication
Authentication failed. Replace the API key or OAuth bearer token first.
404 Draw missing
No accessible draw matches that ID. Check its account and exact value.
429 Rate limit
Too many requests. Honor
Retry-After, then retry the same draw ID.Twitter giveaway winner verification questions
How do I verify a past Twitter giveaway winner?
Get the draw ID from giveaway history. RequestGET /draws/{id}. Preserve the
ordered winner rows and source tweet snapshot.
Does the draw detail include eligibility rules?
No. Store the original create request separately. Use entry exports when a review needs candidate pass or fail values.How do I identify backup winners?
ReadisBackup on every winner row. A primary winner has false. A backup
winner has true.
Can I download the giveaway result?
Yes. CallGET /draws/{id}/export. Choose winners or entries and a supported
file format.
What if the giveaway draw ID returns 404?
Check the exact draw ID and authenticated account. Another account’s draw is not accessible with the current credential.Does winner verification consume credits?
No. Retrieving an existing draw is free. Running a new draw can consume credits.Related. Export Draw downloads results.
Giveaway History lists past
draws. Create Draw runs a new selection.
- 200
- 401
- 404
- 429
Twitter giveaway winner API & draw verification