Skip to main content
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. Use 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, call GET /account and store a small planning checkpoint:
cURL
Store 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.
Response.
The estimate reports:
  • allowed, creditsRequired, and creditsAvailable: affordability and balance.
  • source and estimatedResults: count basis and projected rows.
  • resolvedXUserId: the ID found for a supplied targetUsername.
allowed: false means your balance cannot fund the full estimate. Add credits or lower resultsLimit.
resultsLimit defaults to 10,000 for estimates and jobs. Set any positive integer for a different bound. Billing follows unique emitted results. Source counts such as followers or replyCount can produce a smaller estimate.

Step 3: run the extraction

Submit the job with the same parameters you used for the estimate.
Response.
The endpoint returns 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.
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.

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

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

Only tweet_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.
Example: Search for popular English tweets with images from the last week
cURL
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.

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?

Run follower_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?

Use reply_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 the execute 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.
Example prompts for AI agents.
  • “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.