Twitter campaign verification API workflow

Use this workflow when a campaign needs one reviewable row per participant. Choose the narrowest check first. Use a draw when winners need selection. Campaign verification separates entry collection, rule checks, winner selection, and publication. Store one campaign ID across every stage. Keep source Tweet IDs, participant user IDs, filters, cursors, timestamps, and verification states. Without these checkpoints, the review cannot trace each decision.

Pick the proof path

Follow task

Use GET /api/v1/x/followers/check?source={participant}&target={brand} to check one participant and one target account.

Retweet task

Use GET /api/v1/x/tweets/{id}/retweeters to page retweeters.

Reply or quote task

Use GET /api/v1/x/tweets/{id}/replies for replies. Use GET /api/v1/x/tweets/{id}/quotes for quote posts.

Giveaway selection

Use POST /api/v1/draws for winner selection and published filters.

Translate every published participation rule into one documented check. Use follower relationships for follow rules. Use retweeter pages for repost rules. Use reply rows for keywords, hashtags, and mentions. Use quote rows when quotes define campaign participation. Store the endpoint and checked time beside each result. Never infer one campaign activity from another activity. Complete every required check before winner selection begins. A participant can pass one rule and fail another. Preserve accepted and rejected states separately. This lets an operator explain every inclusion and rejection later.

Choose the focused picker guide

Use the Twitter giveaway picker guide for random winner selection, backups, exports, and public result URLs. Use the comment and retweet picker guide for reply authors, retweeters, hashtags, cursors, and stable user IDs.

Follow check

Check one relationship at a time. Store both handles, the result, and time. A follow check proves one source-to-target relationship at one checked time. Store the source handle, target handle, stable user IDs, and response state. Repeat the same request only when the first read is uncertain. Do not treat follower counts as proof for one participant. Use separate rows when campaigns require several target accounts. This prevents one successful relationship from satisfying every follow rule.

curl "https://xquik.com/api/v1/x/followers/check?source=participant_handle&target=username" \
  -H "x-api-key: xq_YOUR_KEY_HERE" | jq

Tweet-Level checks

Use tweet endpoints when one source tweet defines campaign participation. Keep each cursor with its participant page. Retrieve every available reply, retweeter, or quote page before evaluation. Save each page before requesting the next cursor. Normalize participants to stable X user IDs. Then join required activities by that stable key. Remove duplicate authors only when published uniqueness rules require it. Keep rejection reasons for missing replies, retweets, quotes, or required text. Do not replace missing proof with displayed engagement counts.

Retweeters

GET /api/v1/x/tweets/{id}/retweeters

Replies

GET /api/v1/x/tweets/{id}/replies

Quotes

GET /api/v1/x/tweets/{id}/quotes

Page until has_next_page is false. Pass next_cursor back as cursor. Store the campaign ID with every page.

Giveaway draw

Use the Draws API when campaign rules require winner selection. Define every filter before entries close. Never add hidden rules afterward. Record the number of winners and backup winners before running a giveaway. Random selection starts only after every published check completes. Do not randomly pick from an unchecked participant list. Do not pick multiple winners by repeating uncertain create requests. Save the original draw request and returned draw ID immediately. Poll that stored draw until completion or failure. Export inspected entries and selected winners as separate records. Reconcile exported row counts with the stored request before publishing results.

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/example_user/status/1893704267862470862",
    "winnerCount": 3,
    "backupCount": 2,
    "uniqueAuthorsOnly": true,
    "mustRetweet": true,
    "mustFollowUsername": "username",
    "requiredKeywords": ["entered"]
  }' | jq

Export inspected participants with type=entries. Export selected winners with type=winners.

curl "https://xquik.com/api/v1/draws/f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345/export?format=csv&type=entries" \
  -H "x-api-key: xq_YOUR_KEY_HERE" \
  -o campaign-entries.csv

Store one audit row

Use stable user IDs as keys. Display names and handles can change. One audit row should answer who, what, when, and how. Store the participant ID, source Tweet ID, proof endpoint, cursor, and state. Add the campaign ID and checked timestamp. Keep the published rule that required the check. Preserve rejection reasons without exposing private operator notes.

{
  "campaign_id": "spring-launch-2026",
  "x_user_id": "9876543210",
  "username": "participant_handle",
  "tweet_id": "1893704267862470862",
  "proof_endpoint": "GET /api/v1/x/followers/check",
  "proof_cursor": null,
  "verification_state": "matched",
  "checked_at": "2026-05-24T19:30:00.000Z"
}

Handle costs and retries

Direct X read endpoints are metered. Budget by participants and pages.

Draw execution can meter tweet, reply, retweeter, and follow checks.

402 insufficient_credits stops the audit. Fund or narrow it first.

Repeat an uncertain read with the same tweet, filter, and cursor. Search draw history before repeating an uncertain create request. Estimate costs from participant checks and expected pagination. Persist completed pages so retries never restart the whole campaign audit. Stop on 402 insufficient_credits. Add credits or narrow the participant set. Respect 429 backoff before repeating reads. Never change campaign rules to avoid a billing or rate-limit response.

Next steps

Create draw

Run a giveaway draw with published eligibility filters.

Export draw

Export winners or all inspected entries.

Check follower

Verify one source and target relationship.

Get retweeters

Page users who retweeted one campaign tweet.

Getting started

SDKs

Guides

Webhooks

MCP server

Agent plugins

Framework guides

OAuth

MPP

Resources

Twitter campaign verification API workflow

Pick the proof path

Follow task

Retweet task

Reply or quote task

Giveaway selection

Choose the focused picker guide

Follow check

Tweet-Level checks

Retweeters

Replies

Quotes

Giveaway draw

Store one audit row

Handle costs and retries

Next steps

Create draw

Export draw

Check follower

Get retweeters

​Pick the proof path

Follow task

Retweet task

Reply or quote task

Giveaway selection

​Choose the focused picker guide

​Follow check

​Tweet-Level checks

Retweeters

Replies

Quotes

​Giveaway draw

​Store one audit row

​Handle costs and retries

​Next steps

Create draw

Export draw

Check follower

Get retweeters

Pick the proof path

Choose the focused picker guide

Follow check

Tweet-Level checks

Giveaway draw

Store one audit row

Handle costs and retries

Next steps