Twitter (X) Media Downloader

{
  "properties": {
    "audioFormat": {
      "default": "m4a",
      "description": "Format used when Audio only is on.",
      "editor": "select",
      "enum": [
        "m4a",
        "mp3"
      ],
      "enumTitles": [
        "M4A (AAC, smaller, native)",
        "MP3 (widest compatibility)"
      ],
      "prefill": "m4a",
      "title": "Audio file format",
      "type": "string"
    },
    "audioOnly": {
      "default": false,
      "description": "Download only the audio track of videos. Photos and GIFs are skipped. Files are extracted with ffmpeg and file saving is enabled automatically.",
      "prefill": false,
      "title": "Audio only (extract sound from videos)",
      "type": "boolean"
    },
    "downloadAllQualities": {
      "default": false,
      "description": "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.",
      "prefill": false,
      "title": "Download every video quality",
      "type": "boolean"
    },
    "imageQuality": {
      "default": "orig",
      "description": "Quality to use for photos (and video poster images). Original is the full-resolution file posted on X.",
      "editor": "select",
      "enum": [
        "orig",
        "large",
        "medium",
        "small"
      ],
      "enumTitles": [
        "Original (highest quality)",
        "Large",
        "Medium",
        "Small (lightest)"
      ],
      "prefill": "orig",
      "title": "Photo quality",
      "type": "string"
    },
    "includeAltText": {
      "default": true,
      "description": "Attach the alt text (image description) X stores for each photo or video thumbnail to the media row.",
      "prefill": true,
      "title": "Include image alt text",
      "type": "boolean"
    },
    "includeMetadata": {
      "default": true,
      "description": "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.",
      "prefill": true,
      "title": "Include post and author metadata",
      "type": "boolean"
    },
    "includePosterImage": {
      "default": true,
      "description": "Save the thumbnail/poster image of each video or GIF as an additional photo file.",
      "prefill": false,
      "title": "Also save video poster images",
      "type": "boolean"
    },
    "includeQuotedMedia": {
      "default": true,
      "description": "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\".",
      "prefill": true,
      "title": "Include media from quoted posts",
      "type": "boolean"
    },
    "maxItems": {
      "default": 100,
      "description": "Hard cap on dataset rows for the whole run. The actor stops collecting and downloading once this many files are emitted.",
      "maximum": 10000,
      "minimum": 1,
      "prefill": 1,
      "title": "Maximum media files to collect",
      "type": "integer"
    },
    "maxPostsPerUser": {
      "default": 20,
      "description": "How many of each profile's most recent media posts to look at. Posts without matching media or filtered-out posts are skipped.",
      "maximum": 1000,
      "minimum": 1,
      "prefill": 1,
      "title": "Maximum media posts to check per username",
      "type": "integer"
    },
    "mediaTypes": {
      "default": [
        "video",
        "photo",
        "gif"
      ],
      "description": "Choose which kinds of media to download. All types are selected by default.",
      "editor": "select",
      "items": {
        "enum": [
          "video",
          "photo",
          "gif"
        ],
        "enumTitles": [
          "Videos",
          "Photos",
          "GIFs"
        ],
        "type": "string"
      },
      "prefill": [
        "video",
        "photo",
        "gif"
      ],
      "title": "Media types to download",
      "type": "array"
    },
    "minLikes": {
      "default": 0,
      "description": "When scanning usernames, skip posts with fewer likes than this. Posts whose like count is unknown are kept. Leave at 0 to keep every post.",
      "maximum": 1000000000,
      "minimum": 0,
      "prefill": 0,
      "sectionCaption": "Profile filters",
      "sectionDescription": "Optional filters applied while scanning usernames. Directly linked posts are always collected.",
      "title": "Minimum likes (profile scans)",
      "type": "integer"
    },
    "minRetweets": {
      "default": 0,
      "description": "When scanning usernames, skip posts with fewer reposts than this. Posts whose repost count is unknown are kept. Leave at 0 to keep every post.",
      "maximum": 1000000000,
      "minimum": 0,
      "prefill": 0,
      "title": "Minimum reposts (profile scans)",
      "type": "integer"
    },
    "onlyVerifiedAuthors": {
      "default": false,
      "description": "When scanning usernames, skip posts whose author is not verified. Posts where verification is unknown are kept.",
      "prefill": false,
      "title": "Only verified authors (profile scans)",
      "type": "boolean"
    },
    "postUrls": {
      "description": "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.",
      "editor": "stringList",
      "example": [
        "https://x.com/NASA/status/2107095768821576019",
        "2107516524965794217"
      ],
      "items": {
        "type": "string"
      },
      "prefill": [
        "https://x.com/NASA/status/2107095768821576019"
      ],
      "title": "Post links or IDs",
      "type": "array"
    },
    "saveToFile": {
      "default": true,
      "description": "Download each file into this run's key-value store and add a public signed download link. Turn off to collect metadata and direct CDN links only.",
      "prefill": false,
      "title": "Save files and return download links",
      "type": "boolean"
    },
    "usernames": {
      "description": "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.",
      "editor": "stringList",
      "example": [
        "NASA",
        "https://x.com/elonmusk"
      ],
      "items": {
        "type": "string"
      },
      "prefill": [],
      "title": "Usernames or profile links to scan",
      "type": "array"
    },
    "videoQuality": {
      "default": "best",
      "description": "Preferred video resolution. The actor picks the closest available quality when the exact one is not offered.",
      "editor": "select",
      "enum": [
        "best",
        "2160p",
        "1080p",
        "720p",
        "480p",
        "worst"
      ],
      "enumTitles": [
        "Best available",
        "2160p (4K)",
        "1080p (Full HD)",
        "720p (HD)",
        "480p (SD)",
        "Worst (smallest file)"
      ],
      "prefill": "best",
      "title": "Video quality",
      "type": "string"
    }
  },
  "required": [],
  "schemaVersion": 1,
  "title": "Twitter (X) Media Downloader",
  "type": "object"
}

{
  "actorOutputSchemaVersion": 1,
  "properties": {
    "files": {
      "description": "Key-value store holding the downloaded media files and their public links.",
      "template": "{{links.apiDefaultKeyValueStoreUrl}}/keys",
      "title": "Stored files",
      "type": "string"
    },
    "media": {
      "description": "One row per downloaded video, photo, GIF, audio track or poster image, with media metadata and a public download link. Status rows explain deleted, protected or media-less posts.",
      "template": "{{links.apiDefaultDatasetUrl}}/items",
      "title": "Downloaded media",
      "type": "string"
    }
  },
  "title": "Twitter (X) Media Downloader Output",
  "type": "object"
}

{
  "actorSpecification": 1,
  "description": "One row per downloaded file, plus status rows for failures.",
  "fields": {
    "properties": {
      "altText": {
        "description": "Image description X stores for the photo or video thumbnail.",
        "title": "Alt text",
        "type": "string"
      },
      "audioFormat": {
        "description": "Audio container used when the audio-only option is on.",
        "enum": [
          "m4a",
          "mp3"
        ],
        "title": "Audio format",
        "type": "string"
      },
      "collectedAt": {
        "description": "UTC timestamp when the row was created.",
        "example": "2026-10-06T18:53:49+00:00",
        "title": "Data collected at",
        "type": "string"
      },
      "downloadStatus": {
        "description": "finished, failed or notDownloaded.",
        "enum": [
          "finished",
          "failed",
          "notDownloaded"
        ],
        "title": "Download status",
        "type": "string"
      },
      "downloadUrl": {
        "description": "Public signed download link for the stored file.",
        "example": "https://api.apify.com/v2/key-value-stores/STORE/records/file.mp4?signature=...",
        "title": "Download URL",
        "type": "string"
      },
      "durationSeconds": {
        "description": "Video or GIF duration.",
        "example": 13.3,
        "title": "Duration (seconds)",
        "type": "number"
      },
      "fileSizeBytes": {
        "description": "Real size of the downloaded file.",
        "example": 3178943,
        "title": "File size (bytes)",
        "type": "integer"
      },
      "filename": {
        "description": "File name used in the key-value store.",
        "example": "2107095768821576019_video_1.mp4",
        "title": "File name",
        "type": "string"
      },
      "height": {
        "description": "Media height in pixels.",
        "example": 1080,
        "title": "Height",
        "type": "integer"
      },
      "likeCount": {
        "description": "Number of likes on the post.",
        "title": "Likes",
        "type": "integer"
      },
      "mediaSource": {
        "description": "post for the post's own media, quoted post for media inside a quoted post, poster image for a video thumbnail.",
        "enum": [
          "post",
          "quoted post",
          "poster image"
        ],
        "title": "Media source",
        "type": "string"
      },
      "mediaType": {
        "description": "video, photo or gif.",
        "enum": [
          "video",
          "photo",
          "gif"
        ],
        "title": "Media type",
        "type": "string"
      },
      "mediaUrl": {
        "description": "Media URL with the selected photo quality applied (videos/GIFs use the chosen stream).",
        "example": "https://pbs.twimg.com/media/ABC123?format=jpg&name=large",
        "title": "Media URL",
        "type": "string"
      },
      "mediaUrlOriginal": {
        "description": "Untouched X CDN URL of the media, without the quality parameter.",
        "example": "https://pbs.twimg.com/media/ABC123",
        "title": "Original media URL",
        "type": "string"
      },
      "message": {
        "description": "Human-friendly status or failure message.",
        "title": "Message",
        "type": "string"
      },
      "posterImageUrl": {
        "description": "Poster image URL on video/GIF rows when includePosterImage is on, with the selected photo quality applied.",
        "title": "Poster image URL",
        "type": "string"
      },
      "retweetCount": {
        "description": "Number of reposts on the post.",
        "title": "Reposts",
        "type": "integer"
      },
      "status": {
        "description": "Status code on status rows.",
        "enum": [
          "noInput",
          "invalidLink",
          "invalidUsername",
          "notFound",
          "rateLimited",
          "error",
          "noMatchingMedia",
          "noRecords"
        ],
        "title": "Status code",
        "type": "string"
      },
      "thumbnailUrl": {
        "description": "Preview/poster image URL for videos and GIFs.",
        "title": "Thumbnail URL",
        "type": "string"
      },
      "tweetId": {
        "description": "Numeric ID of the post the media belongs to.",
        "example": "2107095768821576019",
        "title": "Post ID",
        "type": "string"
      },
      "tweetText": {
        "description": "Text of the post.",
        "title": "Post text",
        "type": "string"
      },
      "tweetUrl": {
        "description": "Canonical URL of the post.",
        "example": "https://x.com/i/status/2107095768821576019",
        "title": "Post URL",
        "type": "string"
      },
      "type": {
        "description": "media file for a downloaded file, status for a run message.",
        "enum": [
          "media file",
          "status"
        ],
        "example": "media file",
        "title": "Row type",
        "type": "string"
      },
      "uploaderUsername": {
        "description": "Handle of the account that posted the media.",
        "example": "NASA",
        "title": "Uploader",
        "type": "string"
      },
      "username": {
        "description": "Username related to a status row.",
        "title": "Username",
        "type": "string"
      },
      "viewCount": {
        "description": "Number of views on the post.",
        "title": "Views",
        "type": "integer"
      },
      "width": {
        "description": "Media width in pixels.",
        "example": 1920,
        "title": "Width",
        "type": "integer"
      }
    },
    "required": [
      "type",
      "collectedAt"
    ],
    "type": "object"
  },
  "title": "Twitter (X) Media Downloader Output",
  "views": {
    "allRecords": {
      "display": {
        "component": "table",
        "properties": {
          "collectedAt": {
            "format": "date",
            "label": "Data collected at"
          },
          "downloadUrl": {
            "format": "link",
            "label": "Download Link"
          },
          "filename": {
            "label": "File"
          },
          "mediaType": {
            "label": "Type"
          },
          "message": {
            "label": "Message"
          },
          "status": {
            "label": "Status"
          },
          "tweetId": {
            "label": "Post ID"
          },
          "tweetUrl": {
            "format": "link",
            "label": "Post URL"
          },
          "type": {
            "label": "Row Type"
          }
        }
      },
      "title": "All records",
      "transformation": {
        "fields": [
          "type",
          "status",
          "message",
          "tweetUrl",
          "tweetId",
          "mediaType",
          "filename",
          "downloadUrl",
          "collectedAt"
        ]
      }
    },
    "mediaFiles": {
      "description": "One row per downloaded video, photo or GIF.",
      "display": {
        "component": "table",
        "properties": {
          "altText": {
            "label": "Alt Text"
          },
          "collectedAt": {
            "format": "date",
            "label": "Data collected at"
          },
          "contentType": {
            "label": "Content type"
          },
          "downloadStatus": {
            "label": "Status"
          },
          "downloadUrl": {
            "format": "link",
            "label": "Download Link"
          },
          "durationSeconds": {
            "format": "number",
            "label": "Duration (s)"
          },
          "fileSizeBytes": {
            "format": "number",
            "label": "Size (bytes)"
          },
          "filename": {
            "label": "File"
          },
          "height": {
            "format": "number",
            "label": "Height"
          },
          "mediaId": {
            "label": "Media ID"
          },
          "mediaType": {
            "label": "Type"
          },
          "mediaUrl": {
            "format": "link",
            "label": "Media URL"
          },
          "mediaUrlOriginal": {
            "format": "link",
            "label": "Original Media URL"
          },
          "postedAt": {
            "format": "date",
            "label": "Posted at"
          },
          "posterImageUrl": {
            "format": "image",
            "label": "Poster Image"
          },
          "quoteCount": {
            "format": "number",
            "label": "Quotes"
          },
          "quotedTweetUrl": {
            "format": "link",
            "label": "Quoted post"
          },
          "tweetUrl": {
            "format": "link",
            "label": "Post URL"
          },
          "uploaderName": {
            "label": "Uploader name"
          },
          "uploaderUsername": {
            "label": "Uploader"
          },
          "uploaderVerified": {
            "label": "Verified"
          },
          "width": {
            "format": "number",
            "label": "Width"
          }
        }
      },
      "title": "Downloaded media",
      "transformation": {
        "fields": [
          "tweetUrl",
          "uploaderUsername",
          "mediaType",
          "filename",
          "fileSizeBytes",
          "width",
          "height",
          "durationSeconds",
          "mediaUrl",
          "mediaUrlOriginal",
          "posterImageUrl",
          "altText",
          "downloadUrl",
          "downloadStatus",
          "postedAt",
          "contentType",
          "mediaId",
          "uploaderName",
          "uploaderVerified",
          "quoteCount",
          "quotedTweetUrl",
          "collectedAt"
        ]
      }
    }
  }
}