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. Preserve 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. Preserve 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.
Preserve 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 two export types contain different columns and answer different review questions.Free - 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 represents the same selected rows. Serialization and filename extensions change. Column selection depends only ontype.
CSV for Google Sheets
Use
format=csv for spreadsheets and imports. Formula-like reply text is
neutralized 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
Winner rows are ordered by their 1-indexed draw position. Do not sort them by username before publication.Position
Position preserves 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 preserve stored insertion order. They include passing and failing replies from the inspected candidate set.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
Pair both exports with the draw snapshot. This keeps winner selection separate from inspected candidate evidence.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 are capped 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. Preserve 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 stored replies from the inspected
candidate set. 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 lightweight processing.
How do I identify backup winners?
Export winners and readBackup. A true value marks a backup winner.
Preserve 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. Preserve 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.
- 200
- 400
- 401
- 404
- 429
Twitter giveaway CSV export API & winner lists