Draws
Twitter giveaway CSV export API & winner lists
Export selected Twitter giveaway winners or inspected reply entries as CSV, XLSX, JSON, Markdown, PDF, or text. Keep all columns, order, and filenames.
- 200
- 400
- 401
- 404
- 429
GET
Twitter giveaway CSV export API & winner lists
Download a Twitter giveaway winner list or inspected reply entries. Choose
CSV, XLSX, JSON, Markdown, PDF, or plain text. Keep the returned filename
and exact row order for every handoff.
Use
The export does not include source tweet metadata or create-time filter rules.
Join the file with Get Draw using the draw ID.
Keep the original create request when reviewers need eligibility rules.
Never parse a successful export as JSON. The
CSV, JSON, Markdown, text, and XLSX entry exports include up to 100,000 rows.
PDF entry exports include up to 10,000 rows. Winner exports contain selected winners.
The winner export does not include the winning reply ID. Retrieve draw detail
when verification needs each winner’s
Do not call every exported entry eligible. Check
Store the original create request separately. It contains hashtags, keywords,
mentions, language, follower rules, and other eligibility settings.
PDF
Entry exports use the same suffix pattern with
The
The API key or OAuth bearer token is missing or invalid. Replace it first.
No accessible draw matches that ID. Check the ID and authenticated account.
Honor
type=winners for selected primary and backup winners. Use type=entries
for every stored reply inspected during the draw. Entry exports include passing
and failing replies.
Export Twitter giveaway winners or entries
Choose the export type before choosing its file format. The 2 export types contain different columns and answer different review questions.Free. This endpoint does not consume credits.
Winner list
Set
type=winners. Export ordered primary and backup winners with their
selected reply text.Inspected entries
Set
type=entries. Export stored replies with filter results and detected
languages.Spreadsheet review
Choose CSV or XLSX for sorting, filtering, sponsor review, and fulfillment.
Audit archive
Choose JSON, Markdown, PDF, or text for scripts and review records.
Download a giveaway winner CSV
200 body contains file bytes.
Parse JSON only after a non-success status.
Choose a Twitter giveaway export format
Every format contains the same rows. Only the file encoding and filename extension change.type alone decides the columns.
CSV for Google Sheets
Use
format=csv for spreadsheets and imports. Xquik neutralizes
formula-like reply text before download.XLSX for Excel
Use
format=xlsx for a native workbook with a bold header row.JSON for automation
Use
format=json for scripts, databases, and structured giveaway archives.Markdown table
Use
format=md for a compact table in repositories or review tickets.Markdown document
Use
format=md-document for one titled section per winner or entry.PDF for review
Use
format=pdf for a readable handoff. Entry PDFs include up to 10,000 rows.Plain text
Use
format=txt for line-oriented review without spreadsheet software.Understand winner export columns
The export orders winner rows by their 1-indexed draw position. Do not sort them by username before publication.Position
Position keeps the original winner order. Keep it in every handoff.Username
Username identifies the selected X account at draw time.Text
Text contains the selected reply text stored for the draw.Backup
Backup is true for a backup winner. Keep backup rows separate.tweetId.
Understand giveaway entry export columns
Entry rows keep stored insertion order. They include passing and failing replies that Xquik inspected.Username
Username identifies the reply author stored during draw processing.Text
Text contains the stored reply used during eligibility checks.Passed filter
Passed Filter reports whether that reply passed every configured filter.Language
Language contains the stored language code. It can be empty.Passed Filter first. The
entry file cannot explain which individual rule rejected a reply.
Build a giveaway audit handoff
Keep both exports with the draw detail. Reviewers can then check winners against every inspected reply.Path parameters
string
required
The public draw ID. Retrieve it from Giveaway History or draw creation.
Headers
string
Send
Bearer <token> instead of x-api-key when using OAuth 2.1.Query parameters
string
required
Choose
csv, json, md, md-document, pdf, txt, or xlsx.string
Choose
winners or entries. The default is winners.Response
200 File download
Returns a file download. The response includes aContent-Disposition
header with the filename.
CSV
format=csv returns text/csv; charset=utf-8 with filenames like
draw-winners-*.csv.JSON
format=json returns application/json; charset=utf-8 with filenames
like draw-winners-*.json.Markdown
format=md returns text/markdown; charset=utf-8 with filenames like
draw-winners-*.md.Markdown document
format=md-document returns text/markdown; charset=utf-8 with
filenames like draw-winners-*.md.format=pdf returns application/pdf with filenames like
draw-winners-*.pdf.TXT
format=txt returns text/plain; charset=utf-8 with filenames like
draw-winners-*.txt.XLSX
format=xlsx returns
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet with
filenames like draw-winners-*.xlsx.draw-entries-* filenames.
Winner export columns. Position, Username, Text, Backup
Entry export columns. Username, Text, Passed Filter, Language
Entry exports stop at 100,000 rows (10,000 for PDF).
400 Invalid parameters
format value is missing or unsupported. The type value can also be
invalid. Fix both values before retrying.
401 Unauthenticated
404 Draw not found
429 Rate limited
Retry-After, then retry the identical export request.
Handle giveaway export responses
200 File ready
Save the binary body. Keep the
Content-Disposition filename when
your storage policy allows it.400 Parameters
Supply one supported format. Use only
winners or entries for type.401 Authentication
Replace the API key or OAuth bearer token before retrying.
404 Draw missing
Confirm the public draw ID and the account owning that draw.
429 Rate limit
Wait for
Retry-After. Reuse the same draw ID, format, and type.Twitter giveaway export questions
How do I download Twitter giveaway winners as CSV?
Call this endpoint withformat=csv&type=winners. Save the binary response as
a CSV file. Check the HTTP status before opening it.
Can I export every inspected giveaway entry?
Yes. Settype=entries. The file contains the stored replies that Xquik
inspected. It does not fetch new replies.
Does an entry export contain only eligible replies?
No. It contains passing and failing stored replies. UsePassed Filter to
separate them.
Which giveaway export opens in Excel?
Chooseformat=xlsx for a native workbook. Choose CSV for Excel, Google
Sheets, imports, or simple scripts.
How do I identify backup winners?
Export winners and readBackup. A true value marks a backup winner.
Keep the original Position value.
Can I export more than 100,000 giveaway entries?
No single non-PDF entry export exceeds 100,000 stored rows. PDF exports include up to 10,000 rows. The endpoint has no cursor.Does the export include giveaway eligibility rules?
No. Keep the original draw request separately. The entry export reports only the combined pass result.Does the export include source tweet metrics?
No. Call Get Draw for source tweet metrics, candidate counts, status, and timestamps.What happens when a winner export has no rows?
The file can contain headers or an empty collection. Treat that as an empty result, not a transport failure.Can I use the file for sponsor proof?
Yes, but include draw detail and the stored create request. The export alone cannot reconstruct eligibility rules.Does a giveaway export consume credits?
No. Exporting an existing draw is free. Creating a new draw can consume credits.Related. Get Draw verifies winners.
Giveaway History finds draw
IDs. Create Draw starts a new selection.