reply_extractor for reply authors and follower_explorer for profiles.
Jobs also cover posts, communities, lists, likes, reposts, quotes, and media.
Retrieve structured JSON or export CSV, JSON, or XLSX files.
Tweet search results can filter authors, dates, engagement, media, relationships, lists, and locations.
Workflow overview
Treat
202 Accepted as a queued run receipt. Credits are reserved after the job starts. Poll GET /extractions/{id} before handoff. The run can lower resultsLimit to the affordable count or fail with insufficient_credits.1
Check credits
Verify that your available credit balance can cover the job.
2
Estimate cost
Preview the extraction cost before committing. Check whether it fits within your remaining budget.
3
Run the extraction
Submit the extraction job, store the
202 Accepted receipt, then poll before handoff.4
Retrieve results
Paginate through extracted data via the API, or export as CSV, JSON, XLSX, Markdown, PDF, or TXT.
5
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: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, callGET /account
and store a small planning checkpoint:
cURL
plan for billing context. Use creditInfo.balance to decide whether to
continue, top up, or lower resultsLimit before estimating the extraction.
Step 2: estimate cost
Use the estimate endpoint first. It shows expected rows and credits without charging you.allowed,creditsRequired, andcreditsAvailable: affordability and balance.sourceandestimatedResults: count basis and projected rows.resolvedXUserId: the ID found for a suppliedtargetUsername.
Step 3: run the extraction
Submit the job with the same parameters you used for the estimate.202 Accepted. Save the key with the job ID. Reuse that
key only after a timeout or lost response. An exact retry returns the original
job with Idempotency-Replayed: true. A changed request returns 409. A
terminal replay sets pollAfterMs to 0 and omits Retry-After.
Step 4: retrieve results
Poll the extraction ID until it completes or fails. Then download a file or retrieve every JSON page. Save ID, row count, cursor, and format before loading.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 cursor.
Use compact output for core fields and tweet counts.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.Option a: paginate via API
Fetch results in pages of up to 1,000 records. Use cursor-based pagination to iterate through all results.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.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:
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. Available export rows include bios, locations, and engagement counts.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.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.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 visible users who liked a
post. Liker identities can be unavailable even when the post reports likes.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.Search within a community
Use
community_search with both targetCommunityId and searchQuery to
search matching posts inside one community.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 filters
Onlytweet_search_extractor accepts the 31 optional filters.
Xquik converts them to X search operators internally. Omit every filter the
caller did not request. A topic plus a like minimum includes every language,
reply, repost, and quote. A minimum alone does not request queryType=Top.
Use structured fields for authors, replies, media, dates, engagement, and locations.
Use advancedQuery only for a known X search operator string.
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, media, links, or none.
Set minFaves, minRetweets, minReplies, or minQuotes.Conversation filters
Use
replies, retweets, and quotes with include, exclude, or only.
Set verifiedOnly when only verified authors should match.Query refinement
Combine
exactPhrase, excludeWords, anyWords, hashtags, cashtags,
and url for terms, entities, or linked domains.Tweet relationships
Use
conversationId, inReplyToTweetId, quotesOfTweetId, or
retweetsOfTweetId for one conversation or source tweet.List and location scopes
Use
listId, place, placeCountry, pointRadius, or boundingBox.
These fields narrow search results to a list or location.Advanced query
Use
advancedQuery only for raw X search syntax.
Prefer the 30 structured fields when one already represents the filter.cURL
Twitter scraper API questions
What is a Twitter scraper API?
A Twitter scraper API collects X posts and profiles through documented requests. Xquik creates a job, returns its ID, and exposes cursor-based JSON results. It can also generate downloadable files. This Twitter data scraper covers tweets, replies, followers, following, communities, and lists. It also covers spaces, likes, reposts, quotes, and media posts.Can Python scrape Twitter without the official API?
Yes, through Xquik’s REST API and the Python examples above. API access still requires an Xquik API key. You do not need to maintain an X developer application. Poll the job, follow every cursor, and save structured tweet or profile rows.How do I export Twitter followers?
Runfollower_explorer with the Twitter account username in targetUsername.
This Twitter follower scraper returns visible follower profiles.
Estimate the job before creating it.
Then poll every JSON page or download a file.
The follower export API preserves each Twitter profile ID, username, counts, and verification.
It also preserves names when available.
How do I export tweet replies?
Usereply_extractor with targetTweetId for visible reply-author profiles.
Use tweet_search_extractor when the reply posts themselves matter.
Pass inReplyToTweetId to restrict results to one source tweet.
A tweet replies export can use CSV, JSON, XLSX, or paginated JSON.
Store the source tweet ID, extraction ID, row IDs, and cursor checkpoint.
Why use a Twitter scrape API instead of a custom web scraper?
A custom web scraper must maintain selectors, login behavior, retries, and parsers. A Twitter scrape API uses documented requests, statuses, cursors, and output fields.MCP equivalent
The same workflow works through the MCP server using theexecute sandbox tool:
Check account
REST route:
GET /account. MCP call:
xquik.request('/api/v1/account') to confirm account state, 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.- “How much would it cost to extract all followers of @elonmusk?”
- “Extract visible 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
Resolve billing access
A
402 means the account cannot fund this extraction. Check the available
balance and payment_options. An active plan is not required when enough
credits remain.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.