# X (Twitter) Video, Photo & GIF Downloader (`lurkapi/x-twitter-video-photo-gif-downloader`) Actor Download videos, photos, and GIFs from X (Twitter) in bulk. Paste a tweet URL, an X handle, or a search query. Files saved for you, ready to download. Pay per media file. - **URL**: https://apify.com/lurkapi/x-twitter-video-photo-gif-downloader.md - **Developed by:** [LurkAPI](https://apify.com/lurkapi) (community) - **Categories:** Agents, Social media, Videos - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks - **User rating**: No ratings yet ## Pricing from $1.00 / 1,000 media downloadeds 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 (Twitter) Video, Photo & GIF Downloader Download every video, photo, and GIF from X.com (formerly Twitter). Paste a tweet URL, an X handle, or a search query and get the files straight into your Apify storage with a permanent download link on every row. ### 📥 What it does Give it any of these inputs and this tool returns one row per media file, plus the actual file saved to your run's storage: - **Tweet URLs or IDs**: paste `https://x.com/user/status/123`, `twitter.com/user/status/123`, a share link with `?s=20&t=abc`, or just the numeric tweet ID. - **X handles or profile URLs**: paste `NASA` or `https://x.com/NASA` to pull every media file from that account. - **Search queries**: use X's advanced-search syntax to find media across the platform (`from:elonmusk filter:videos`, `mars filter:images since:2024-01-01`, `#space min_faves:1000`, and dozens more). See the [operator reference](https://github.com/igorbrigadir/twitter-advanced-search). For every media file you get: - The **actual file** saved in your Apify key-value store (jpg, png, webp for photos; mp4 for videos and animated GIFs). - A permanent Apify download link (`downloadUrl`) that never expires while your run is retained. - The original X CDN URL as a fallback (`sourceUrl`). - Full media metadata: type, dimensions, duration (for videos), file size in bytes. - The parent tweet's text, ID, canonical URL, and creation timestamp. - The author's handle, display name, avatar, and verification badges. - Engagement counts on the parent tweet: likes, retweets, replies, quotes, bookmarks, views. ### 📋 How to use it #### Step 1: Pick your inputs Mix any of these in the same run: - **Tweet URLs / IDs**: one entry per tweet. - **X handles**: one entry per profile. - **Search queries**: one entry per query. Any X advanced-search operator works. Every input is optional as long as at least one has a value. #### Step 2: Pick a media type Filter what gets downloaded: - **All**: videos + photos + GIFs. - **Video only**: mp4 video clips (highest bitrate variant). - **Photo only**: images from tweets (jpg / png / webp). - **GIF only**: X's animated GIFs (served as muted mp4). #### Step 3: Set the run size - **Max media files per run**: hard cap across every input. Default 100. Each photo, video, or GIF counts as one. A tweet with 4 photos = 4 files. Cap protects against surprise bills. Raise as high as 5,000. #### Step 4: (Optional) Add-on - **High-resolution originals**: for photos, pull the original uploaded file (uncompressed, full resolution) instead of X's 2048px "large" variant. iPhone shots often come back at 4000×3000 or higher. Videos always ship the highest available bitrate; no upgrade needed. Charged once per photo successfully pulled at original resolution. #### Step 5: Run Click Start. Rows stream into the Output tab as each page finishes, so you do not have to wait for the whole run. Files land in the Storage tab as they download. ### 📊 What you get Every row is one media file (a tweet with 4 photos = 4 rows). Four tabs group the fields by what you probably care about: | Tab | What is in it | |---|---| | 📋 Overview | Status, type, download link, handle, tweet URL, dimensions, duration, bytes, posted date | | 📥 Downloads | Every media file with Apify KV link, source URL, preview, dimensions, and file size | | 🐦 Tweets | Per-tweet spread: text, engagement counts, creation timestamp | | 👤 Authors | Author handle, name, avatar, verification badges | You can export from the Output tab as JSON, CSV, or Excel. Every row has a `status` field. `Success` means the file downloaded. Anything else is a human-readable message explaining what happened (file too large, tweet deleted, handle suspended, X CDN denied access). Rows that did not succeed are never billed. ### 💰 Pricing You only pay for what you get. | Event | Rate | When it fires | |---|---|---| | Actor run start | ~$0.00005 | Once per run (Apify platform overhead) | | Media downloaded | $1.00 / 1,000 | Once per file saved successfully to your storage | | Original-resolution photo | $0.50 / 1,000 | Once per photo pulled at original resolution (add-on only) | Failed downloads, suspended accounts, and tweets with no media cost nothing. ### 💡 Good to know - **Files land in your Apify key-value store**, not our servers. You get signed download links that anyone with the link can use. Retention depends on your Apify plan. - **Video always ships at the highest bitrate variant** X returns. No configuration needed. - **Photos are 2048px by default** (X's "large" size). Turn on the High-resolution originals add-on to pull the original upload for photos posted at higher resolution. - **Multi-media tweets explode into multiple rows.** A tweet with 3 photos and 1 GIF gives 4 rows, each with its own download link. - **URL forms accepted**: `x.com/user/status/123`, `twitter.com/user/status/123`, `mobile.x.com/user/status/123`, `x.com/i/web/status/123`, share links with `?s=20&t=abc`, and bare numeric tweet IDs. - **Handle forms accepted**: `NASA`, `@NASA`, `https://x.com/NASA`, `x.com/NASA?src=share`. Handles are case-insensitive. - **Rows appear in real time.** Open the Output tab while the run is still going and start pulling data. - **500 MB per-file cap.** Videos above this size return a `file_too_large` status. Rare, but very long uploads from premium accounts can hit it. ### For developers Call this actor through the Apify API: ```json { "tweetUrls": ["https://x.com/NASA/status/2075249100035866880"], "handles": ["NASA", "elonmusk"], "searchQueries": ["mars filter:videos min_faves:1000"], "mediaType": "all", "maxItems": 500, "includeHighResOriginals": true } ```` Every input field is optional. Provide at least one of `tweetUrls`, `handles`, or `searchQueries`. ### ❓ FAQ **Where do the downloaded files go?** Straight into your run's key-value store on Apify. Every row has a `downloadUrl` that points there. Files stay for as long as your Apify plan retains storage. **Do you keep any copies of my downloads?** No. Files exist only in your Apify storage. We never mirror or archive them. **Why did a video come back with `file_too_large`?** The file exceeded 500 MB. This happens occasionally with very long uploads from Premium+ accounts. Try a different tweet or a specific tweet URL that points to a shorter clip. **Why did my run return zero rows?** Possible reasons: the tweet was deleted, the account is protected or suspended, the search query did not match any tweets with media, or the media type filter dropped everything. You will see a clear `status` message on the row. **What is the difference between the default photo size and High-resolution originals?** Default photos come back at X's "large" size, capped at 2048px on the long side. High-resolution originals pulls the file the user actually uploaded, which for many phone shots is 4000×3000 or larger. Turn the add-on on when file quality matters more than file size. **Can I use my own X cookies?** No. This actor does not accept user cookies. **How long are the files kept?** Retention depends on your Apify plan. Free plans typically keep run storage for 7 days; paid plans keep it longer. ### 🔗 Other tools you might like - [X.com (Twitter) Tweet Scraper](https://apify.com/lurkapi/x-twitter-tweet-scraper): Full tweet data by search query, handle, or tweet URL. Same input syntax, tweet-focused output. - [X.com (Twitter) Profile Scraper](https://apify.com/lurkapi/x-twitter-profile-scraper): Every tweet from a profile with sort options. - [X.com (Twitter) Thread Unroller](https://apify.com/lurkapi/x-twitter-thread-unroller): Paste any tweet, get the whole thread unrolled with Markdown export. ### ⚖️ Disclaimer This tool is intended for personal, research, and educational use. You are responsible for complying with X.com's Terms of Service, the original creators' rights, and applicable laws in your jurisdiction. The developer is not liable for misuse. Data availability depends on X at run time. **Keywords:** twitter video downloader, x video downloader, twitter photo downloader, x photo downloader, twitter gif downloader, twitter media downloader, bulk twitter downloader, save twitter videos, x media bulk download, no login twitter download # Actor input Schema ## `tweetUrls` (type: `array`): One tweet per entry. Accepts standard, mobile, and share links: https://x.com/user/status/123, https://twitter.com/user/status/123, https://mobile.x.com/user/status/123. Numeric tweet IDs also work. ## `handles` (type: `array`): Usernames (e.g. NASA) or profile URLs (https://x.com/NASA). Pulls media from the user's media tab, newest first. ## `searchQueries` (type: `array`): X advanced-search queries. Full operator syntax supported: from:elonmusk, since:2024-01-01, min\_faves:100, lang:en, filter:videos, filter:images. See the operator reference: https://github.com/igorbrigadir/twitter-advanced-search. Only tweets with attached media surface in this actor. ## `mediaType` (type: `string`): Filter by media type. 'All' keeps everything. 'Video' keeps mp4 video clips. 'Photo' keeps jpg/png/webp images. 'GIF' keeps X's animated GIFs (served as muted mp4). ## `maxItems` (type: `integer`): Hard cap on total media files downloaded across all inputs. Each photo, video, or GIF counts as one. A tweet with 4 photos = 4 files. ## `includeHighResOriginals` (type: `boolean`): Get photos at the original size the creator uploaded, not the compressed version X shows on the site. Phone shots often come back much larger and sharper. Videos always come at the best available quality; no upgrade needed. Only billed on photos that arrive at full original size. ## Actor input object example ```json { "tweetUrls": [ "https://x.com/NASA/status/2075249100035866880" ], "handles": [], "searchQueries": [], "mediaType": "all", "maxItems": 10, "includeHighResOriginals": false } ``` # Actor output Schema ## `overview` (type: `string`): Status, media type, download link, tweet handle & URL, dimensions. ## `downloads` (type: `string`): Every media file with Apify KV download link, X CDN source, preview, dimensions. ## `tweets` (type: `string`): Per-tweet spread: text, engagement counts, creation timestamp. ## `authors` (type: `string`): Author handle, name, avatar, verification. ## `keyValueStore` (type: `string`): Downloaded photos, videos and GIFs. Signed links point into your Apify key-value store. # 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/NASA/status/2075249100035866880" ], "handles": [], "searchQueries": [], "maxItems": 10 }; // Run the Actor and wait for it to finish const run = await client.actor("lurkapi/x-twitter-video-photo-gif-downloader").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/NASA/status/2075249100035866880"], "handles": [], "searchQueries": [], "maxItems": 10, } # Run the Actor and wait for it to finish run = client.actor("lurkapi/x-twitter-video-photo-gif-downloader").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/NASA/status/2075249100035866880" ], "handles": [], "searchQueries": [], "maxItems": 10 }' | apify call lurkapi/x-twitter-video-photo-gif-downloader --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=lurkapi/x-twitter-video-photo-gif-downloader", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "X (Twitter) Video, Photo & GIF Downloader", "description": "Download videos, photos, and GIFs from X (Twitter) in bulk. Paste a tweet URL, an X handle, or a search query. Files saved for you, ready to download. Pay per media file.", "version": "0.0", "x-build-id": "McTpyLMsqc9dKdnUz" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/lurkapi~x-twitter-video-photo-gif-downloader/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-lurkapi-x-twitter-video-photo-gif-downloader", "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-video-photo-gif-downloader/runs": { "post": { "operationId": "runs-sync-lurkapi-x-twitter-video-photo-gif-downloader", "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-video-photo-gif-downloader/run-sync": { "post": { "operationId": "run-sync-lurkapi-x-twitter-video-photo-gif-downloader", "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", "properties": { "tweetUrls": { "title": "🔗 Tweet URLs / IDs", "type": "array", "description": "One tweet per entry. Accepts standard, mobile, and share links: https://x.com/user/status/123, https://twitter.com/user/status/123, https://mobile.x.com/user/status/123. Numeric tweet IDs also work.", "items": { "type": "string" } }, "handles": { "title": "👤 X handles / profile URLs", "type": "array", "description": "Usernames (e.g. NASA) or profile URLs (https://x.com/NASA). Pulls media from the user's media tab, newest first.", "items": { "type": "string" } }, "searchQueries": { "title": "🔍 Search queries", "type": "array", "description": "X advanced-search queries. Full operator syntax supported: from:elonmusk, since:2024-01-01, min_faves:100, lang:en, filter:videos, filter:images. See the operator reference: https://github.com/igorbrigadir/twitter-advanced-search. Only tweets with attached media surface in this actor.", "items": { "type": "string" } }, "mediaType": { "title": "Media type", "enum": [ "all", "video", "photo", "gif" ], "type": "string", "description": "Filter by media type. 'All' keeps everything. 'Video' keeps mp4 video clips. 'Photo' keeps jpg/png/webp images. 'GIF' keeps X's animated GIFs (served as muted mp4).", "default": "all" }, "maxItems": { "title": "Max media files per run", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Hard cap on total media files downloaded across all inputs. Each photo, video, or GIF counts as one. A tweet with 4 photos = 4 files.", "default": 100 }, "includeHighResOriginals": { "title": "High-resolution originals ($)", "type": "boolean", "description": "Get photos at the original size the creator uploaded, not the compressed version X shows on the site. Phone shots often come back much larger and sharper. Videos always come at the best available quality; no upgrade needed. Only billed on photos that arrive at full original size.", "default": false } } }, "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 } } } } } } } } } } ```