> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xquik.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Panel>
  <Tabs defaultTabIndex={0} sync={false}>
    <Tab title="200" id="response-draws-export-200">
      ```text theme={null}
      <string>
      ```
    </Tab>

    <Tab title="400" id="response-draws-export-400">
      ```json theme={null}
      {
        "error": "invalid_input",
        "message": "Invalid input. Check the request body."
      }
      ```
    </Tab>

    <Tab title="401" id="response-draws-export-401">
      ```json theme={null}
      {
        "error": "unauthenticated",
        "message": "Authentication required. Provide a valid API key or bearer token."
      }
      ```
    </Tab>

    <Tab title="404" id="response-draws-export-404">
      ```json theme={null}
      {
        "error": "not_found",
        "message": "Resource not found."
      }
      ```
    </Tab>

    <Tab title="429" id="response-draws-export-429">
      ```json theme={null}
      {
        "error": "rate_limit_exceeded",
        "message": "Too many requests. Try again later.",
        "retryAfter": 60
      }
      ```
    </Tab>
  </Tabs>
</Panel>

<blockquote className="agent-llms-directive">
  For the complete documentation index, see <a href="/llms.txt">llms.txt</a>.
</blockquote>

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

<Callout icon="circle-check" color="#16a34a">
  **Free.** This endpoint does not consume credits.
</Callout>

<CardGroup cols={2}>
  <Card title="Winner list" icon="trophy">
    Set `type=winners`. Export ordered primary and backup winners with their
    selected reply text.
  </Card>

  <Card title="Inspected entries" icon="list-checks">
    Set `type=entries`. Export stored replies with filter results and detected
    languages.
  </Card>

  <Card title="Spreadsheet review" icon="file-spreadsheet">
    Choose CSV or XLSX for sorting, filtering, sponsor review, and fulfillment.
  </Card>

  <Card title="Audit archive" icon="archive">
    Choose JSON, Markdown, PDF, or text for scripts and review records.
  </Card>
</CardGroup>

The export does not include source tweet metadata or create-time filter rules.
Join the file with [Get Draw](/api-reference/draws/get) using the draw ID.
Keep the original create request when reviewers need eligibility rules.

## Download a giveaway winner CSV

<CodeGroup>
  ```bash cURL theme={null}
  curl --fail-with-body \
    "https://xquik.com/api/v1/draws/f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345/export?format=csv&type=winners" \
    -H "x-api-key: xq_YOUR_KEY_HERE" \
    --output twitter-giveaway-winners.csv
  ```

  ```javascript Node.js theme={null}
  import { writeFile } from "node:fs/promises";

  const drawId = "f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345";
  const response = await fetch(
    `https://xquik.com/api/v1/draws/${drawId}/export?format=csv&type=winners`,
    {
      headers: { "x-api-key": "xq_YOUR_KEY_HERE" },
    },
  );
  if (!response.ok) {
    const problem = await response.json();
    throw new Error(problem.message || "Giveaway winner export failed.");
  }

  const bytes = Buffer.from(await response.arrayBuffer());
  await writeFile("twitter-giveaway-winners.csv", bytes);
  process.stdout.write(`${response.headers.get("content-disposition") || "download saved"}\n`);
  ```

  ```python Python theme={null}
  import requests

  draw_id = "f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345"
  response = requests.get(
      f"https://xquik.com/api/v1/draws/{draw_id}/export",
      headers={"x-api-key": "xq_YOUR_KEY_HERE"},
      params={"format": "csv", "type": "winners"},
      timeout=30,
  )
  response.raise_for_status()
  with open("twitter-giveaway-winners.csv", "wb") as export_file:
      export_file.write(response.content)
  ```

  ```go Go theme={null}
  package main

  import (
    "fmt"
    "io"
    "log"
    "net/http"
    "os"
  )

  func main() {
    drawID := "f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345"
    req, err := http.NewRequest("GET", "https://xquik.com/api/v1/draws/"+drawID+"/export?format=csv&type=winners", nil)
    if err != nil {
      log.Fatal(err)
    }
    req.Header.Set("x-api-key", "xq_YOUR_KEY_HERE")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
      log.Fatal(err)
    }
    defer resp.Body.Close()

    if resp.StatusCode < 200 || resp.StatusCode >= 300 {
      body, readErr := io.ReadAll(resp.Body)
      if readErr != nil {
        log.Fatal(readErr)
      }
      log.Fatalf("giveaway export failed with %d: %s", resp.StatusCode, string(body))
    }

    file, err := os.Create("twitter-giveaway-winners.csv")
    if err != nil {
      log.Fatal(err)
    }
    defer file.Close()

    if _, err := io.Copy(file, resp.Body); err != nil {
      log.Fatal(err)
    }
    fmt.Println(resp.Header.Get("Content-Disposition"))
  }
  ```
</CodeGroup>

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 contains the same rows. Only the file encoding and filename
extension change. `type` alone decides the columns.

<CardGroup cols={2}>
  <Card title="CSV for Google Sheets" icon="table">
    Use `format=csv` for spreadsheets and imports. Xquik neutralizes
    formula-like reply text before download.
  </Card>

  <Card title="XLSX for Excel" icon="file-spreadsheet">
    Use `format=xlsx` for a native workbook with a bold header row.
  </Card>

  <Card title="JSON for automation" icon="braces">
    Use `format=json` for scripts, databases, and structured giveaway archives.
  </Card>

  <Card title="Markdown table" icon="table-properties">
    Use `format=md` for a compact table in repositories or review tickets.
  </Card>

  <Card title="Markdown document" icon="file-text">
    Use `format=md-document` for one titled section per winner or entry.
  </Card>

  <Card title="PDF for review" icon="file-down">
    Use `format=pdf` for a readable handoff. Entry PDFs include up to 10,000 rows.
  </Card>

  <Card title="Plain text" icon="file">
    Use `format=txt` for line-oriented review without spreadsheet software.
  </Card>
</CardGroup>

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

The export orders winner rows by their 1-indexed draw position. Do not sort them by
username before publication.

<CardGroup cols={2}>
  <Card title="Position" icon="list-ordered">
    `Position` keeps the original winner order. Keep it in every handoff.
  </Card>

  <Card title="Username" icon="at-sign">
    `Username` identifies the selected X account at draw time.
  </Card>

  <Card title="Text" icon="message-square-text">
    `Text` contains the selected reply text stored for the draw.
  </Card>

  <Card title="Backup" icon="shield-plus">
    `Backup` is `true` for a backup winner. Keep backup rows separate.
  </Card>
</CardGroup>

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 keep stored insertion order. They include passing and failing
replies that Xquik inspected.

<CardGroup cols={2}>
  <Card title="Username" icon="at-sign">
    `Username` identifies the reply author stored during draw processing.
  </Card>

  <Card title="Text" icon="reply">
    `Text` contains the stored reply used during eligibility checks.
  </Card>

  <Card title="Passed filter" icon="list-checks">
    `Passed Filter` reports whether that reply passed every configured filter.
  </Card>

  <Card title="Language" icon="languages">
    `Language` contains the stored language code. It can be empty.
  </Card>
</CardGroup>

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

Keep both exports with the draw detail. Reviewers can then check winners
against every inspected reply.

```json theme={null}
{
  "draw_id": "f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345",
  "draw_detail_path": "/api/v1/draws/f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345",
  "winner_export_path": "/api/v1/draws/f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345/export?format=csv&type=winners",
  "entry_export_path": "/api/v1/draws/f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345/export?format=csv&type=entries",
  "create_request_stored": true
}
```

Store the original create request separately. It contains hashtags, keywords,
mentions, language, follower rules, and other eligibility settings.

## Path parameters

<ParamField path="id" type="string" required>
  The public draw ID. Retrieve it from [Giveaway History](/api-reference/draws/twitter-giveaway-history) or draw creation.
</ParamField>

## Headers

<ParamField header="x-api-key" type="string" required>
  Send your Xquik API key. Generate one from the [dashboard](https://xquik.com/dashboard).
</ParamField>

<ParamField header="Authorization" type="string">
  Send `Bearer <token>` instead of `x-api-key` when using OAuth 2.1.
</ParamField>

## Query parameters

<ParamField query="format" type="string" required>
  Choose `csv`, `json`, `md`, `md-document`, `pdf`, `txt`, or `xlsx`.
</ParamField>

<ParamField query="type" type="string">
  Choose `winners` or `entries`. The default is `winners`.
</ParamField>

## Response

### 200 File download

Returns a file download. The response includes a `Content-Disposition`
header with the filename.

<CardGroup cols={2}>
  <Card title="CSV" icon="table">
    `format=csv` returns `text/csv; charset=utf-8` with filenames like
    `draw-winners-*.csv`.
  </Card>

  <Card title="JSON" icon="braces">
    `format=json` returns `application/json; charset=utf-8` with filenames
    like `draw-winners-*.json`.
  </Card>

  <Card title="Markdown" icon="file-text">
    `format=md` returns `text/markdown; charset=utf-8` with filenames like
    `draw-winners-*.md`.
  </Card>

  <Card title="Markdown document" icon="file-text">
    `format=md-document` returns `text/markdown; charset=utf-8` with
    filenames like `draw-winners-*.md`.
  </Card>

  <Card title="PDF" icon="file-down">
    `format=pdf` returns `application/pdf` with filenames like
    `draw-winners-*.pdf`.
  </Card>

  <Card title="TXT" icon="file">
    `format=txt` returns `text/plain; charset=utf-8` with filenames like
    `draw-winners-*.txt`.
  </Card>

  <Card title="XLSX" icon="file-spreadsheet">
    `format=xlsx` returns
    `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` with
    filenames like `draw-winners-*.xlsx`.
  </Card>
</CardGroup>

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 stop at 100,000 rows (10,000 for PDF).

### 400 Invalid parameters

```json theme={null}
{
  "error": "invalid_input",
  "message": "Invalid input. Check the request body."
}
```

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

### 401 Unauthenticated

```json theme={null}
{
  "error": "unauthenticated",
  "message": "Authentication required. Provide a valid API key or bearer token."
}
```

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

### 404 Draw not found

```json theme={null}
{
  "error": "not_found",
  "message": "Resource not found."
}
```

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

### 429 Rate limited

```json theme={null}
{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Try again later.",
  "retryAfter": 60
}
```

Honor `Retry-After`, then retry the identical export request.

## Handle giveaway export responses

<CardGroup cols={2}>
  <Card title="200 File ready" icon="circle-check">
    Save the binary body. Keep the `Content-Disposition` filename when
    your storage policy allows it.
  </Card>

  <Card title="400 Parameters" icon="list-x">
    Supply one supported format. Use only `winners` or `entries` for type.
  </Card>

  <Card title="401 Authentication" icon="key-round">
    Replace the API key or OAuth bearer token before retrying.
  </Card>

  <Card title="404 Draw missing" icon="search-x">
    Confirm the public draw ID and the account owning that draw.
  </Card>

  <Card title="429 Rate limit" icon="timer">
    Wait for `Retry-After`. Reuse the same draw ID, format, and type.
  </Card>
</CardGroup>

## 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 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. 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 simple scripts.

### How do I identify backup winners?

Export winners and read `Backup`. 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](/api-reference/draws/get) 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.

<Note>
  **Related.** [Get Draw](/api-reference/draws/get) verifies winners.
  [Giveaway History](/api-reference/draws/twitter-giveaway-history) finds draw
  IDs. [Create Draw](/api-reference/draws/create) starts a new selection.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.