jq, Python, a warehouse loader, or a queue worker.
Install
PATH.Authenticate
--api-key per command. For OAuth 2.1 access tokens, use X_TWITTER_SCRAPER_BEARER_TOKEN.Basic example
--help at any level.Tweet search workflow to JSON Lines, CSV, or XLSX
Use this workflow to get tweets from an X (Twitter) search query. It suits an analyst, data engineer, or growth operator. Deliver the tweets as a JSON Lines handoff, analyst CSV file, or XLSX workbook. They can also go to a warehouse load, CRM enrichment job, or queue. The CLI command below callsGET /x/tweets/search. It maps the same REST API query parameters to CLI flags. The flags are --q, --limit, --cursor, --since-time, --until-time, and --query-type..tweets[], .has_next_page, and .next_cursor. Each tweet can include id, text, createdAt, engagement counts, bookmarkCount, and isNoteTweet. It can also include author, media, quoted_tweet, and retweeted_tweet. Each field appears only when the result has it.
Project .tweets[] into xquik-tweet-search.jsonl and xquik-tweet-search.csv rows. Give each row tweet_id, author_username, engagement counts, page_index, page_cursor, next_cursor, and has_next_page. Scripts can then resume. They can also load the same records into XLSX, CRM, warehouse, or agent workflows.--limit as a 1 to 200 upper bound for a bounded pull. When .has_next_page is true, keep the same --q, filters, --query-type, and --limit. Only --cursor changes.
Tweet search costs 1 credit per tweet returned. If credits cannot cover a bounded --limit request, the API can return fewer tweets. If credits cover no results, it returns 402 insufficient_credits. If a bounded pull returns fewer tweets than --limit, pass .next_cursor back as --cursor. Send the same query, filters, --query-type, and --limit with it. Use --format-error json so batch jobs can branch on status and code. Retry 429 or temporary 5xx responses with backoff.
For XLSX handoff, keep xquik-tweet-search.jsonl as the master file. When account managers need a workbook, convert the same projected rows in your pipeline.Follower export workflow to CSV, JSON, or XLSX
Use this workflow when a team needs an owned follower list. It fits sales, support, research, or marketing teams. Deliver the list as a CRM import, warehouse load, or analyst CSV file. You can also deliver it as an XLSX workbook or resumable JSON handoff.follower_explorer requires targetUsername. The CLI flag is --target-username.POST /extractions/estimate and returns allowed, estimatedResults, creditsRequired, creditsAvailable, and source. For follower exports, source is usually followers.POST /extractions and returns the queued 202 Accepted receipt. The receipt holds id, toolType, and status: "running". Store follower-run.json, job_id, the source username, and the estimate before polling. Credit reservation happens after the job starts. If available credits changed since the estimate, the run has 2 outcomes. It can fetch only the affordable count before export. Or it can mark the job failed with insufficient_credits..job, .results, .hasMore, and .nextCursor. When .hasMore is true, pass .nextCursor back as --cursor. That fetches the next saved page.--format json --output xquik-followers.json for app ingestion or --format xlsx --output xquik-followers.xlsx for XLSX handoff. Map User ID or result xUserId as the CRM unique key. Keep xquik-followers.jsonl for queue replay or warehouse loads, and xquik-followers.json for app ingestion. Keep xquik-followers.csv for CRM import and xquik-followers.xlsx for analyst handoff.
The cost is 1 credit per follower extracted or returned. Exports cost no credits after the
extraction job exists.Tweet replies workflow to CSV, JSON, or XLSX
Use this workflow when you need every reply under one Tweet. Export CSV, JSON, or XLSX. Write a local JSON Lines file from paginated JSON rows.reply_extractor requires targetTweetId. The CLI flag is --target-tweet-id.POST /extractions/estimate and returns allowed, estimatedResults, creditsRequired, creditsAvailable, and source. For replies, source is usually replyCount.POST /extractions. Store job_id before polling. With it, a shell restart, queue retry, or CI rerun can resume that extraction. Reuse the follower export polling loop above with reply filenames.GET /extractions/{id} and returns .job, .results, .hasMore, and .nextCursor. Append .results[] to your queue, CRM import, or warehouse load. While .hasMore is true, pass .nextCursor back as --cursor "$next_cursor".GET /extractions/{id}/export and writes bytes to --output. Use --format csv, --format json with --output xquik-tweet-replies.json, or --format xlsx with --output xquik-tweet-replies.xlsx. The cost is 1 credit per reply extracted or returned. Exports cost no credits after the extraction job exists.Workflow to post media tweets, replies, and DM attachments
Use this workflow when an operator, support queue, or agent sends media. It can publish a media-backed tweet or reply with media. It can also send one media attachment in a DM. The workflow runs from a connected X account. Tweet and reply media posts use public media URLs directly onx:tweets create. Pass repeated --media flags for up to 4 image URLs. Or pass exactly 1 MP4 video URL up to 100 MB. Do not mix video with other media. Do not upload first when you already have public media URLs.--reply-to-tweet-id flag maps to reply_to_tweet_id. --media maps to the public URL array on POST /x/tweets.Idempotency-Key. Store the durable action’s id, request.hash, billing, result, and statusUrl. Poll while terminal is false. Retry only when safeToRetry is true, using a new key. Keep one JSON Lines handoff shape for every lifecycle state.x:media upload when you need an uploaded media ID for a DM attachment. The CLI upload command accepts a local file through --file. --transform mediaId extracts the upload response ID for scripts.--media-id flag maps to the REST media_ids body field. DMs accept exactly 1 uploaded media ID. Store messageId from the DM response. Put it on the support ticket, CRM record, queue job, or agent memory. Keep DM body text in private systems. Shared logs, public artifacts, queue status, and agent handoffs should omit full DM bodies. They should store message_id, optional media_id, and send status. They should also store recipient and account identifiers from your job context. Uploading media costs 10 credits. Sending the DM costs 10 credits.
Do not pass --reply-to-message-id to x:dm send. The REST endpoint rejects reply_to_message_id. Start a new DM with --user-id, --account, --text, and optional one-item --media-id instead.
Do not pass uploaded mediaId values to x:tweets create. That command uses --media with public media URLs.Useful commands
Search tweets or scrape tweets
Run
x-twitter-scraper x:tweets search to return tweet objects, author objects, metrics, media, has_next_page, and next_cursor.Fetch one tweet
Run
x-twitter-scraper x:tweets retrieve to return the full tweet text, author, and metrics. It also returns media, the quoted tweet, and the retweeted tweet.Get tweet replies
Run
x-twitter-scraper x:tweets get-replies to return reply tweets plus cursor fields.Export followers
Run
x-twitter-scraper x:users retrieve-followers to return user profiles, follower counts, and cursor fields.Post a tweet or reply
Run
x-twitter-scraper x:tweets create to return tweetId, success, charged, and chargedCredits. When confirmation is pending, it returns writeActionId instead.Upload media for a DM attachment
Run
x-twitter-scraper x:media upload to return mediaId for one-item DM media_ids. It also returns mediaUrl for tweet media URL handoff.Send a direct message
Run
x-twitter-scraper x:dm send to return messageId and success.--format json for scripts and --format yaml for readable operations output. When you only need one field from the response, use --transform with GJSON syntax.Error handling
The CLI writes API errors to stderr and exits non-zero for failed requests. Use--format-error json when scripts need machine-readable errors.