Skip to main content
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 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.
Use Giveaway History to find a draw ID. Use Export Draw for winner or entry files.

Interpret Twitter giveaway winner rows

Winner order is part of the result. Preserve each 1-indexed position 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.
Do not promote a backup winner by changing the existing row. Record the replacement decision separately. This preserves the original draw result.

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
Use an entry export when the review needs candidate rows. The export can show whether an entry passed the filters. It does not reconstruct a missing create request.

Build a giveaway verification handoff

Join the draw summary, winner rows, and export location with one draw ID:
Store winner rows separately from this summary. Keep 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
required
Send your Xquik API key. Generate one from the dashboard.
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
Selected winners and backup winners ordered by position. Winner object fields.
number
Winner position (1-indexed).
string
X username of the winner.
string
Tweet ID of the winning reply.
boolean
true if this is a backup winner.

401 Unauthenticated

The API key or OAuth bearer token is missing or invalid. Replace it before retrying.

404 Not found

No draw exists with this ID, or it belongs to a different account.

429 Rate limited

Too many requests. Wait for the 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. Request GET /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?

Read isBackup on every winner row. A primary winner has false. A backup winner has true.

Can I download the giveaway result?

Yes. Call GET /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.