Extraction workflow

Run bulk data extractions from X in 5 stages: check credits, estimate costs, run the job, retrieve JSON pages, and export files. Use this workflow to scrape tweets, export followers, pull tweet replies, save CSV/JSON/XLSX files, or hand paginated JSON to a CRM, warehouse, queue, or AI agent.

Workflow overview

1. Check credits

Call GET /account to confirm subscription status and available credits.

2. Estimate cost

Call POST /extractions/estimate with the same target you plan to run.

3. Run extraction

Call POST /extractions after the estimate fits your balance and result cap.

4. Retrieve JSON

Call GET /extractions/{id} and page through nextCursor while hasMore is true.

5. Export file

Call GET /extractions/{id}/export when you need CSV, JSON, XLSX, or another file.

Check credits

Verify your subscription is active and your credit balance can cover the job.

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, JSON, XLSX, Markdown, PDF, or TXT.

Export files

Download CSV, JSON, XLSX, Markdown, PDF, or TXT when a downstream tool expects a file.

End-to-end agent handoff

Store one checkpoint per extraction run so another worker can resume without rereading logs:

{
  "workflow": "reply_extractor_to_csv",
  "request": {
    "toolType": "reply_extractor",
    "targetTweetId": "1893704267862470862",
    "resultsLimit": 500
  },
  "estimate": {
    "estimatedResults": 500,
    "creditsRequired": "500",
    "creditsAvailable": "77000",
    "allowed": true,
    "source": "replyCount"
  },
  "create_receipt": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "running",
    "poll_path": "/api/v1/extractions/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "json_pages": {
    "limit": 1000,
    "page_cursor": null,
    "next_cursor": "990200",
    "has_more": true
  },
  "inventory_path": "/api/v1/extractions?status=completed&toolType=reply_extractor",
  "export_path": "/api/v1/extractions/a1b2c3d4-e5f6-7890-abcd-ef1234567890/export?format=csv",
  "handoff_state": "poll_until_completed_then_export"
}

Estimate checkpoint

Store estimatedResults, creditsRequired, creditsAvailable, allowed, and source before creating the job.

Create receipt

Store the returned job id, status, and poll_path; result rows arrive from GET /extractions/{id}.

Cursor state

Store page_cursor, next_cursor, and has_more for each JSON page so workers can resume pagination.

File handoff

Store inventory_path for later job lookup and export_path for the CSV, JSON, or XLSX download.

Step 1: Check credits

Before running an extraction, verify your subscription status and credit balance.

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": 9007199254740991,
  "monitorsUsed": 1,
  "monitorBilling": {
    "activeDailyEstimate": "500",
    "activeHourlyBurn": "21",
    "creditsPerActiveMonitorDay": "500",
    "creditsPerActiveMonitorHour": "21",
    "eventsIncluded": true,
    "instantCheckIntervalSeconds": 1,
    "unlimitedSlots": true
  },
  "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 credit usage without consuming credits.

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,
  "creditsRequired": "150",
  "creditsAvailable": "77000",
  "estimatedResults": 150,
  "source": "replyCount",
  "resolvedXUserId": "44196397"
}

Allowed

allowed tells you whether the job can start with the current credit balance.

Estimate source

source names the count used for the estimate, such as replyCount, followers, or resultsLimit.

Estimated results

estimatedResults is the approximate number of records the job will return.

Credits required

creditsRequired is the projected credit usage for this extraction.

Credits available

creditsAvailable is your current balance when the estimate runs.

Resolved X user ID

resolvedXUserId appears when targetUsername resolves to an X user ID.

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.

Step 4: Retrieve results

Data handoff

Choose the handoff based on the system that consumes the extraction.

App or API pipeline

Use GET /extractions/{id}. Store job, results, hasMore, nextCursor. Use limit up to 1,000 and pass nextCursor as after.

CRM import

Use GET /extractions/{id}/export?format=csv. Store User ID, Username, Display Name, Followers, and Verified. Upsert by stable X user ID when possible.

Warehouse or queue

Use GET /extractions/{id}/export?format=json or paginated JSON. Store xUserId, xUsername, tweetId, tweetText, createdAt. Keep the extraction ID with each load for replay and audit.

Analyst review

Use GET /extractions/{id}/export?format=xlsx. Store export columns plus enrichment fields. Use CSV/JSON for automation and XLSX for manual review.

Paginated JSON is not row-capped by the export limit. File exports are capped at 100,000 rows, and PDF exports are capped at 10,000 rows.

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

Durable JSON Lines handoff

Use JSON Lines when a queue, warehouse, or agent needs replayable rows without the export row cap. Write each paginated result with the cursor state that produced it.

{
  "extraction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "row_id": "990001",
  "x_user_id": "44196397",
  "x_username": "elonmusk",
  "tweet_id": "1893710452812718080",
  "tweet_text": "This is a great thread, thanks for sharing.",
  "page_cursor": "990100",
  "next_cursor": "990200",
  "has_more": true,
  "handoff_format": "jsonl"
}

Store rows in xquik-extraction-results.jsonl for queue replay, warehouse loads, or agent audits. Keep page_cursor and next_cursor so the job can resume from the last successful page. 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 results as CSV, JSON, XLSX, Markdown, PDF, or TXT. Exports include enrichment data such as bios, locations, and engagement metrics.

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

CSV

format=csv returns text/csv; charset=utf-8 for spreadsheets and data pipelines.

JSON

format=json returns application/json; charset=utf-8 for API clients and programmatic processing.

Markdown

format=md returns text/markdown; charset=utf-8 for documentation and issue handoffs.

Markdown document

format=md-document returns text/markdown; charset=utf-8 for longer markdown documents.

PDF

format=pdf returns application/pdf for reports and sharing. PDF exports are capped at 10,000 rows.

TXT

format=txt returns text/plain; charset=utf-8 for plain text and logs.

XLSX

format=xlsx returns application/vnd.openxmlformats-officedocument.spreadsheetml.sheet for Excel and 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

Reply authors

Use reply_extractor with targetTweetId to extract users who replied to a tweet.

Repost authors

Use repost_extractor with targetTweetId to extract users who reposted a tweet.

Quote authors

Use quote_extractor with targetTweetId to extract users who quote-posted a tweet.

Like authors

Use favoriters with targetTweetId to extract users who liked a tweet.

Thread tweets

Use thread_extractor with targetTweetId to extract all tweets in a thread.

Article content

Use article_extractor with targetTweetId to extract article content from a tweet.

User-based tools

Follower profiles

Use follower_explorer with targetUsername to extract followers of an account.

Following profiles

Use following_explorer with targetUsername to extract accounts followed by a user.

Verified followers

Use verified_follower_explorer with targetUsername to extract verified followers of an account.

Mention tweets

Use mention_extractor with targetUsername to extract tweets mentioning an account.

Account posts

Use post_extractor with targetUsername to extract posts from an account.

Liked tweets

Use user_likes with targetUsername to extract tweets liked by a user.

Media posts

Use user_media with targetUsername to extract media posts from a user.

Community tools

Community members

Use community_extractor with targetCommunityId to extract members of a community.

Community moderators

Use community_moderator_explorer with targetCommunityId to extract moderators of a community.

Community posts

Use community_post_extractor with targetCommunityId to extract posts from a community.

Cross-community search

Use community_search with searchQuery to search posts across communities.

List tools

List members

Use list_member_extractor with targetListId to extract members of a list.

List tweets

Use list_post_extractor with targetListId to extract tweets from a list.

List followers

Use list_follower_explorer with targetListId to extract followers of a list.

Other tools

People search

Use people_search with searchQuery to find user profiles by keyword.

Space participants

Use space_explorer with targetSpaceId to extract participants of a Space.

Tweet search

Use tweet_search_extractor with searchQuery to extract tweets by keyword, hashtag, or structured filters.

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. Use structured fields first for common jobs such as search tweets from a user, search tweet replies, scrape tweets with images, or export posts in a date range. Use advancedQuery only when you already know the X search operator string you want to append.

Account filters

Use fromUser for author username, toUser for tweets directed to a user, and mentioning for tweets that mention a user.

Date and language

Use language for a language code such as en, tr, or es, then bound the export with sinceDate and untilDate in YYYY-MM-DD format.

Media and engagement

Use mediaType for images, videos, gifs, or media, then set minFaves, minRetweets, or minReplies for minimum engagement.

Conversation filters

Use verifiedOnly for verified authors, replies to include, exclude, or return only replies, and retweets to include, exclude, or return only retweets.

Query refinement

Use exactPhrase for exact matches, excludeWords for comma-separated exclusions, and advancedQuery for 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:

Check account

REST route: GET /account. MCP call: xquik.request('/api/v1/account') to confirm subscription, credits, and usage before a run.

Estimate extraction

REST route: POST /extractions/estimate. MCP call: xquik.request('/api/v1/extractions/estimate', { method: 'POST', body }) with the same body you plan to run.

Start extraction

REST route: POST /extractions. MCP call: xquik.request('/api/v1/extractions', { method: 'POST', body }) to create the background job.

Poll results

REST route: GET /extractions/{id}. MCP call: xquik.request('/api/v1/extractions/ID') to retrieve the job status and rows.

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

402 no_subscription means the account has no active subscription. Subscribe from the dashboard, then retry the extraction.

Top up credits

402 insufficient_credits means the account cannot cover the requested extraction. Top up credits, wait for the next grant, or lower resultsLimit.

Fix toolType

400 invalid_tool_type means toolType is not one of the supported extraction tools. Check the tool types reference.

Fix required fields

400 invalid_input usually means the target field is missing or malformed. Match targetTweetId, targetUsername, targetCommunityId, targetListId, targetSpaceId, or searchQuery to the selected tool.

Retry read service

502 x_api_unavailable means the read service is temporarily unavailable. Retry with exponential backoff, then contact support if the error persists.

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, credits, and usage scenarios.

Getting Started

SDKs

Guides

Webhooks

MCP Server

Agent Plugins

Framework Guides

OAuth

MPP

Resources

Documentation Index

​Workflow overview

1. Check credits

2. Estimate cost

3. Run extraction

4. Retrieve JSON

5. Export file

​End-to-end agent handoff

Estimate checkpoint

Create receipt

Cursor state

File handoff

​Step 1: Check credits

​Step 2: Estimate cost

Allowed

Estimate source

Estimated results

Credits required

Credits available

Resolved X user ID

​Step 3: Run the extraction

​Step 4: Retrieve results

​Data handoff

App or API pipeline

CRM import

Warehouse or queue

Analyst review

​Option A: Paginate via API

​Durable JSON Lines handoff

​Option B: Export as file

CSV

JSON

Markdown

Markdown document

PDF

TXT

XLSX

​Tool types reference

​Tweet-based tools

Reply authors

Repost authors

Quote authors

Like authors

Thread tweets

Article content

​User-based tools

Follower profiles

Following profiles

Verified followers

Mention tweets

Account posts

Liked tweets

Media posts

​Community tools

Community members

Community moderators

Community posts

Cross-community search

​List tools

List members

List tweets

List followers

​Other tools

People search

Space participants

Tweet search

​Tweet search filters

Account filters

Date and language

Media and engagement

Workflow overview

End-to-end agent handoff

Step 1: Check credits

Step 2: Estimate cost

Step 3: Run the extraction

Step 4: Retrieve results

Data handoff

Option A: Paginate via API

Durable JSON Lines handoff

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