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 subscription status and credit balance:

Show Example response

{
  "plan": "active",
  "monitorsAllowed": 1,
  "monitorsUsed": 1,
  "creditInfo": {
    "balance": 77000,
    "lifetimePurchased": 140000,
    "lifetimeUsed": 63000,
    "autoTopupEnabled": false
  }
}

If creditInfo.balance is low, consider topping up 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:

Show Example response

{
  "allowed": true,
  "creditsRequired": "150",
  "creditsAvailable": "77000",
  "estimatedResults": 150,
  "source": "replyCount",
  "resolvedXUserId": "44196397"
}

Field	Description
`allowed`	Whether the extraction can proceed with the current credit balance
`source`	Data point used for the estimate (e.g. `replyCount`, `followers`)
`estimatedResults`	Approximate number of results
`creditsRequired`	Credits this extraction will consume
`creditsAvailable`	Credits currently available in your balance
`resolvedXUserId`	Resolved X user ID when `targetUsername` was provided. Omitted for non-user-based tools

If allowed is false, the extraction will return 402. Top up credits or run a smaller job.

Add resultsLimit to cap the number of results. Both the estimate and extraction endpoints accept this parameter. The estimate will use resultsLimit as the projected count, and the extraction will stop early once the limit is reached.

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": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "toolType": "reply_extractor",
  "status": "running"
}

The endpoint returns 202 Accepted with the job in running status. Poll GET /extractions/{id} until status is completed or failed. For large extractions (10,000+ results), this may take up to a few minutes.

AI summaries

Completed extractions and draws automatically receive AI-generated summaries in 3 languages (EN, TR, ES). These appear as the aiTitles field on job responses:

{
  "aiTitles": {
    "en": "150 replies to @elonmusk's tweet about Starship",
    "tr": "Starship hakkinda @elonmusk'un tweetine 150 yanit",
    "es": "150 respuestas al tweet de @elonmusk sobre Starship"
  }
}

AI titles are generated asynchronously after job completion and may not appear immediately.

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:

Show Example response

{
  "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",
  "createdAt": "2026-02-24T10:06:12.000Z"
}

Only id, xUserId, and createdAt 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
`json`	`application/json; charset=utf-8`	APIs, programmatic processing
`md`	`text/markdown; charset=utf-8`	Documentation, GitHub issues
`md-document`	`text/markdown; charset=utf-8`	Long-form markdown documents
`pdf`	`application/pdf`	Reports, sharing (max 10,000 rows)
`txt`	`text/plain; charset=utf-8`	Plain text, logs
`xlsx`	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`	Excel, formatted reports

Exports are capped at 100,000 rows (10,000 for PDF). For larger extractions, use the paginated API to retrieve all results.

Tool types reference

All 23 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
`favoriters`	`targetTweetId`	Extract users who liked 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
`user_likes`	`targetUsername`	Extract tweets liked by a user
`user_media`	`targetUsername`	Extract media posts from a user

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
`tweet_search_extractor`	`searchQuery`	Search and extract tweets by keyword or hashtag

tweet_search_extractor supports 16 optional filter parameters that are converted to X search operators internally. These filters only apply to tweet_search_extractor and are ignored by all other tool types.

Parameter	Type	Description
`fromUser`	string	Filter by author username
`toUser`	string	Filter tweets directed to a user
`mentioning`	string	Filter tweets mentioning a user
`language`	string	Language code (e.g. `en`, `tr`, `es`)
`sinceDate`	string	Start date `YYYY-MM-DD`
`untilDate`	string	End date `YYYY-MM-DD`
`mediaType`	string	`images`, `videos`, `gifs`, or `media`
`minFaves`	number	Minimum likes
`minRetweets`	number	Minimum retweets
`minReplies`	number	Minimum replies
`verifiedOnly`	boolean	Verified authors only
`replies`	string	`include`, `exclude`, or `only`
`retweets`	string	`include`, `exclude`, or `only`
`exactPhrase`	string	Exact phrase match
`excludeWords`	string	Comma-separated words to exclude
`advancedQuery`	string	Raw X search operator syntax

Example: Search for popular English tweets with images from the last week

curl -X POST https://xquik.com/api/v1/extractions \
  -H "x-api-key: xq_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "toolType": "tweet_search_extractor",
    "searchQuery": "artificial intelligence",
    "language": "en",
    "mediaType": "images",
    "minFaves": 100,
    "sinceDate": "2026-03-06",
    "untilDate": "2026-03-13",
    "retweets": "exclude"
  }' | jq

Combine filters with resultsLimit to run targeted, cost-efficient searches. For example, find the top 50 viral tweets about a topic from verified accounts in the last 24 hours.

MCP equivalent

The same workflow works through the MCP server using the xquik sandbox tool:

REST API	MCP Sandbox Code	Purpose
`GET /account`	`xquik.request('/api/v1/account')`	Check subscription and usage
`POST /extractions/estimate`	`xquik.request('/api/v1/extractions/estimate', { method: 'POST', body: { ... } })`	Preview cost
`POST /extractions`	`xquik.request('/api/v1/extractions', { method: 'POST', body: { ... } })`	Start the job
`GET /extractions/:id`	`xquik.request('/api/v1/extractions/ID')`	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 via xquik.request().

Error handling

Error	Cause	Solution
`402 no_subscription`	No active subscription	Subscribe from the dashboard
`402 insufficient_credits`	Insufficient credits	Top up credits or wait for next grant
`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 data source 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

Framework Guides

OAuth

MPP

Resources

Extraction workflow

Workflow overview

Step 1: Check your budget

Step 2: Estimate cost

Step 3: Run the extraction

AI summaries

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

Tweet search filters

MCP equivalent

Error handling

Next steps

Create Extraction

Estimate Extraction

Export Extraction

Billing & Usage

Getting Started

Guides

Webhooks

MCP Server

Framework Guides

OAuth

MPP

Resources

​Workflow overview

​Step 1: Check your budget

​Step 2: Estimate cost

​Step 3: Run the extraction

​AI summaries

​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

​Tweet search filters

​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

AI summaries

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

Tweet search filters

MCP equivalent

Error handling

Next steps