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. This workflow scrapes tweets, exports followers, pulls tweet replies, saves files, or passes JSON. Files can be CSV, JSON, or XLSX. Paginated JSON can go 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. Xquik reserves credits 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 it as CSV, JSON, XLSX, Markdown, PDF, or TXT.
5

Export files

Download a file when the next tool expects one. Formats are CSV, JSON, XLSX, Markdown, PDF, or TXT.

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 download. The download can be CSV, JSON, or XLSX.

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. Decide 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 these fields.
  • allowed, creditsRequired, and creditsAvailable show affordability and balance.
  • source and estimatedResults give the count basis and projected rows.
  • resolvedXUserId is the ID returned by count-based profile estimates.
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

Follow waitUrl until terminal. Save row count, cursor, and format before result loading.

Data handoff

Pick the handoff that fits your pipeline, from durable JSON Lines to spreadsheets. See extraction data handoff for each pattern.

Tool types reference

This section groups the 23 extraction tools 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. The job reads through your connected X account. Without one, the job fails with errorMessage set to errorXAccountRequired.

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 liked tweets that X makes visible. X shows likes only to their owner. The job reads through your connected X account. Without one, the job fails with errorMessage set to errorXAccountRequired.

Media posts

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

Affiliates

Use user_affiliates with targetUsername to extract the accounts an organization lists as its affiliates.

Community tools

Community members

Use community_extractor with targetCommunityId to extract members.

Community moderators

Use community_moderator_explorer with targetCommunityId to extract moderators.

Community posts

Use community_post_extractor with targetCommunityId to extract posts.

Search within a community

Use community_search with targetCommunityId and searchQuery to filter Community posts.

List tools

List members

Use list_member_extractor with targetListId to extract members.

List tweets

Use list_post_extractor with targetListId to extract tweets.

List followers

Use list_follower_explorer with targetListId to extract followers.

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.

Search filters

tweet_search_extractor accepts every filter below. community_search accepts language, dates, media, verified authors, native reposts, and the listed minimums. Omit unrequested filters. A minimum alone does not request queryType=Top. Use advancedQuery only for a known X (Twitter) search operator string.

Account filters

Use fromUser for author username and toUser for tweets directed to a user. Use 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 (Twitter) 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 narrow a search and cap its cost. For example, find the 50 top tweets about a topic from verified accounts. Limit them to 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 keeps each Twitter profile ID, username, counts, and verification. It also keeps 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

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

Estimate extraction

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

Start extraction

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

Poll results

The REST route is GET /extractions/{id}. In 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 the tweet at 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. You need no active plan 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 and 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.