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

# Workflows

> X API workflow finder for tweet lookup, search, monitoring, webhooks, MCP, exports, DMs.

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

Use these X API workflows for dashboards, webhooks, agents, exports, and content. Choose the handoff here, then open the focused workflow or API page for copy-ready examples.

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

  <Card title="Real-time webhooks" icon="bell">
    Alerts, queues, customer support triage, and warehouse sync. Real-time, medium setup effort.
  </Card>

  <Card title="AI agent (MCP)" icon="bot">
    Tweet search, user lookups, follower checks, and research summaries. Real-time, 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. Returned data: tweets, replies, quotes, and retweets.
  </Card>

  <Card title="Send real-time alerts" icon="bell-ring">
    Use real-time webhooks. Returned data: signed event payloads for Slack, queues, or support tools.
  </Card>

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

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

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

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

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

  <Card title="Audit giveaway activity" icon="trophy">
    Use draws. Returned data: 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.
* **Real-time monitoring:** `POST /monitors` or `POST /monitors/keywords`. Handoff: Signed webhook 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`.
    Returned data: tweet, reply, quote, and retweet events.
    Handoff: polling cursor or signed webhook payload.
    Cost check: active instant monitors bill 21 credits per hour while enabled.
  </Accordion>

  <Accordion title="Real-time alert routing">
    Setup: webhook URL and subscribed event types.
    First call: `POST /webhooks`, then `POST /webhooks/{id}/test`.
    Returned data: delivery status and signed event body.
    Handoff: queue, Slack, CRM, or warehouse endpoint.
    Cost check: webhook management and deliveries are included with active monitor billing.
  </Accordion>

  <Accordion title="AI research agent">
    Setup: MCP client with API key or OAuth.
    First call: `xquik.request('/api/v1/x/tweets/search')`.
    Returned data: tweet search, user profiles, and monitor events.
    Handoff: MCP tool result with normalized pagination.
    Cost check: X data calls use endpoint credit costs.
  </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`.
    Returned data: job status, rows, and export links.
    Handoff: CSV, JSON, XLSX, or paginated JSON.
    Cost check: 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`.
    Returned data: reply author fields, reply tweet fields, engagement counts, and metadata.
    Handoff: CSV, JSON, XLSX, JSONL, or moderation queue rows.
    Cost check: 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`.
    Returned data: `tweetId`, `success`, `charged`, and `chargedCredits`.
    Handoff: published tweet ID and charged credits for queue, CRM, CMS, or agent state.
    Cost check: 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`.
    Returned data: algorithm guidance, refined draft, and score checklist.
    Handoff: draft text or X compose URL.
    Cost check: 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 endpoint: `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 endpoint: `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 endpoint: `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 endpoint: `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; webhook delivery is included.
  </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 endpoint: `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 endpoint: `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:xquikcom 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 `after` 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": "xquikcom",
    "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": "xquikcom",
    "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, and both can deliver events to the same signed webhooks.

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

Payloads include durable IDs: persist `deliveryId` for delivery-level idempotency and `streamEventId` when the same monitor event must be processed once across retries or endpoints. Store the one-time `secret` returned by `POST /webhooks` and 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 returns `tweetId`, `success`, `charged`, and `chargedCredits`, or `202 x_write_unconfirmed` with `writeActionId` if final confirmation is still pending. Store media URLs next to `tweetId`, `reply_to_tweet_id`, `chargedCredits`, or `writeActionId`. 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`, and 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`, which you should store on the support ticket, CRM note, or agent state.

## Focused Workflow Pages

Use the overview to choose the path, then move to the focused page for copy-ready examples, SDK handoff, and endpoint-specific error recovery.

<CardGroup cols={2}>
  <Card title="Tweet search exports" icon="search" href="/guides/tweet-search-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/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/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}`. No authentication required. Share the URL with participants for transparency.

<CardGroup cols={2}>
  <Card title="Create a Monitor" icon="radar" href="/api-reference/monitors/create">
    Start monitoring a user for real-time events.
  </Card>

  <Card title="Register a Webhook" icon="webhook" href="/api-reference/webhooks/create">
    Receive events on your server in real time.
  </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>