Skip to main content
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 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.
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.

Download a giveaway winner CSV

Never parse a successful export as JSON. The 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 on type.

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.
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.

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.
The winner export does not include the winning reply ID. Retrieve draw detail when verification needs each winner’s 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.
Do not call every exported entry eligible. Check 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.
Store the original create request separately. It contains hashtags, keywords, mentions, language, follower rules, and other eligibility settings.

Path parameters

string
required
The public draw ID. Retrieve it from Giveaway History or draw creation.

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.

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 a Content-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.

PDF

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.
Entry exports use the same suffix pattern with 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

The format value is missing or unsupported. The type value can also be invalid. Fix both values before retrying.

401 Unauthenticated

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

404 Draw not found

No accessible draw matches that ID. Check the ID and authenticated account.

429 Rate limited

Honor 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 with format=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. Set type=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. Use Passed Filter to separate them.

Which giveaway export opens in Excel?

Choose format=xlsx for a native workbook. Choose CSV for Excel, Google Sheets, imports, or lightweight processing.

How do I identify backup winners?

Export winners and read Backup. 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.