---
title: "Run giveaway draw"
method: POST
path: "/draws"
tags: ["Draws"]
---

# Run giveaway draw

`POST /draws`

Runs a giveaway draw from a source tweet. The draw first checks the minimum credits needed to inspect the source tweet and at least one candidate. Remaining credits cap how many replies and retweeters can be inspected before filters and winner selection run.

## Request body

- object
  - `tweetUrl` string, uri, required
  - `winnerCount` integer
  - `backupCount` integer
  - `uniqueAuthorsOnly` boolean
  - `mustRetweet` boolean
  - `mustFollowUsername` string
  - `filterMinFollowers` integer
  - `filterAccountAgeDays` integer
  - `filterLanguage` string
  - `requiredHashtags` string[]
  - `requiredKeywords` string[]
  - `requiredMentions` string[]

## Response `201`

Draw completed

- object
  - `id` string, required
  - `tweetId` string, required
  - `totalEntries` integer, required — Candidate entries inspected for this draw after the credit-derived cap. This may be lower than the source tweet's full reply count.
  - `validEntries` integer, required — Entries from the inspected candidate set that passed all filters. This is not necessarily every valid reply on the source tweet when credits cap inspection.
  - `winners` Winner[], required
    - `authorUsername` string, required
    - `tweetId` string, required
    - `position` integer, required
    - `isBackup` boolean, required

## Other responses

- `400` — Invalid input
- `401` — Unauthenticated
- `402` — Insufficient usable credits. Draws can fail before execution when the available balance cannot cover the minimum draw cost. A draw can also fail after execution when its final computed cost cannot be deducted.
- `404` — Not found
- `424` — Dependency unavailable, unauthorized, or rate limited. Default v1 returns 502. The best-practice response contract returns 424 for transparent dependency failures.
- `429` — Xquik tier rate limit exceeded. The response includes a `Retry-After` header with the number of seconds to wait before retrying.
- `502` — Dependency unavailable, unauthorized, or rate limited. Default v1 returns 502. The best-practice response contract returns 424 for transparent dependency failures.

---

[API](https://skmtc.net/xquik-dev/apis/xquik-api-3.md) · [All operations](https://skmtc.net/xquik-dev/apis/xquik-api-3/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/xquik-dev/xquik-api-3/revisions/4839804dc9da/schema)