# X.com (Twitter) Thread Unroller & Scraper (`lurkapi/x-twitter-thread-unroller`) Actor Paste any tweet URL. Get the entire thread unrolled: root, all self-replies, and clean Markdown. Pay per thread ($5/1k base). Optional add-ons: media downloads, full quoted tweets. - **URL**: https://apify.com/lurkapi/x-twitter-thread-unroller.md - **Developed by:** [LurkAPI](https://apify.com/lurkapi) (community) - **Categories:** Agents, Automation, Social media - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $5.00 / 1,000 thread unrolleds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## X.com (Twitter) Thread Unroller & Scraper Paste any tweet from a thread. Get the whole story back, clean and ready to use. ### ๐Ÿงต What it does Give it any tweet from an X (Twitter) thread. It finds the first post, walks through every reply from the original author, and hands you the full thread in order. You get likes, replies, retweets, views, media, and a clean Markdown version you can drop straight into Notion, Obsidian, or a blog post. Works even when the tweet you paste is buried deep in the middle of the thread. ### ๐Ÿ“‹ How to use it 1. **Paste your tweet links.** Any tweet from the thread works. Full URLs, share links, and plain tweet ID numbers are all accepted (x.com, twitter.com, mobile.twitter.com, fxtwitter.com, vxtwitter.com). 2. **Pick an output shape.** "Nested" keeps each thread as one row with replies grouped inside. "Flat" gives you one row per tweet, great for spreadsheets. 3. **Click Start** and grab your results from the Output tab. ### ๐Ÿ’ฐ Pricing Pay only for what you get. No monthly fee. - **$0.005 per thread unrolled** ($5 for 1,000 threads) - **$0.002 per media downloaded**, only if you turn on the media download add-on - **$0.001 per quoted tweet**, only if you turn on the quoted tweets add-on Failed threads, deleted tweets, and blocked accounts are **free**. ### ๐Ÿ’ก Good to know - **Any tweet in the thread works.** No need to search for the first one. - **Same author only.** A "thread" means the original author's own chain of posts. Replies from other people are not included. - **Free Markdown export.** Every thread comes with a ready-to-paste Markdown version of the whole conversation. - **Long threads.** By default we return up to 50 posts per thread. Raise the limit for very long ones. - **Media storage.** Downloaded images and videos are saved in your Apify storage. How long they stay depends on your Apify plan. ### โ“ FAQ **Do I need a Twitter API key or a paid X account?** No. Nothing to sign up for. Just paste and go. **What if the tweet I paste is not the first one in the thread?** That is fine. The tool finds the first tweet for you and returns the whole thread from the top. **Why did my thread come back as "not found"?** The tweet may be deleted, from a suspended account, or from a private profile. You will see a clear status message. These runs are free. **Can I export the thread as a document?** Yes. Every result includes a Markdown version of the full thread, ready to paste into your notes, blog, or docs. **Why are there fewer replies than I expected?** Only the original author's own chain of posts counts as a "thread". Replies from other users are not included. ### ๐Ÿ”— Other tools you might like - [X.com (Twitter) Tweet Scraper](https://apify.com/lurkapi/x-twitter-tweet-scraper): search-driven tweet scraping with filters. - [X.com (Twitter) Profile Scraper](https://apify.com/lurkapi/x-twitter-profile-scraper): every tweet from a profile with sort options. ### โš–๏ธ Disclaimer This tool is meant for personal, research, and educational use. You are responsible for following X's Terms of Service and any laws in your region. The developer is not liable for how the tool is used. Data availability depends on what X shows at run time. **Keywords:** x thread scraper, twitter thread unroller, tweet unroll, twitter markdown export, x conversation scraper, apify twitter, twitter thread to markdown, x tweet thread download, twitter thread archiver, x post thread saver # Actor input Schema ## `tweetUrls` (type: `array`): Paste any tweet from anywhere in the thread. Accepts x.com, twitter.com, mobile.twitter.com, fxtwitter.com, vxtwitter.com URLs, share links, or bare numeric IDs. One entry per thread. ## `downloadMedia` (type: `boolean`): Download every photo and video attached to any tweet in the thread into the run's key-value store. Charged once per tweet with at least one file downloaded. ## `includeQuotedTweets` (type: `boolean`): When a tweet in the thread quote-tweets another post, embed the full quoted tweet: text, author, media, counts. Charged once per thread that has at least one quoted tweet. ## `outputMode` (type: `string`): Nested: one row per thread, all replies attached under threadTweets[]. Best for JSON export. Flat: one row per tweet, ordered root โ†’ tail, with threadRootId + threadPosition + inReplyToTweetId fields. Best for CSV / spreadsheet export. ## `includeRootAsFirstReply` (type: `boolean`): In flat mode, emit the root tweet as the first row (position 0). Ignored in nested mode where the root is always at the top. ## `maxRepliesPerThread` (type: `integer`): Hard cap on self-replies collected per thread. Root tweet is always included. Default 50 covers 99% of threads. ## `outputId` (type: `boolean`): Numeric tweet ID. ## `outputUrl` (type: `boolean`): Canonical tweet URL. ## `outputFullText` (type: `boolean`): Full tweet text (long-form notes never 280-char truncated). ## `outputCreatedAt` (type: `boolean`): ISO-8601 creation timestamp. ## `outputLang` (type: `boolean`): Source language as returned by X. ## `outputReplyCount` (type: `boolean`): Reply count. ## `outputRetweetCount` (type: `boolean`): Retweet count. ## `outputLikeCount` (type: `boolean`): Favorite / like count. ## `outputQuoteCount` (type: `boolean`): Quote-tweet count. ## `outputBookmarkCount` (type: `boolean`): Bookmark count. ## `outputViewCount` (type: `boolean`): View count. ## `outputConversationId` (type: `boolean`): Conversation root ID (equal to threadRootId when the tweet is part of a thread). ## `outputIsReply` (type: `boolean`): Boolean flag for reply tweets. ## `outputIsRetweet` (type: `boolean`): Boolean flag for retweets. ## `outputIsQuote` (type: `boolean`): Boolean flag for quote tweets. ## `outputRetweetedTweet` (type: `boolean`): Nested retweeted-tweet object when the tweet is a retweet. ## `outputInReplyTo` (type: `boolean`): inReplyToTweetId + inReplyToScreenName. Present on every non-root tweet. ## `outputMentions` (type: `boolean`): @-mentions array. ## `outputHashtags` (type: `boolean`): Hashtags array. ## `outputUrls` (type: `boolean`): Expanded URLs in tweet. ## `outputMedia` (type: `boolean`): Media array (photos + videos with URLs). Files are downloaded into the KV store only if the Download media add-on is enabled. ## `outputAuthor` (type: `boolean`): Author block (id, screenName, name, profileImageUrl, verification flags, followers, bio). ## `outputQuotedTweet` (type: `boolean`): Nested quoted-tweet object when present. ## `outputThreadMarkdown` (type: `boolean`): Clean Markdown export of the full thread. Populated on the root row in nested mode, on the position-0 row in flat mode. ## Actor input object example ```json { "tweetUrls": [ "https://x.com/karpathy/status/1615398117683388417" ], "downloadMedia": false, "includeQuotedTweets": false, "outputMode": "flat", "includeRootAsFirstReply": true, "maxRepliesPerThread": 50, "outputId": true, "outputUrl": true, "outputFullText": true, "outputCreatedAt": true, "outputLang": true, "outputReplyCount": true, "outputRetweetCount": true, "outputLikeCount": true, "outputQuoteCount": true, "outputBookmarkCount": true, "outputViewCount": true, "outputConversationId": true, "outputIsReply": true, "outputIsRetweet": true, "outputIsQuote": true, "outputRetweetedTweet": true, "outputInReplyTo": true, "outputMentions": true, "outputHashtags": true, "outputUrls": true, "outputMedia": true, "outputAuthor": true, "outputQuotedTweet": true, "outputThreadMarkdown": true } ```` # Actor output Schema ## `overview` (type: `string`): Every tweet in the thread with the essentials. ## `markdown` (type: `string`): The thread rendered as clean Markdown, ready to copy-paste. ## `tweets` (type: `string`): Per-tweet with parent + root IDs. ## `authors` (type: `string`): Thread authors (one per thread). ## `media` (type: `string`): Media attachments per tweet. ## `keyValueStore` (type: `string`): Downloaded photos and videos (when Download media add-on is enabled). # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "tweetUrls": [ "https://x.com/karpathy/status/1615398117683388417" ], "maxRepliesPerThread": 50 }; // Run the Actor and wait for it to finish const run = await client.actor("lurkapi/x-twitter-thread-unroller").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`๐Ÿ’พ Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // ๐Ÿ“š Want to learn more ๐Ÿ“–? Go to โ†’ https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "tweetUrls": ["https://x.com/karpathy/status/1615398117683388417"], "maxRepliesPerThread": 50, } # Run the Actor and wait for it to finish run = client.actor("lurkapi/x-twitter-thread-unroller").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("๐Ÿ’พ Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # ๐Ÿ“š Want to learn more ๐Ÿ“–? Go to โ†’ https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "tweetUrls": [ "https://x.com/karpathy/status/1615398117683388417" ], "maxRepliesPerThread": 50 }' | apify call lurkapi/x-twitter-thread-unroller --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=lurkapi/x-twitter-thread-unroller", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "X.com (Twitter) Thread Unroller & Scraper", "description": "Paste any tweet URL. Get the entire thread unrolled: root, all self-replies, and clean Markdown. Pay per thread ($5/1k base). Optional add-ons: media downloads, full quoted tweets.", "version": "0.0", "x-build-id": "VaePfUyRl87RfCGGH" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/lurkapi~x-twitter-thread-unroller/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-lurkapi-x-twitter-thread-unroller", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/lurkapi~x-twitter-thread-unroller/runs": { "post": { "operationId": "runs-sync-lurkapi-x-twitter-thread-unroller", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/lurkapi~x-twitter-thread-unroller/run-sync": { "post": { "operationId": "run-sync-lurkapi-x-twitter-thread-unroller", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "tweetUrls" ], "properties": { "tweetUrls": { "title": "๐Ÿงต Tweet URLs or IDs", "type": "array", "description": "Paste any tweet from anywhere in the thread. Accepts x.com, twitter.com, mobile.twitter.com, fxtwitter.com, vxtwitter.com URLs, share links, or bare numeric IDs. One entry per thread.", "items": { "type": "string" } }, "downloadMedia": { "title": "Download media files ($)", "type": "boolean", "description": "Download every photo and video attached to any tweet in the thread into the run's key-value store. Charged once per tweet with at least one file downloaded.", "default": false }, "includeQuotedTweets": { "title": "Include full quoted tweets ($)", "type": "boolean", "description": "When a tweet in the thread quote-tweets another post, embed the full quoted tweet: text, author, media, counts. Charged once per thread that has at least one quoted tweet.", "default": false }, "outputMode": { "title": "Output shape", "enum": [ "nested", "flat" ], "type": "string", "description": "Nested: one row per thread, all replies attached under threadTweets[]. Best for JSON export. Flat: one row per tweet, ordered root โ†’ tail, with threadRootId + threadPosition + inReplyToTweetId fields. Best for CSV / spreadsheet export.", "default": "flat" }, "includeRootAsFirstReply": { "title": "Include root tweet as the first item (flat mode only)", "type": "boolean", "description": "In flat mode, emit the root tweet as the first row (position 0). Ignored in nested mode where the root is always at the top.", "default": true }, "maxRepliesPerThread": { "title": "Max replies per thread", "minimum": 1, "maximum": 500, "type": "integer", "description": "Hard cap on self-replies collected per thread. Root tweet is always included. Default 50 covers 99% of threads.", "default": 50 }, "outputId": { "title": "id", "type": "boolean", "description": "Numeric tweet ID.", "default": true }, "outputUrl": { "title": "url", "type": "boolean", "description": "Canonical tweet URL.", "default": true }, "outputFullText": { "title": "fullText", "type": "boolean", "description": "Full tweet text (long-form notes never 280-char truncated).", "default": true }, "outputCreatedAt": { "title": "createdAt", "type": "boolean", "description": "ISO-8601 creation timestamp.", "default": true }, "outputLang": { "title": "lang", "type": "boolean", "description": "Source language as returned by X.", "default": true }, "outputReplyCount": { "title": "replyCount", "type": "boolean", "description": "Reply count.", "default": true }, "outputRetweetCount": { "title": "retweetCount", "type": "boolean", "description": "Retweet count.", "default": true }, "outputLikeCount": { "title": "likeCount", "type": "boolean", "description": "Favorite / like count.", "default": true }, "outputQuoteCount": { "title": "quoteCount", "type": "boolean", "description": "Quote-tweet count.", "default": true }, "outputBookmarkCount": { "title": "bookmarkCount", "type": "boolean", "description": "Bookmark count.", "default": true }, "outputViewCount": { "title": "viewCount", "type": "boolean", "description": "View count.", "default": true }, "outputConversationId": { "title": "conversationId", "type": "boolean", "description": "Conversation root ID (equal to threadRootId when the tweet is part of a thread).", "default": true }, "outputIsReply": { "title": "isReply", "type": "boolean", "description": "Boolean flag for reply tweets.", "default": true }, "outputIsRetweet": { "title": "isRetweet", "type": "boolean", "description": "Boolean flag for retweets.", "default": true }, "outputIsQuote": { "title": "isQuote", "type": "boolean", "description": "Boolean flag for quote tweets.", "default": true }, "outputRetweetedTweet": { "title": "retweetedTweet", "type": "boolean", "description": "Nested retweeted-tweet object when the tweet is a retweet.", "default": true }, "outputInReplyTo": { "title": "inReplyTo*", "type": "boolean", "description": "inReplyToTweetId + inReplyToScreenName. Present on every non-root tweet.", "default": true }, "outputMentions": { "title": "mentions", "type": "boolean", "description": "@-mentions array.", "default": true }, "outputHashtags": { "title": "hashtags", "type": "boolean", "description": "Hashtags array.", "default": true }, "outputUrls": { "title": "urls", "type": "boolean", "description": "Expanded URLs in tweet.", "default": true }, "outputMedia": { "title": "media", "type": "boolean", "description": "Media array (photos + videos with URLs). Files are downloaded into the KV store only if the Download media add-on is enabled.", "default": true }, "outputAuthor": { "title": "author", "type": "boolean", "description": "Author block (id, screenName, name, profileImageUrl, verification flags, followers, bio).", "default": true }, "outputQuotedTweet": { "title": "quotedTweet", "type": "boolean", "description": "Nested quoted-tweet object when present.", "default": true }, "outputThreadMarkdown": { "title": "threadMarkdown", "type": "boolean", "description": "Clean Markdown export of the full thread. Populated on the root row in nested mode, on the position-0 row in flat mode.", "default": true } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```