Twitter giveaway picker API & random winner draw

{
  "id": "f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345",
  "tweetId": "1234567890",
  "totalEntries": 250,
  "validEntries": 200,
  "winners": []
}

{
  "error": "invalid_input",
  "message": "Invalid input. Check the request body."
}

{
  "error": "unauthenticated",
  "message": "Authentication required. Provide a valid API key or bearer token."
}

{
  "error": "insufficient_credits",
  "message": "Insufficient credits"
}

{
  "error": "not_found",
  "message": "Resource not found."
}

{
  "error": "x_api_unavailable",
  "message": "X data source temporarily unavailable. Try again later."
}

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Try again later.",
  "retryAfter": 60
}

{
  "error": "x_api_unavailable",
  "message": "X data source temporarily unavailable. Try again later."
}

POST

draws

Twitter giveaway picker API & random winner draw

curl --request POST \
  --url https://xquik.com/api/v1/draws \
  --header 'Content-Type: <content-type>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "tweetUrl": "<string>",
  "winnerCount": 123,
  "backupCount": 123,
  "uniqueAuthorsOnly": true,
  "mustRetweet": true,
  "mustFollowUsername": "<string>",
  "filterMinFollowers": 123,
  "filterAccountAgeDays": 123,
  "filterLanguage": "<string>",
  "requiredKeywords": [
    "<string>"
  ],
  "requiredHashtags": [
    "<string>"
  ],
  "requiredMentions": [
    "<string>"
  ]
}
'

import requests

url = "https://xquik.com/api/v1/draws"

payload = {
    "tweetUrl": "<string>",
    "winnerCount": 123,
    "backupCount": 123,
    "uniqueAuthorsOnly": True,
    "mustRetweet": True,
    "mustFollowUsername": "<string>",
    "filterMinFollowers": 123,
    "filterAccountAgeDays": 123,
    "filterLanguage": "<string>",
    "requiredKeywords": ["<string>"],
    "requiredHashtags": ["<string>"],
    "requiredMentions": ["<string>"]
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': '<content-type>'},
  body: JSON.stringify({
    tweetUrl: '<string>',
    winnerCount: 123,
    backupCount: 123,
    uniqueAuthorsOnly: true,
    mustRetweet: true,
    mustFollowUsername: '<string>',
    filterMinFollowers: 123,
    filterAccountAgeDays: 123,
    filterLanguage: '<string>',
    requiredKeywords: ['<string>'],
    requiredHashtags: ['<string>'],
    requiredMentions: ['<string>']
  })
};

fetch('https://xquik.com/api/v1/draws', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

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

func main() {

	url := "https://xquik.com/api/v1/draws"

	payload := strings.NewReader("{\n  \"tweetUrl\": \"<string>\",\n  \"winnerCount\": 123,\n  \"backupCount\": 123,\n  \"uniqueAuthorsOnly\": true,\n  \"mustRetweet\": true,\n  \"mustFollowUsername\": \"<string>\",\n  \"filterMinFollowers\": 123,\n  \"filterAccountAgeDays\": 123,\n  \"filterLanguage\": \"<string>\",\n  \"requiredKeywords\": [\n    \"<string>\"\n  ],\n  \"requiredHashtags\": [\n    \"<string>\"\n  ],\n  \"requiredMentions\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "<content-type>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "id": "<string>",
  "tweetId": "<string>",
  "totalEntries": 123,
  "validEntries": 123,
  "winners": [
    {}
  ]
}

Use this Twitter giveaway picker API to select primary and backup winners. Filter replies by reposts, follows, keywords, hashtags, mentions, or language. Add account-age, follower-count, or unique-author rules.

Metered draw execution · source lookup, replies, optional retweeters, and optional follow checks consume credits

Remaining credits cap how many replies and retweeters Xquik can inspect before filters run. totalEntries and validEntries describe that inspected candidate set, not necessarily every reply on the source tweet.

curl -X POST https://xquik.com/api/v1/draws \
  -H "x-api-key: xq_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "tweetUrl": "https://x.com/xquik/status/1893456789012345678",
    "winnerCount": 3,
    "backupCount": 2,
    "mustRetweet": true,
    "filterMinFollowers": 10,
    "requiredKeywords": ["giveaway"]
  }' | jq

const response = await fetch("https://xquik.com/api/v1/draws", {
  method: "POST",
  headers: {
    "x-api-key": "xq_YOUR_KEY_HERE",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    tweetUrl: "https://x.com/xquik/status/1893456789012345678",
    winnerCount: 3,
    backupCount: 2,
    mustRetweet: true,
    filterMinFollowers: 10,
    requiredKeywords: ["giveaway"],
  }),
});
const data = await response.json();
console.log(data);

import requests

response = requests.post(
    "https://xquik.com/api/v1/draws",
    headers={"x-api-key": "xq_YOUR_KEY_HERE"},
    json={
        "tweetUrl": "https://x.com/xquik/status/1893456789012345678",
        "winnerCount": 3,
        "backupCount": 2,
        "mustRetweet": True,
        "filterMinFollowers": 10,
        "requiredKeywords": ["giveaway"],
    },
)
data = response.json()
print(data)

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"log"
	"net/http"
)

func main() {
	payload := map[string]interface{}{
		"tweetUrl":           "https://x.com/xquik/status/1893456789012345678",
		"winnerCount":        3,
		"backupCount":        2,
		"mustRetweet":        true,
		"filterMinFollowers": 10,
		"requiredKeywords":   []string{"giveaway"},
	}
	body, err := json.Marshal(payload)
	if err != nil {
		log.Fatal(err)
	}

	req, err := http.NewRequest("POST", "https://xquik.com/api/v1/draws", bytes.NewReader(body))
	if err != nil {
		log.Fatal(err)
	}
	req.Header.Set("x-api-key", "xq_YOUR_KEY_HERE")
	req.Header.Set("Content-Type", "application/json")

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

	respBody, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(string(respBody))
}

Giveaway draw column	Request or response source	Audit rule
Draw ID	Response `id`	Use this public ID for review and export.
Source tweet	Response `tweetId`	Preserve the giveaway tweet identifier.
Inspected entries	Response `totalEntries`	Record the credit-bounded candidate count.
Eligible entries	Response `validEntries`	Compare this count with every filter.
Winner order	`winners[].position`	Preserve the original selection order.
Winner username	`winners[].authorUsername`	Store the selected X account.
Winning reply	`winners[].tweetId`	Retain the qualifying reply identifier.
Backup state	`winners[].isBackup`	Separate primary and backup winners.

Headers

string

required

Your API key. Session cookie authentication is also supported.

string

required

Must be application/json.

Body

string

required

Full tweet URL to run the draw on. Accepts x.com and twitter.com formats (e.g. https://x.com/user/status/1893456789012345678).

number

Number of winners to draw. Defaults to 1 if omitted.

number

Number of backup winners to draw. Backup winners are selected in case primary winners are disqualified.

boolean

When true, each author can only win once regardless of how many replies they posted.

boolean

When true, only entries from users who retweeted the original tweet are eligible.

string

X username that entrants must follow to be eligible. The @ prefix is stripped if included.

number

Minimum follower count required for eligible entries.

number

Minimum account age in days. Accounts younger than this are excluded.

string

Filter entries by tweet language code (e.g. en, tr, es).

string[]

Array of keywords that must appear in the reply text. Entries missing any keyword are excluded.

string[]

Array of hashtags that must appear in the reply text. Include the # prefix.

string[]

Array of usernames that must be mentioned in the reply text. Include the @ prefix.

Response

201 Created

string

Draw public ID returned by Xquik.

string

X tweet ID extracted from the URL.

number

Candidate entries inspected for this draw after the credit-derived cap. This may be lower than the source tweet’s full reply count.

number

Entries from the inspected candidate set that passed all filters.

array

Selected winners and backup winners. Winner object fields.

number

Winner position (1-indexed).

string

X username of the winner.

string

Tweet ID of the winning reply.

boolean

true if this is a backup winner.

{
  "id": "f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345",
  "tweetId": "1893456789012345678",
  "totalEntries": 847,
  "validEntries": 312,
  "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
    },
    {
      "position": 4,
      "authorUsername": "diana_crypto",
      "tweetId": "1893456789012345703",
      "isBackup": true
    },
    {
      "position": 5,
      "authorUsername": "eve_trades",
      "tweetId": "1893456789012345704",
      "isBackup": true
    }
  ]
}

400 Invalid input

{ "error": "invalid_input", "message": "Missing or malformed request body" }

Missing or malformed request body. Ensure tweetUrl is a string.

400 Invalid tweet URL

{ "error": "invalid_tweet_url", "message": "Invalid tweet URL format" }

The tweetUrl could not be parsed. Must be a valid x.com or twitter.com status URL.

401 Unauthenticated

{ "error": "unauthenticated", "message": "Missing or invalid API key" }

Missing or invalid API key / session cookie.

402 Insufficient credits

{ "error": "insufficient_credits", "message": "Insufficient credits. Top up or subscribe to continue." }

The available balance cannot cover the minimum draw cost. A later final deduction failure also returns insufficient_credits. No draw result is persisted after that failure. Check your credit balance.

404 Not found

{ "error": "tweet_not_found", "message": "Tweet not found" }

The target tweet does not exist, was deleted, or the ID is invalid.

424 X API dependency failed

{
  "error": {
    "type": "dependency_error",
    "code": "x_api_unavailable",
    "message": "X data source temporarily unavailable"
  }
}

Send xquik-api-contract: 2026-04-29 to receive this status for dependency failures that return 502 by default.

429 Rate limited

{ "error": "rate_limit_exceeded", "message": "Too many requests. Try again later.", "retryAfter": 1 }

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

502 X API unavailable

{ "error": "x_api_unavailable", "message": "X data source temporarily unavailable" }

The read service returned an error. Retry after a short delay.

Next steps. Get Draw to retrieve full draw details including tweet metadata, Export Draw to download results as CSV/XLSX/Markdown, or List Draws to see your draw history.

{
  "id": "f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345",
  "tweetId": "1234567890",
  "totalEntries": 250,
  "validEntries": 200,
  "winners": []
}

{
  "error": "invalid_input",
  "message": "Invalid input. Check the request body."
}

{
  "error": "unauthenticated",
  "message": "Authentication required. Provide a valid API key or bearer token."
}

{
  "error": "insufficient_credits",
  "message": "Insufficient credits"
}

{
  "error": "not_found",
  "message": "Resource not found."
}

{
  "error": "x_api_unavailable",
  "message": "X data source temporarily unavailable. Try again later."
}

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Try again later.",
  "retryAfter": 60
}

{
  "error": "x_api_unavailable",
  "message": "X data source temporarily unavailable. Try again later."
}

Twitter giveaway picker API & random winner draw

curl --request POST \
  --url https://xquik.com/api/v1/draws \
  --header 'Content-Type: <content-type>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "tweetUrl": "<string>",
  "winnerCount": 123,
  "backupCount": 123,
  "uniqueAuthorsOnly": true,
  "mustRetweet": true,
  "mustFollowUsername": "<string>",
  "filterMinFollowers": 123,
  "filterAccountAgeDays": 123,
  "filterLanguage": "<string>",
  "requiredKeywords": [
    "<string>"
  ],
  "requiredHashtags": [
    "<string>"
  ],
  "requiredMentions": [
    "<string>"
  ]
}
'

import requests

url = "https://xquik.com/api/v1/draws"

payload = {
    "tweetUrl": "<string>",
    "winnerCount": 123,
    "backupCount": 123,
    "uniqueAuthorsOnly": True,
    "mustRetweet": True,
    "mustFollowUsername": "<string>",
    "filterMinFollowers": 123,
    "filterAccountAgeDays": 123,
    "filterLanguage": "<string>",
    "requiredKeywords": ["<string>"],
    "requiredHashtags": ["<string>"],
    "requiredMentions": ["<string>"]
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': '<content-type>'},
  body: JSON.stringify({
    tweetUrl: '<string>',
    winnerCount: 123,
    backupCount: 123,
    uniqueAuthorsOnly: true,
    mustRetweet: true,
    mustFollowUsername: '<string>',
    filterMinFollowers: 123,
    filterAccountAgeDays: 123,
    filterLanguage: '<string>',
    requiredKeywords: ['<string>'],
    requiredHashtags: ['<string>'],
    requiredMentions: ['<string>']
  })
};

fetch('https://xquik.com/api/v1/draws', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

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

func main() {

	url := "https://xquik.com/api/v1/draws"

	payload := strings.NewReader("{\n  \"tweetUrl\": \"<string>\",\n  \"winnerCount\": 123,\n  \"backupCount\": 123,\n  \"uniqueAuthorsOnly\": true,\n  \"mustRetweet\": true,\n  \"mustFollowUsername\": \"<string>\",\n  \"filterMinFollowers\": 123,\n  \"filterAccountAgeDays\": 123,\n  \"filterLanguage\": \"<string>\",\n  \"requiredKeywords\": [\n    \"<string>\"\n  ],\n  \"requiredHashtags\": [\n    \"<string>\"\n  ],\n  \"requiredMentions\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "<content-type>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "id": "<string>",
  "tweetId": "<string>",
  "totalEntries": 123,
  "validEntries": 123,
  "winners": [
    {}
  ]
}

Overview

X API

X write

Trends

Radar

Account

API keys

Guest wallets

Credits

X accounts

Monitors

Events

Webhooks

Draws

Extractions

Compose

Drafts

Styles

Support

Twitter giveaway picker API & random winner draw

Headers

Body

Response

201 Created

400 Invalid input

400 Invalid tweet URL

401 Unauthenticated

402 Insufficient credits

404 Not found

424 X API dependency failed

429 Rate limited

502 X API unavailable

​Headers

​Body

​Response

​201 Created

​400 Invalid input

​400 Invalid tweet URL

​401 Unauthenticated

​402 Insufficient credits

​404 Not found

​424 X API dependency failed

​429 Rate limited

​502 X API unavailable

Headers

Body

Response

201 Created

400 Invalid input

400 Invalid tweet URL

401 Unauthenticated

402 Insufficient credits

404 Not found

424 X API dependency failed

429 Rate limited

502 X API unavailable