X (Twitter) Media Scraper & Downloader

X (Twitter) Media Scraper & Downloader

This Actor helps teams and AI agents retrieve media from public X tweets and profiles through Apify. It accepts either one or more tweet URLs or one or more profile handles, then returns one dataset record per media item found. Each record can include the tweet URL, author, media type, media URL, thumbnail URL, tweet date, like count, and duration in milliseconds for video or GIF content. When saveToKeyValueStore is enabled, the Actor also stores downloaded files in the media key-value store for archiving workflows.

Best fit and connected workflows

This Actor fits workflows that need media extraction from public X content, such as:

• pulling all photos, videos, and animated GIFs from a specific tweet
• collecting recent media posts from a profile by handle
• preparing media datasets for review, tagging, or downstream automation
• archiving source media alongside dataset metadata
• using Apify MCP in an agent workflow that needs structured media links and storage keys

It is designed as an Apify Actor usable through Apify MCP, with provider-backed execution from the primary and fallback data providers.

Practical scenario

Maya, a social media analyst, starts with a list of three public X profile handles for event coverage. She sends the handles into this Actor with the default media types and a scan limit per handle. The returned dataset gives her one record for each media item, including the post URL, author, media type, direct media URL, thumbnail, and engagement fields such as likes. She uses those records to identify which posts are worth forwarding to a review queue, then passes the media URLs into a downstream asset organizer.

Focused standalone workflow

X (Twitter) Media Scraper & Downloader is designed as a focused standalone workflow.

Input

Input fields

Field	Type	Required	Description
tweetUrls	array of strings	No	One or more tweet URLs to extract media from. Each URL is fetched and all photos, videos, and GIFs in the tweet are returned.
handles	array of strings	No	X usernames or handles, with or without @, for bulk-scraping recent media from a profile timeline.
maxTweetsPerHandle	integer	No	Maximum number of recent tweets to scan per handle. Minimum 1, maximum 200, default 15.
mediaTypes	array of strings	No	Media types to include: photo, video, animated_gif. Default includes all three.
saveToKeyValueStore	boolean	No	When enabled, each media file is downloaded and saved in the media key-value store, and the dataset row includes kvKey.

Focused JSON input example

{
  "handles": ["NASA", "SpaceX"],
  "maxTweetsPerHandle": 20,
  "mediaTypes": ["photo", "video"],
  "saveToKeyValueStore": true
}

Output

The main output is a dataset of media items. The dataset view in the live contract surfaces these fields:

Field	Type	Description
tweetUrl	string	Full tweet URL for the media item.
author	string	Author display name.
mediaType	string	Media type such as photo, video, or animated_gif.
mediaUrl	string	Direct media URL.
thumbnailUrl	string	Thumbnail or cover image URL.
tweetDate	string	Tweet posting date.
likeCount	number	Like count recorded for the tweet.
durationMs	number	Duration in milliseconds for video or animated GIF media.

Illustrative dataset record

{
  "tweetUrl": "https://x.com/example/status/1234567890",
  "author": "Example Account",
  "mediaType": "video",
  "mediaUrl": "https://video.twimg.com/example.mp4",
  "thumbnailUrl": "https://pbs.twimg.com/example.jpg",
  "tweetDate": "Mon Jan 01 00:00:00 +0000 2026",
  "likeCount": 1234,
  "durationMs": 31533
}

The Actor also writes summary records to key-value storage for OUTPUT and RUN_SUMMARY, and exposes the dataset items through the default dataset URL.

How it works

The Actor accepts either tweet URLs or profile handles. For tweet URLs, it fetches each tweet and returns the media attached to that tweet. For profile handles, it scans recent tweets up to maxTweetsPerHandle and returns the media tweets it finds. The mediaTypes setting controls which media classes are included. When saveToKeyValueStore is enabled, downloaded files are stored in the media key-value store and the dataset row includes a kvKey reference.

The live contract also shows the Actor running with Apify default run options of 256 MB memory and a 300 second timeout.

Pricing

X (Twitter) Media Scraper & Downloader uses Pay per event pricing on the Apify platform. One event is charged when the Actor starts, and another event is charged for each media item saved to the dataset. Platform usage such as storage and execution resources can also apply, especially when saveToKeyValueStore is enabled.

For the current pricing details, see the live Pricing tab in the Apify Console.

As a simple example, if a run finds ten media items, the billed events include one Actor start and ten media item events.

Use with AI agents (MCP)

This Actor is available as an Apify Actor usable through Apify MCP. The tool is built for agent workflows that need to request X media extraction, then read back structured dataset items and storage references.

Actor identity: khadinakbar/x-media-scraper

Extract media from these public X posts and profiles, return the dataset rows, and include any kvKey values when media files are stored. Prefer the dataset output for structured fields and use the key-value store references only when the run is configured to save files.

Output interpretation

• datasetItems points to the dataset items endpoint.
• outputSummary points to the OUTPUT record in key-value storage.
• runSummary points to the RUN_SUMMARY record in key-value storage.
• Each dataset row represents one media item found in a tweet or profile scan.
• If saveToKeyValueStore is true, kvKey identifies the stored file in the media store.

Scope and provenance

The returned data is derived from public X content provided through the Actor's provider-backed execution. The live contract identifies the primary data provider, the fallback data provider, and the optional the routing options listed in the input schema environment variables.

Pagination and cost guidance

When working from profile handles, the Actor scans recent tweets up to maxTweetsPerHandle. More scanned tweets can produce more media items and therefore more charged events. For agent workflows, it is often useful to start with a smaller scan limit, inspect the dataset, then expand the scan if needed.

Apify API example

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({
  token: process.env.APIFY_TOKEN,
});

const input = {
  tweetUrls: ['https://x.com/NASA/status/1895937985895723209'],
};

const run = await client.actor('khadinakbar/x-media-scraper').call(input);

const dataset = await client.dataset(run.defaultDatasetId).listItems();
console.log(dataset.items);

Best results and outcome guidance

Use tweet URLs when you already know the exact post and want only the media attached to it. Use handles when you want to review recent media from a profile in bulk. Keep mediaTypes aligned with the asset classes you need so the returned dataset stays focused. Turn on saveToKeyValueStore when you need stored file references for archiving or follow-up processing.

Design note

I found that the live output contract surfaces three top-level records: datasetItems, outputSummary, and runSummary, while the dataset view itself focuses on the media fields that matter most for downstream processing.

FAQ

Can I use tweet URLs and handles in the same run?

Yes. The input schema supports both tweetUrls and handles, so one run can target specific posts and also scan recent media from profiles.

What media types can this Actor return?

The input schema includes photo, video, and animated_gif. All three are included by default.

What changes when saveToKeyValueStore is enabled?

Each media file is downloaded into the media key-value store, and the dataset row includes a kvKey that points to the saved object.

What does one dataset record represent?

One record represents one media item found in a tweet or profile scan, not the entire profile or tweet by itself.

Is this Actor suitable for Apify MCP workflows?

Yes. It is described in the live contract as MCP-ready and can be used through Apify MCP as an Apify Actor.

Responsible use

X and Twitter is a trademark of its owner. This independent Actor is not affiliated with, associated with, or endorsed by X and Twitter.

Use this Actor only with content and workflows you are authorized to access and process. Respect applicable laws, platform terms, and rights associated with the media you handle.