Extraction Workflow

Run bulk data extractions from X in 4 steps: check your budget, estimate costs, run the job, and retrieve results. This guide covers the full workflow for both the REST API and MCP server.

Workflow Overview

Check Budget → Estimate Cost → Run Extraction → Get Results → Export (optional)

Check your budget

Verify your subscription is active and you have enough quota remaining.

Estimate cost

Preview the extraction cost before committing. Check whether it fits within your remaining budget.

Run the extraction

Submit the extraction job with the appropriate tool type and target.

Retrieve results

Paginate through extracted data via the API, or export as CSV/XLSX/Markdown.

Step 1: Check Your Budget

Before running an extraction, verify your subscription status and remaining quota.

curl -s https://xquik.com/api/v1/account \
  -H "x-api-key: xq_YOUR_KEY_HERE" | jq

The response includes your current billing period and usage percentage:

{
  "plan": "active",
  "monitorsAllowed": 1,
  "monitorsUsed": 1,
  "currentPeriod": {
    "start": "2026-02-01T00:00:00.000Z",
    "end": "2026-03-01T00:00:00.000Z",
    "usagePercent": 45
  }
}

If usagePercent is near 100, consider waiting for the next billing period or running a smaller extraction.

Step 2: Estimate Cost

Always estimate before running. The estimate endpoint previews the result count and projected usage without consuming any quota.

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"
  }' | jq

Response:

{
  "allowed": true,
  "source": "replyCount",
  "estimatedResults": 150,
  "usagePercent": 45,
  "projectedPercent": 78
}

Field	Description
`allowed`	Whether the extraction fits within your monthly quota
`source`	Data point used for the estimate (e.g. `replyCount`, `followers`)
`estimatedResults`	Approximate number of results
`usagePercent`	Current usage before this extraction
`projectedPercent`	Projected usage after completion

If allowed is false, the extraction will return 402. Wait for the next billing period or run a smaller job.

Step 3: Run the Extraction

Submit the job with the same parameters you used for the estimate.

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

Response:

{
  "id": "77777",
  "toolType": "reply_extractor",
  "status": "completed",
  "totalResults": 150
}

The job runs synchronously and returns when complete. For large extractions (10,000+ results), this may take up to a few minutes.

Step 4: Retrieve Results

Option A: Paginate via API

Fetch results in pages of up to 1,000 records. Use cursor-based pagination to iterate through all results.

# First page
curl -s "https://xquik.com/api/v1/extractions/77777?limit=1000" \
  -H "x-api-key: xq_YOUR_KEY_HERE" | jq

# Next page (use nextCursor from previous response)
curl -s "https://xquik.com/api/v1/extractions/77777?limit=1000&after=990100" \
  -H "x-api-key: xq_YOUR_KEY_HERE" | jq

Each result contains user profile data and (for tweet-based tools) tweet data:

{
  "id": "990001",
  "xUserId": "44196397",
  "xUsername": "elonmusk",
  "xDisplayName": "Elon Musk",
  "xFollowersCount": 210500000,
  "xVerified": true,
  "xProfileImageUrl": "https://pbs.twimg.com/profile_images/el0n.jpg",
  "tweetId": "1893710452812718080",
  "tweetText": "This is a great thread, thanks for sharing.",
  "tweetCreatedAt": "2026-02-24T10:05:00.000Z"
}

Only id and xUserId are guaranteed on every result. All other fields are omitted when unavailable (never null). Check for field presence before accessing.

Option B: Export as File

Download all results as CSV, XLSX, or Markdown. Exports include enrichment data (bios, locations, engagement metrics) not available in the API response.

curl -s "https://xquik.com/api/v1/extractions/77777/export?format=csv" \
  -H "x-api-key: xq_YOUR_KEY_HERE" \
  -o extraction-reply_extractor-77777.csv

Format	Content-Type	Use Case
`csv`	`text/csv; charset=utf-8`	Spreadsheets, data pipelines
`xlsx`	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`	Excel, formatted reports
`md`	`text/markdown; charset=utf-8`	Documentation, GitHub issues

Exports are capped at 50,000 rows. For larger extractions, use the paginated API to retrieve all results.

Tool Types Reference

All 19 extraction tools grouped by target type. Each requires a specific target field.

Tweet-Based Tools

Tool Type	Required Field	Description
`reply_extractor`	`targetTweetId`	Extract users who replied to a tweet
`repost_extractor`	`targetTweetId`	Extract users who retweeted a tweet
`quote_extractor`	`targetTweetId`	Extract users who quote-tweeted a tweet
`thread_extractor`	`targetTweetId`	Extract all tweets in a thread
`article_extractor`	`targetTweetId`	Extract article content from a tweet

User-Based Tools

Tool Type	Required Field	Description
`follower_explorer`	`targetUsername`	Extract followers of an account
`following_explorer`	`targetUsername`	Extract accounts followed by a user
`verified_follower_explorer`	`targetUsername`	Extract verified followers of an account
`mention_extractor`	`targetUsername`	Extract tweets mentioning an account
`post_extractor`	`targetUsername`	Extract posts from an account

Community Tools

Tool Type	Required Field	Description
`community_extractor`	`targetCommunityId`	Extract members of a community
`community_moderator_explorer`	`targetCommunityId`	Extract moderators of a community
`community_post_extractor`	`targetCommunityId`	Extract posts from a community
`community_search`	`targetCommunityId` + `searchQuery`	Search posts within a community

List Tools

Tool Type	Required Field	Description
`list_member_extractor`	`targetListId`	Extract members of a list
`list_post_extractor`	`targetListId`	Extract posts from a list
`list_follower_explorer`	`targetListId`	Extract followers of a list

Other Tools

Tool Type	Required Field	Description
`people_search`	`searchQuery`	Search for users by keyword
`space_explorer`	`targetSpaceId`	Extract participants of a Space

MCP Equivalent

The same workflow works through the MCP server using 3 tools:

REST API	MCP Tool	Purpose
`GET /account`	`get-account`	Check subscription and usage
`POST /extractions/estimate`	`estimate-extraction`	Preview cost
`POST /extractions`	`run-extraction`	Start the job
`GET /extractions/:id`	`get-extraction`	Retrieve results

Example prompts for AI agents:

“How much would it cost to extract all followers of @elonmusk?”
“Extract all replies to this tweet: https://x.com/vercel/status/1893704267862470862”
“Show me the results of my last extraction.”

File export (GET /extractions/:id/export) is only available via the REST API. The MCP server returns results as structured JSON through the get-extraction tool.

Error Handling

Error	Cause	Solution
`402 no_subscription`	No active subscription	Subscribe from the dashboard
`402 usage_limit_reached`	Monthly quota exhausted	Wait for next billing period
`400 invalid_tool_type`	Unrecognized `toolType`	Check the tool types table
`400 invalid_input`	Missing required target field	Match target field to tool type
`502 x_api_unavailable`	X API temporarily down	Retry with exponential backoff

Next Steps

Create Extraction

Full API reference with request/response schemas.

Estimate Extraction

Cost estimation endpoint reference.

Export Extraction

CSV, XLSX, and Markdown export with column details.

Billing & Usage

Pricing, quotas, and usage scenarios.

Getting Started

Guides

Webhooks

MCP Server

Resources

Extraction Workflow

Workflow Overview

Step 1: Check Your Budget

Step 2: Estimate Cost

Step 3: Run the Extraction

Step 4: Retrieve Results

Option A: Paginate via API

Option B: Export as File

Tool Types Reference

Tweet-Based Tools

User-Based Tools

Community Tools

List Tools

Other Tools

MCP Equivalent

Error Handling

Next Steps

Create Extraction

Estimate Extraction

Export Extraction

Billing & Usage

Getting Started

Guides

Webhooks

MCP Server

Resources

​Workflow Overview

​Step 1: Check Your Budget

​Step 2: Estimate Cost

​Step 3: Run the Extraction

​Step 4: Retrieve Results

​Option A: Paginate via API

​Option B: Export as File

​Tool Types Reference

​Tweet-Based Tools

​User-Based Tools

​Community Tools

​List Tools

​Other Tools

​MCP Equivalent

​Error Handling

​Next Steps

Create Extraction

Estimate Extraction

Export Extraction

Billing & Usage

Workflow Overview

Step 1: Check Your Budget

Step 2: Estimate Cost

Step 3: Run the Extraction

Step 4: Retrieve Results

Option A: Paginate via API

Option B: Export as File

Tool Types Reference

Tweet-Based Tools

User-Based Tools

Community Tools

List Tools

Other Tools

MCP Equivalent

Error Handling

Next Steps