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

# X API workflows for tweets, followers & webhooks

> Choose workflows for tweet lookup, search, follower export, profile monitors, signed webhooks, MCP agents, file exports, or DMs. Includes exact API steps.

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

Choose a workflow for dashboards, webhooks, agents, exports, or content. Open its API examples. Run the [API checklist](/guides/x-api-integration-checklist) before launch.

<CardGroup cols={2}>
  <Card title="Monitor & poll" icon="radio">
    Batch processing, dashboards, and low-frequency checks. Interval-based, low setup effort.
  </Card>

  <Card title="Signed monitor webhooks" icon="bell">
    Alerts, queues, support triage, and warehouse sync. Medium setup effort.
  </Card>

  <Card title="AI agent (MCP)" icon="bot">
    Tweet search, user lookups, follower checks, and research summaries. Low setup effort.
  </Card>

  <Card title="Publish tweet or reply" icon="send">
    Post tweets, post tweet replies, and hand off public media URLs. Low setup effort.
  </Card>

  <Card title="Tweet composition" icon="pen-line">
    Draft generation and reply monitoring. Low setup effort.
  </Card>
</CardGroup>

## Choose a workflow

<CardGroup cols={2}>
  <Card title="Track competitor or brand posts" icon="radar">
    Use monitor polling or webhooks. Returns: tweets, replies, quotes, and retweets.
  </Card>

  <Card title="Send monitor alerts" icon="bell-ring">
    Use signed webhooks. They deliver event payloads to queues or support tools.
  </Card>

  <Card title="Build an AI research assistant" icon="bot">
    Use the MCP path. Returns: tweet search results, user profiles, and monitor events.
  </Card>

  <Card title="Export followers or audiences" icon="users">
    Use extraction workflows. Returns: CSV, JSON, XLSX, or paginated JSON.
  </Card>

  <Card title="Sync followers to CRM" icon="database">
    Use the follower export CRM workflow. Returns: CSV, XLSX, JSON, and a CRM field map.
  </Card>

  <Card title="Post a tweet or reply" icon="send">
    Use the create tweet workflow. Returns: published `tweetId`, `success`, `charged`, and `chargedCredits`.
  </Card>

  <Card title="Score and refine a draft tweet" icon="sparkles">
    Use tweet composition. Returns: algorithm guidance, refined text, and score.
  </Card>

  <Card title="Audit giveaway activity" icon="trophy">
    Use draws. Returns: eligible participants, winners, and archived tweet metrics.
  </Card>
</CardGroup>

## Use-case endpoint finder

Start here when a user asks which Xquik endpoint to call. Pick the matching
job, then open the API page for params, responses, and examples.

* **One tweet by ID.** `GET /x/tweets/{id}`. Handoff: tweet row with media and metrics.
* **Many known tweet IDs.** `GET /x/tweets`. Handoff: Batch response before single-tweet loops.
* **Keyword or advanced search.** `GET /x/tweets/search`. Handoff: cursor pages, or `tweet_search_extractor` exports.
* **Profile timeline.** `GET /x/users/{id}/tweets`. Handoff: `cursor`, `includeReplies`, and `includeParentTweet`.
* **Article body.** `GET /x/articles/{tweetId}`. Handoff: body blocks, cover image, author, and not-found handling.
* **Replies, quotes, or threads.** `GET /x/tweets/{id}/replies`. Handoff: Conversation rows from replies, quotes, or threads.
* **Follower or following page.** `GET /x/users/{id}/followers` or `GET /x/users/{id}/following`. Handoff: `users`, `has_next_page`, and `next_cursor`.
* **Follower or following export.** `POST /extractions/estimate`. Handoff: `follower_explorer` or `following_explorer` estimate, job, CSV, JSON, or XLSX.
* **Campaign verification.** `GET /x/followers/check`, retweeters, replies, quotes, or draws. Handoff: proof exports.
* **Post tweet or reply.** `POST /x/tweets`. Handoff: `tweetId`, write status, credits, and public media URLs.
* **Direct messages.** `GET /x/dm/{userId}/history`. Handoff: history, cursor state, outbound `messageId`, and success.
* **1-second monitoring.** `POST /monitors` or `POST /monitors/keywords`. Handoff: Signed payloads and delivery IDs.
* **AI agent handoff.** `xquik.request(...)`. Handoff: normalized Xquik API results for MCP clients.
* **Saved file exports.** `GET /extractions/{id}/export`. Handoff: CSV, JSON, XLSX, Markdown, PDF, or TXT.

## Integration handoff matrix

Use this matrix before choosing code, webhooks, MCP, or exports.

<AccordionGroup>
  <Accordion title="Competitor or brand monitoring">
    Setup: API key, account username or keyword query, and event types.
    First call: `POST /monitors` for accounts or `POST /monitors/keywords` for search queries, then `GET /events`.
    Returns: tweet, reply, quote, and retweet events.
    Handoff: polling cursor or signed webhook payload.
    Cost: active monitors bill 21 credits per hour while enabled.
  </Accordion>

  <Accordion title="Monitor alert routing">
    Setup: webhook URL and subscribed event types.
    First call: `POST /webhooks`, then `POST /webhooks/{id}/test`.
    Returns: delivery status and signed event body.
    Handoff: queue, Slack, CRM, or warehouse endpoint.
    Cost: active monitor billing includes webhook management and deliveries.
  </Accordion>

  <Accordion title="AI research agent">
    Setup: MCP API key or OAuth.
    First call: `xquik.request('/api/v1/x/tweets/search')`.
    Returns: tweets, profiles, and monitor events.
    Handoff: MCP tool result with normalized pagination.
    Cost: Tweet search, profile lookup, and follower exports use endpoint credits.
  </Accordion>

  <Accordion title="Audience export handoff">
    Setup: target username, `follower_explorer` or `following_explorer`, and optional `resultsLimit`.
    First call: `POST /extractions/estimate`, then `POST /extractions`.
    Returns: job status, rows, and export links.
    Handoff: CSV, JSON, XLSX, or paginated JSON.
    Cost: estimate before creating the job.
  </Accordion>

  <Accordion title="Tweet replies export">
    Setup: tweet ID and optional `resultsLimit`.
    First call: `POST /extractions/estimate` with `reply_extractor`.
    Returns: reply author fields, reply tweet fields, engagement counts, and metadata.
    Handoff: CSV, JSON, XLSX, JSONL, or moderation queue rows.
    Cost: 1 credit per reply returned or extracted.
  </Accordion>

  <Accordion title="Post tweets or replies">
    Setup: connected X account plus text, media URLs, or parent tweet ID.
    First call: `POST /x/tweets`.
    Returns: `tweetId`, `success`, `charged`, and `chargedCredits`.
    Handoff: published tweet ID and charged credits for queue, CRM, CMS, or agent state.
    Cost: 30 credits text-only, plus 2 credits per started MB across attached media.
  </Accordion>

  <Accordion title="Tweet draft workflow">
    Setup: topic, goal, tone, and optional style username.
    First call: `POST /compose` with `step`.
    Returns: algorithm guidance, refined draft, and score checklist.
    Handoff: draft text or X compose URL.
    Cost: Compose, refine, and score are free.
  </Accordion>
</AccordionGroup>

## High-value workflows first

Prioritize rows for analysts, IDs for systems of record, events for queues, and published action IDs for audit trails.

<CardGroup cols={2}>
  <Card title="1. Scrape tweets to CSV, JSON, or XLSX" icon="search">
    Turns search intent into research, lead, support, and AI retrieval rows.
    First: `POST /extractions/estimate` with `tweet_search_extractor`.
    Handoff: export file, paginated JSON, or direct `GET /x/tweets/search` page.
    Cost model: 1 credit per tweet returned or extracted.
  </Card>

  <Card title="2. Scrape tweet replies to CSV, JSON, or XLSX" icon="messages-square">
    Turns a post's conversation into moderation, support, giveaway, research, or AI rows.
    First: `POST /extractions/estimate` with `reply_extractor` and `targetTweetId`.
    Handoff: export file, paginated JSON, JSONL rows, or direct `GET /x/tweets/{id}/replies` page.
    Cost model: 1 credit per reply returned or extracted.
  </Card>

  <Card title="3. Export followers or following to CRM" icon="users">
    Builds audience and interest tables with stable X user IDs for import and upsert.
    First: `POST /extractions/estimate` with `follower_explorer` or `following_explorer`.
    Handoff: CSV, JSON, XLSX, or CRM field map keyed by `x_user_id`.
    Cost model: 1 credit per user returned.
  </Card>

  <Card title="4. Monitor tweets to signed webhooks" icon="radio">
    Delivers new posts, replies, quotes, and retweets to queues without polling.
    First: `POST /monitors` for accounts or `POST /monitors/keywords` for search queries, then `POST /webhooks`.
    Handoff: signed payload with `deliveryId`, `streamEventId`, `eventType`, and tweet data.
    Cost model: 21 credits per active monitor-hour. The rate includes webhook delivery.
  </Card>

  <Card title="5. Post media tweets or replies" icon="image">
    Publishes media tweets or replies from public image URLs or 1 public MP4 URL up to 100 MB.
    First: `POST /x/tweets` with `media`.
    Handoff: `tweetId`, `success`, `chargedCredits`, original `media` URLs, and optional `reply_to_tweet_id`.
    Cost model: 30 credits text-only, plus 2 credits per started MB across attached media.
  </Card>

  <Card title="6. Send direct messages with returned IDs" icon="send">
    Lets support, sales, and agents store the outbound message ID.
    First: `GET /x/users/{id}` if needed. Use `GET /x/dm/{userId}/history?account=...`, then `POST /x/dm/{userId}`.
    Handoff: `account`, `messages`, `has_next_page`, `next_cursor`, `messageId`, and `success`.
    Cost model: 1 credit per user lookup or history message. 10 credits per DM send.
  </Card>
</CardGroup>

### 1. Scrape tweets to CSV, JSON, or XLSX

Use this to scrape tweets, search tweets, export hashtag results, or hand matching posts to analysts. Estimate first, create the job, poll it, then export the format your system expects. For reply-specific exports, use the next workflow.

```bash theme={null}
curl -X POST https://xquik.com/api/v1/extractions/estimate \
  -H "x-api-key: xq_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "toolType": "tweet_search_extractor",
    "searchQuery": "from:username webhook OR SDK",
    "language": "en",
    "resultsLimit": 500
  }' | jq
```

The extraction returns a job ID. `GET /extractions/{id}` returns `job`, `results`, `hasMore`, and `nextCursor`. `GET /extractions/{id}/export?format=csv` downloads the rows. For live pagination without a stored job, call `GET /x/tweets/search` with `q`. Leave `limit` unset for a simple cursor loop. For bounded pulls, keep the same `q`, filters, and `limit` while sending `next_cursor` as `cursor`. It returns `tweets`, `has_next_page`, and `next_cursor`.

### 2. Scrape tweet replies to CSV, JSON, or XLSX

Use this when a moderation, support, giveaway, research, or AI review system needs every reply under a post as rows. Estimate with `reply_extractor` and `targetTweetId`, create the job, poll it, then export `format=csv`, `format=json`, or `format=xlsx`.

```bash theme={null}
curl -X POST https://xquik.com/api/v1/extractions/estimate \
  -H "x-api-key: xq_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "toolType": "reply_extractor",
    "targetTweetId": "1893704267862470862",
    "resultsLimit": 500
  }' | jq
```

`GET /extractions/{id}` returns reply rows, `hasMore`, and `nextCursor`. Pass `nextCursor` as `cursor` for more stored results. For live pagination without a stored job, call `GET /x/tweets/{id}/replies`, pass `next_cursor` back as `cursor`, and store `tweets`, `has_next_page`, and `next_cursor`.

### 3. Export followers or following to CRM

Use this for follower export, following export, audience ownership, CRM import, or warehouse sync. Keep `resultsLimit` on estimate and create calls for a predictable credit cap.

```bash theme={null}
curl -X POST https://xquik.com/api/v1/extractions \
  -H "x-api-key: xq_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "toolType": "follower_explorer",
    "targetUsername": "username",
    "resultsLimit": 10000
  }' | jq
```

Use `following_explorer` with the same `targetUsername` shape when the job needs accounts the user follows. After `status` becomes `completed`, export `format=csv`, `format=xlsx`, or `format=json`. Map stable `User ID` values to `x_user_id`. Do not key imports by display name.

### 4. Monitor tweets to signed webhooks

Use this when a workflow needs account alerts, keyword alerts, support routing, warehouse ingest, or queue fanout within seconds. Create an account monitor or keyword monitor, register the webhook URL, test delivery, then process signed events asynchronously.

```bash theme={null}
curl -X POST https://xquik.com/api/v1/monitors \
  -H "x-api-key: xq_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "username",
    "eventTypes": ["tweet.new", "tweet.reply", "tweet.quote"]
  }' | jq
```

For query alerts, call `POST /monitors/keywords` with `query` and `eventTypes` instead of `username`. Account and keyword monitors both check every 1 second while active. Both can deliver events to the same signed webhooks.

Each POST has 1 event. Multiple matches produce multiple POSTs.

Payloads include durable IDs. Store `deliveryId` for delivery-level idempotency. Store `streamEventId` when you must process the same monitor event once across retries or endpoints. Store the one-time `secret` returned by `POST /webhooks`. Verify `X-Xquik-Signature` against the raw body before accepting the event. Return `2xx` before slow CRM, Slack, warehouse, or queue work starts.

#### Receiver storage handoff

For Zapier, Make, and Pipedream receivers, map production payload IDs before enqueueing slow work:

```json theme={null}
{
  "record_type": "workflow_webhook_receiver_parity",
  "delivery_id": "502",
  "stream_event_id": "9002",
  "event_type": "tweet.new",
  "occurred_at": "2026-02-24T14:22:00.000Z",
  "duplicate_delivery_status": "2xx",
  "duplicate_event_status": "2xx",
  "event_join": "GET /api/v1/events/9002",
  "shared_storage_excludes": [
    "endpoint_signing_values",
    "raw_request_body",
    "raw_signature",
    "full_headers"
  ]
}
```

Return `2xx` for duplicate `deliveryId` or `streamEventId` after signature verification. Store raw request bytes only long enough to verify `X-Xquik-Signature`. Do not put endpoint signing values, raw body, raw signature, or full headers in shared workflow rows.

### 5. Post media tweets or replies

Use this when an agent or app has public image URLs or exactly 1 public MP4 video URL up to 100 MB and needs to post a tweet or reply. Pass those URLs directly in the `media` array on `POST /x/tweets`. Do not call `POST /x/media` first for tweet posts when the media is already public. `POST /x/tweets` rejects `media_ids` with `400 unsupported_field`.

```bash theme={null}
curl -X POST https://xquik.com/api/v1/x/tweets \
  -H "x-api-key: xq_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "brand_account",
    "text": "Product screenshot from today",
    "reply_to_tweet_id": "1893456789012345678",
    "media": ["https://example.com/product-screenshot.png"]
  }' | jq
```

The response is a durable action record. Store `id`, `status`, `billing`, `result`, `request.hash`, and `statusUrl`. Poll while `terminal` is false. Retry only when `safeToRetry` is true, using a new `Idempotency-Key`. Store media URLs with the action record. Text-only tweet or reply writes cost 30 credits. Attached media adds 2 credits per started MB across all files. Use `POST /x/media` only when you need a one-item `media_ids` array for [`POST /x/dm/{userId}`](/api-reference/x-write/send-dm).

### 6. Send direct messages with returned IDs

Use this when a support, sales, or agent workflow needs direct messages with audit trails. Look up the recipient user ID. Pass the same connected sender as `account` for history reads and DM writes. Then store returned message IDs.

```bash theme={null}
curl -G https://xquik.com/api/v1/x/dm/987654321/history \
  --data-urlencode "account=brand_account" \
  -H "x-api-key: xq_YOUR_KEY_HERE" | jq
```

History reads require `account`. That connected account must participate in the conversation. Missing `account` returns `400 account_required`. A non-participant account returns `403 dm_not_permitted`.

```bash theme={null}
curl -X POST https://xquik.com/api/v1/x/dm/987654321 \
  -H "x-api-key: xq_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "brand_account",
    "text": "Thanks for reaching out. Here is the next step."
  }' | jq
```

`GET /x/dm/{userId}/history` returns `messages`, `has_next_page`, and `next_cursor`. Pass `next_cursor` back as `cursor` for older messages. `POST /x/dm/{userId}` returns `messageId` and `success`. Store both on the support ticket, CRM note, or agent state.

## Focused workflow pages

Choose a path, then open its examples, SDK guidance, and error recovery.

<CardGroup cols={2}>
  <Card title="Tweet search exports" icon="search" href="/guides/tweet-scraper-csv-export">
    Build CSV, JSON, or XLSX exports from `tweet_search_extractor`, or use direct `GET /x/tweets/search` pagination.
  </Card>

  <Card title="Tweet replies exports" icon="messages-square" href="/guides/tweet-replies-export">
    Turn a post conversation into `reply_extractor` jobs, direct replies pagination, JSONL rows, or moderation queues.
  </Card>

  <Card title="Follower CRM export" icon="users" href="/guides/follower-export-crm">
    Estimate `follower_explorer`, export CSV, JSON, or XLSX files, and map stable `x_user_id` fields.
  </Card>

  <Card title="Campaign verification" icon="badge-check" href="/guides/campaign-verification-workflow">
    Check social actions and draw exports.
  </Card>

  <Card title="Monitor webhooks" icon="webhook" href="/guides/twitter-webhook-testing">
    Test signed deliveries, verify `X-Xquik-Signature`, store `deliveryId` and `streamEventId`, and return `2xx` before slow work.
  </Card>

  <Card title="Media tweets and DMs" icon="image" href="/guides/media-upload-workflow">
    Use public URLs in tweet `media`. Upload only when DMs need one `media_ids` item.
  </Card>

  <Card title="Direct messages" icon="send" href="/guides/direct-message-workflow">
    Read DM history with `account`, send DMs, and store returned `messageId` values.
  </Card>

  <Card title="MCP agents" icon="bot" href="/mcp/overview">
    Connect agents, call `xquik.request(...)`, and hand normalized pagination back to memory.
  </Card>

  <Card title="Tweet composition" icon="pen-line" href="/api-reference/compose/create">
    Use `POST /compose` for compose, refine, and score loops without usage credits.
  </Card>
</CardGroup>

## Public draw results

Completed giveaway draws have a public results page at `https://xquik.com/results/{drawId}`. The page needs no authentication. Share the URL with participants for transparency.

<CardGroup cols={2}>
  <Card title="Create a monitor" icon="radar" href="/api-reference/monitors/create">
    Start 1-second checks for one account.
  </Card>

  <Card title="Register a webhook" icon="webhook" href="/api-reference/webhooks/create">
    Receive detected events through signed webhooks.
  </Card>

  <Card title="MCP server" icon="bot" href="/mcp/overview">
    Connection details and setup instructions.
  </Card>

  <Card title="Signature verification" icon="shield-check" href="/webhooks/verification">
    Verify webhook payloads with HMAC-SHA256.
  </Card>
</CardGroup>


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