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

# List draws

> Retrieve your draw history with cursor-based pagination

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

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

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://xquik.com/api/v1/draws?limit=10" \
    -H "x-api-key: xq_YOUR_KEY_HERE" | jq
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://xquik.com/api/v1/draws?limit=10",
    {
      headers: { "x-api-key": "xq_YOUR_KEY_HERE" },
    }
  );
  const data = await response.json();
  console.log(data);
  ```

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

  response = requests.get(
      "https://xquik.com/api/v1/draws",
      headers={"x-api-key": "xq_YOUR_KEY_HERE"},
      params={"limit": 10},
  )
  data = response.json()
  print(data)
  ```

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

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

  func main() {
  	req, err := http.NewRequest("GET", "https://xquik.com/api/v1/draws?limit=10", 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)
  	}
  	fmt.Println(string(body))
  }
  ```
</CodeGroup>

## Query parameters

<ParamField query="limit" type="number">
  Results per page. Default `50`, max `100`.
</ParamField>

<ParamField query="after" type="string">
  Cursor for pagination. Pass the `nextCursor` value from a previous response to fetch the next page.
</ParamField>

## Headers

<ParamField header="x-api-key" type="string" required>
  Your API key. This endpoint also accepts session cookie authentication.
</ParamField>

## Response

<Tabs>
  <Tab title="200 OK">
    <ResponseField name="draws" type="array">
      List of draw objects ordered by creation date (newest first).

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

        <ResponseField name="tweetUrl" type="string">
          Original tweet URL used for the draw.
        </ResponseField>

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

        <ResponseField name="totalEntries" type="number">
          Total replies collected from the tweet.
        </ResponseField>

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

        <ResponseField name="createdAt" type="string">
          ISO 8601 timestamp of when the draw was created.
        </ResponseField>

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

    <ResponseField name="hasMore" type="boolean">
      `true` if additional pages exist beyond this result set.
    </ResponseField>

    <ResponseField name="nextCursor" type="string">
      Pagination cursor. Pass as the `after` query parameter to fetch the next page. Present only when `hasMore` is `true`.
    </ResponseField>

    ```json theme={null}
    {
      "draws": [
        {
          "id": "f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345",
          "tweetUrl": "https://x.com/xquik/status/1893456789012345678",
          "status": "completed",
          "totalEntries": 847,
          "validEntries": 312,
          "createdAt": "2026-02-24T10:00:00.000Z",
          "drawnAt": "2026-02-24T10:05:00.000Z"
        },
        {
          "id": "9a78ce15-2f3d-4f90-a86b-1049c7a26e92",
          "tweetUrl": "https://x.com/xquik/status/1893456789012340000",
          "status": "completed",
          "totalEntries": 1240,
          "validEntries": 980,
          "createdAt": "2026-02-23T16:30:00.000Z",
          "drawnAt": "2026-02-23T16:35:00.000Z"
        }
      ],
      "hasMore": true,
      "nextCursor": "MjAyNi0wMi0yM1QxNjozMDowMC4wMDBafDY2NjY1"
    }
    ```
  </Tab>

  <Tab title="401 Unauthenticated">
    ```json theme={null}
    { "error": "unauthenticated" }
    ```

    Missing or invalid API key / session cookie.
  </Tab>

  <Tab title="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.
  </Tab>
</Tabs>

## Pagination

Draws use **cursor-based pagination**. Each response includes `hasMore` and (when `true`) a `nextCursor` value. Pass `nextCursor` as the `after` query parameter to retrieve the next page.

<CodeGroup>
  ```bash First page theme={null}
  curl "https://xquik.com/api/v1/draws?limit=10" \
    -H "x-api-key: xq_YOUR_KEY_HERE" | jq
  ```

  ```bash Next page theme={null}
  curl "https://xquik.com/api/v1/draws?limit=10&after=MjAyNi0wMi0yM1QxNjozMDowMC4wMDBafDY2NjY1" \
    -H "x-api-key: xq_YOUR_KEY_HERE" | jq
  ```
</CodeGroup>

Continue fetching pages until `hasMore` is `false`. Cursors are opaque strings. Do not parse or construct them manually.

<Note>
  **Related:** [Get Draw](/api-reference/draws/get) to retrieve full details for a specific draw · [Create Draw](/api-reference/draws/create) to run a new giveaway draw.
</Note>