> ## 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 winner API & draw verification

> Retrieve one Twitter giveaway draw by ID. Verify source tweet metrics, entry counts, ordered primary and backup winners, timestamps, and result status.

<Panel>
  <Tabs defaultTabIndex={0} sync={false}>
    <Tab title="200" id="response-draws-get-200">
      ```json theme={null}
      {
        "draw": {
          "id": "f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345",
          "tweetUrl": "https://x.com/elonmusk/status/1234567890",
          "tweetId": "1234567890",
          "tweetText": "Giving away 3 Tesla Model 3s!",
          "tweetAuthorUsername": "elonmusk"
        },
        "winners": []
      }
      ```
    </Tab>

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

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

    <Tab title="429" id="response-draws-get-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>

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

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

<CardGroup cols={2}>
  <Card title="Source tweet snapshot" icon="message-square-text">
    Read the tweet ID, URL, text, author, and engagement counts captured for
    the draw.
  </Card>

  <Card title="Candidate counts" icon="users-round">
    Compare `totalEntries` with `validEntries`. Neither value reports the
    number of winners.
  </Card>

  <Card title="Ordered winners" icon="trophy">
    Keep `position`, `authorUsername`, `tweetId`, and `isBackup` for every
    selected account.
  </Card>

  <Card title="Draw timing" icon="clock-3">
    Store `createdAt` for creation. Store `drawnAt` when winner selection has
    finished.
  </Card>
</CardGroup>

Use [Giveaway History](/api-reference/draws/twitter-giveaway-history) to find a
draw ID. Use [Export Draw](/api-reference/draws/export) for winner or entry
files.

<CodeGroup>
  ```bash cURL theme={null}
  curl --fail-with-body https://xquik.com/api/v1/draws/f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345 \
    -H "x-api-key: xq_YOUR_KEY_HERE" | jq
  ```

  ```javascript Node.js theme={null}
  const drawId = "f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345";
  const response = await fetch(`https://xquik.com/api/v1/draws/${drawId}`, {
    headers: { "x-api-key": "xq_YOUR_KEY_HERE" },
  });
  const result = await response.json();
  if (!response.ok) {
    throw new Error(result.message || "Giveaway draw request failed.");
  }

  const verification = {
    draw_id: result.draw.id,
    tweet_id: result.draw.tweetId,
    tweet_url: result.draw.tweetUrl,
    status: result.draw.status,
    total_entries: result.draw.totalEntries,
    valid_entries: result.draw.validEntries,
    created_at: result.draw.createdAt,
    drawn_at: result.draw.drawnAt || null,
    primary_winners: result.winners.filter((winner) => !winner.isBackup),
    backup_winners: result.winners.filter((winner) => winner.isBackup),
  };
  process.stdout.write(`${JSON.stringify(verification)}\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}",
      headers={"x-api-key": "xq_YOUR_KEY_HERE"},
  )
  response.raise_for_status()
  result = response.json()
  verification = {
      "draw_id": result["draw"]["id"],
      "tweet_id": result["draw"]["tweetId"],
      "tweet_url": result["draw"]["tweetUrl"],
      "status": result["draw"]["status"],
      "primary_winners": [
          winner for winner in result["winners"] if not winner["isBackup"]
      ],
      "backup_winners": [
          winner for winner in result["winners"] if winner["isBackup"]
      ],
  }
  print(verification)
  ```

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

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

  func main() {
    drawID := "f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345"
  	req, err := http.NewRequest("GET", "https://xquik.com/api/v1/draws/"+drawID, 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()

  	body, err := io.ReadAll(resp.Body)
  	if err != nil {
  		log.Fatal(err)
  	}
  	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
  		log.Fatalf("giveaway draw failed with %d: %s", resp.StatusCode, string(body))
  	}
  	fmt.Println(string(body))
  }
  ```
</CodeGroup>

## Interpret Twitter giveaway winner rows

Winner order is part of the result. Keep each 1-indexed `position`. Do not
sort by username or tweet ID.

<CardGroup cols={2}>
  <Card title="Primary winner" icon="medal">
    `isBackup` is `false`. Use the original `position` in announcements and
    fulfillment records.
  </Card>

  <Card title="Backup winner" icon="shield-plus">
    `isBackup` is `true`. Keep the row separate until someone approves
    the replacement.
  </Card>

  <Card title="Winning reply" icon="reply">
    `tweetId` identifies the selected reply. Store it beside the winner's X
    username.
  </Card>

  <Card title="Winner account" icon="at-sign">
    `authorUsername` identifies the selected X account at draw time. Join
    records on the tweet ID, which does not change.
  </Card>
</CardGroup>

Do not promote a backup winner by changing the existing row. Record the
replacement decision separately. This keeps the original draw result.

## Keep 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:

```json theme={null}
{
  "draw_id": "f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345",
  "tweet_id": "1893456789012345678",
  "tweet_url": "https://x.com/xquik/status/1893456789012345678",
  "status": "completed",
  "total_entries": 847,
  "valid_entries": 312,
  "created_at": "2026-02-24T10:00:00.000Z",
  "drawn_at": "2026-02-24T10:05:00.000Z",
  "primary_winner_count": 3,
  "backup_winner_count": 0,
  "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"
}
```

Store winner rows separately from this summary. Keep `position` and `isBackup`
on every row. Never infer filter rules from entry counts.

## Path parameters

<ParamField path="id" type="string" required>
  The draw public ID. Returned when you [create a draw](/api-reference/draws/create) or [list draws](/api-reference/draws/twitter-giveaway-history).
</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>

## Response

### 200 OK

<ResponseField name="draw" type="object">
  Draw details including tweet metadata.
  **Draw object fields.**

  <ResponseField name="id" type="string">
    Draw public ID returned by Xquik.
  </ResponseField>

  <ResponseField name="tweetId" type="string">
    X tweet ID.
  </ResponseField>

  <ResponseField name="tweetUrl" type="string">
    Original tweet URL.
  </ResponseField>

  <ResponseField name="tweetText" type="string">
    Full text content of the tweet.
  </ResponseField>

  <ResponseField name="tweetAuthorUsername" type="string">
    Username of the tweet author.
  </ResponseField>

  <ResponseField name="tweetLikeCount" type="number">
    Like count at time of draw.
  </ResponseField>

  <ResponseField name="tweetRetweetCount" type="number">
    Retweet count at time of draw.
  </ResponseField>

  <ResponseField name="tweetReplyCount" type="number">
    Reply count at time of draw.
  </ResponseField>

  <ResponseField name="tweetQuoteCount" type="number">
    Quote tweet count at time of draw.
  </ResponseField>

  <ResponseField name="status" type="string">
    Draw status (for example `completed`).
  </ResponseField>

  <ResponseField name="totalEntries" type="number">
    Inspected candidate entries.
  </ResponseField>

  <ResponseField name="validEntries" type="number">
    Entries that passed all filters.
  </ResponseField>

  <ResponseField name="createdAt" type="string">
    ISO 8601 creation timestamp.
  </ResponseField>

  <ResponseField name="drawnAt" type="string">
    ISO 8601 timestamp of when Xquik selected winners. Present only for completed draws.
  </ResponseField>
</ResponseField>

<ResponseField name="winners" type="array">
  Selected winners and backup winners ordered by position.
  **Winner object fields.**

  <ResponseField name="position" type="number">
    Winner position (1-indexed).
  </ResponseField>

  <ResponseField name="authorUsername" type="string">
    X username of the winner.
  </ResponseField>

  <ResponseField name="tweetId" type="string">
    Tweet ID of the winning reply.
  </ResponseField>

  <ResponseField name="isBackup" type="boolean">
    `true` if this is a backup winner.
  </ResponseField>
</ResponseField>

```json theme={null}
{
  "draw": {
    "id": "f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345",
    "tweetId": "1893456789012345678",
    "tweetUrl": "https://x.com/xquik/status/1893456789012345678",
    "tweetText": "Giveaway time! Reply to enter. 3 winners get a free month of Xquik Pro.",
    "tweetAuthorUsername": "xquik",
    "tweetLikeCount": 2450,
    "tweetRetweetCount": 1820,
    "tweetReplyCount": 847,
    "tweetQuoteCount": 95,
    "status": "completed",
    "totalEntries": 847,
    "validEntries": 312,
    "createdAt": "2026-02-24T10:00:00.000Z",
    "drawnAt": "2026-02-24T10:05:00.000Z"
  },
  "winners": [
    {
      "position": 1,
      "authorUsername": "alice_web3",
      "tweetId": "1893456789012345700",
      "isBackup": false
    },
    {
      "position": 2,
      "authorUsername": "bob_dev",
      "tweetId": "1893456789012345701",
      "isBackup": false
    },
    {
      "position": 3,
      "authorUsername": "charlie_nft",
      "tweetId": "1893456789012345702",
      "isBackup": false
    }
  ]
}
```

### 401 Unauthenticated

```json theme={null}
{ "error": "unauthenticated" }
```

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

### 404 Not found

```json theme={null}
{ "error": "not_found" }
```

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

### 429 Rate limited

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

Too many requests. Wait for the `Retry-After` header before retrying.

## Handle giveaway draw responses

<CardGroup cols={2}>
  <Card title="200 Draw result" icon="circle-check">
    Read `draw` and `winners`. Split primary and backup winners before handoff.
  </Card>

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

  <Card title="404 Draw missing" icon="search-x">
    No accessible draw matches that ID. Check its account and exact value.
  </Card>

  <Card title="429 Rate limit" icon="timer">
    Too many requests. Honor `Retry-After`, then retry the same draw ID.
  </Card>
</CardGroup>

## 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}`. Keep 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. The current credential cannot
read another account's draw.

### Does winner verification consume credits?

No. Retrieving an existing draw is free. Running a new draw can consume
credits.

<Note>
  **Related.** [Export Draw](/api-reference/draws/export) downloads results.
  [Giveaway History](/api-reference/draws/twitter-giveaway-history) lists past
  draws. [Create Draw](/api-reference/draws/create) runs a new selection.
</Note>


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