Twitter (X) Media Downloader: MCP config, n8n workflow and API

{
  "postUrls": [
    "https://x.com/NASA/status/2107095768821576019"
  ],
  "maxPostsPerUser": 1,
  "maxItems": 1,
  "mediaTypes": [
    "video",
    "photo",
    "gif"
  ],
  "imageQuality": "orig",
  "videoQuality": "best",
  "downloadAllQualities": false,
  "includePosterImage": false,
  "includeAltText": true,
  "audioOnly": false,
  "audioFormat": "m4a",
  "includeQuotedMedia": true,
  "includeMetadata": true,
  "minLikes": 0,
  "minRetweets": 0,
  "onlyVerifiedAuthors": false,
  "saveToFile": false
}

---
name: twitter-x-media-downloader
description: "Download videos, photos, GIFs, audio and poster images from public Twitter/X posts - no login, no cookies. Works with post links or usernames, supports every video quality, audio-only M4A/MP3, quoted-post media and public signed download links. Runs the Apify Actor dataspryva/twitter-x-media-downloader. Use when the user needs X (Twitter) data with fields such as type, tweetId, tweetUrl, mediaType, mediaUrl, mediaUrlOriginal and an Apify token is available."
compatibility: "Needs network access, curl, and an APIFY_TOKEN environment variable. Runs are billed to the token owner's Apify account."
metadata:
  actor: "dataspryva/twitter-x-media-downloader"
  store-url: "https://apify.com/dataspryva/twitter-x-media-downloader"
---

# Twitter (X) Media Downloader

Use this skill to fetch X (Twitter) data with the Apify Actor `dataspryva/twitter-x-media-downloader` and work with the returned rows.

## Before running

1. Check that `APIFY_TOKEN` is set in the environment. Never print it or write it to a file.
2. Build `input.json` from the user's request using the fields below. Keep limits small for a first run.
3. Confirm the search terms or URLs with the user if the request is ambiguous.

## Input fields

| Field | Type | Meaning |
| --- | --- | --- |
| `postUrls` | array | Paste links of posts to download media from. Accepts x.com and twitter.com links, i/web/status links, or bare post IDs. Optional if you provide usernames or profile links below. |
| `usernames` | array | Scan a profile's media posts and download their photos, videos and GIFs. Type handles with or without @, or paste full profile links. Optional if you provide post links above. |
| `maxPostsPerUser` | integer | How many of each profile's most recent media posts to look at. Posts without matching media or filtered-out posts are skipped. |
| `maxItems` | integer | Hard cap on dataset rows for the whole run. The actor stops collecting and downloading once this many files are emitted. |
| `mediaTypes` | array | Choose which kinds of media to download. All types are selected by default. |
| `imageQuality` | one of `orig`, `large`, `medium`, `small` | Quality to use for photos (and video poster images). Original is the full-resolution file posted on X. |
| `videoQuality` | one of `best`, `2160p`, `1080p`, `720p`, `480p`, `worst` | Preferred video resolution. The actor picks the closest available quality when the exact one is not offered. |
| `downloadAllQualities` | boolean | Emit and download one separate file for every progressive MP4 quality X offers (for example 1080p, 720p, 480p) instead of only the preferred one. Every quality gets its own row, filename and download link. |
| `includePosterImage` | boolean | Save the thumbnail/poster image of each video or GIF as an additional photo file. |
| `includeAltText` | boolean | Attach the alt text (image description) X stores for each photo or video thumbnail to the media row. |
| `audioOnly` | boolean | Download only the audio track of videos. Photos and GIFs are skipped. Files are extracted with ffmpeg and file saving is enabled automatically. |
| `audioFormat` | one of `m4a`, `mp3` | Format used when Audio only is on. |
| `includeQuotedMedia` | boolean | Also download the photos, videos and GIFs that appear inside a quoted post (a post embedded in the linked post). Those rows are marked with mediaSource "quoted post". |
| `includeMetadata` | boolean | Attach the post text, date, conversation and reply/quote flags, hashtags, mentions, links, like/repost/reply/quote/bookmark/view counts, author name, avatar, verification and follower count, and a derived engagement rate to every downloaded file. |

Example `input.json` (the Actor's published prefill):

```json
{
  "postUrls": [
    "https://x.com/NASA/status/2107095768821576019"
  ],
  "maxPostsPerUser": 1,
  "maxItems": 1,
  "mediaTypes": [
    "video",
    "photo",
    "gif"
  ],
  "imageQuality": "orig",
  "videoQuality": "best",
  "downloadAllQualities": false,
  "includePosterImage": false,
  "includeAltText": true,
  "audioOnly": false,
  "audioFormat": "m4a",
  "includeQuotedMedia": true,
  "includeMetadata": true,
  "minLikes": 0,
  "minRetweets": 0,
  "onlyVerifiedAuthors": false,
  "saveToFile": false
}
```

## Run

```bash
curl -sS -X POST "https://api.apify.com/v2/acts/dataspryva~twitter-x-media-downloader/run-sync-get-dataset-items" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d @input.json > results.json
```

The call waits for the run to finish and returns the dataset items as a JSON array. If the run needs more than 300 seconds the API answers with HTTP 408; then start the run with `POST /v2/acts/dataspryva~twitter-x-media-downloader/runs`, poll `GET /v2/actor-runs/{runId}` until `SUCCEEDED`, and read `GET /v2/datasets/{defaultDatasetId}/items`.

## Output

Each item is one record. Published fields include: `type`, `tweetId`, `tweetUrl`, `mediaType`, `mediaUrl`, `mediaUrlOriginal`, `thumbnailUrl`, `posterImageUrl`, `altText`, `filename`, `fileSizeBytes`, `width`, `height`, `durationSeconds`, `audioFormat`, `downloadUrl`, `downloadStatus`, `uploaderUsername`, `tweetText`, `likeCount`.

Summarise what was found, cite the record URLs when present, and say how many items came back. Do not invent values for empty fields.