# 𝕏(twitter) Video Downloader (`truefetch/x-twitter-video-downloader`) Actor

Process one publicly accessible X post containing video for structured metadata and an optional stored video file. Choose metadata-only mode or a download quality preference.

- **URL**: https://apify.com/truefetch/x-twitter-video-downloader.md
- **Developed by:** [TrueFetch](https://apify.com/truefetch) (community)
- **Categories:** Videos, Social media, News
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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 Downloader turns one accessible X post containing video into a structured Dataset item and can optionally store the video file in Apify.

- The effective input surface has two fields and requires only one public X post URL.
- Four quality values separate metadata-only inspection from three media-download preferences.
- The output contract contains 39 fields covering the post, author, media properties, processing context, and file delivery.
- Comment retrieval is not a public feature; the reserved `comments` array is normally empty.

**[Run a one-result test](https://apify.com/truefetch/x-twitter-video-downloader)**

**[View API](https://apify.com/truefetch/x-twitter-video-downloader/api)**

Publish the Actor, use an accessible post you are authorized to process, and validate metadata before requesting a file.

### What does X Twitter Video Downloader do?

X Twitter Video Downloader handles one X post that contains a video. It reads information available to the downloader and normalizes it into an Apify Dataset record. Depending on the post and media, available values can include the post ID, text or title, thumbnail, duration, publication time, author identity, engagement counts, dimensions, frame rate, and audio labels.

When a download quality is requested, the Actor can store an available video file and return its URL. Metadata mode skips that transfer and is the appropriate first test for a new URL or access condition. Quality is a preference: the source post determines which renditions exist, so `high` is not a promise of 4K.

The public contract has no X login, cookies, profile crawler, search, thread expansion, or comments input. Protected, deleted, age-gated, region-restricted, login-gated, or otherwise unavailable posts are outside the reliable public surface.

### How do I run X Twitter Video Downloader?

Open the Actor draft in Apify Console and verify that its name and input are branded for X. Use the URL of one post, normally in `/status/<id>` form. Do not provide a profile, search result, list, bookmark page, community timeline, or an entire thread.

This README uses one illustrative scenario throughout:

```json
{
  "video_url": "https://x.com/SpaceX/status/1732824684683784516",
  "video_quality": "metadata"
}
```

Replace that URL with a currently accessible video post you have the right to test. Start with metadata and inspect **Results**. If the identity and media fields match the post, repeat with a download quality only when your workflow needs the file. Do not add credentials or undocumented fields; the schema rejects additional properties.

### What data does X Twitter Video Downloader return?

The Actor uses a 39-field cross-video contract:

| Area | Dataset fields |
|---|---|
| Processing | `processor`, `processed_at` |
| Post and media | `id`, `thumbnail`, `platform`, `title`, `description`, `duration`, `published_at` |
| Author | `author`, `author_id`, `author_url` |
| Classification | `categories`, `tags` |
| Available engagement | `view_count`, `like_count`, `shares_count`, `dislike_count`, `comment_count` |
| Media properties | `width`, `height`, `fps`, `audio_title`, `audio_artist` |
| Reserved and file | `comments`, `video` |

An abbreviated illustrative item for the same post is:

```json
{
  "id": "1796229213979111882",
  "platform": "Twitter",
  "title": "Example X video post",
  "author": "X",
  "thumbnail": "https://example.com/x-video-thumbnail.jpg",
  "duration": null,
  "comments": [],
  "video": ""
}
```

This shows the contract rather than a captured live response. X may omit fields, and access can change, so null and empty values are valid. A visible reply count is not a retrieved reply list. Metadata mode intentionally leaves `video` empty.

Source-dependent fields also present in every item:

| Field | Meaning |
|---|---|
| `source_url` | Canonical page URL of the item on its own platform |
| `media_type` | Kind of media the source reports, such as video or audio |
| `live_status` | Whether the item is a recording, currently live, or a finished stream |
| `availability` | Source visibility, such as public, unlisted, or needs\_auth |
| `age_limit` | Minimum viewer age the source enforces; zero means no restriction |
| `language` | Primary language of the item as reported by the source |
| `followers` | Follower or subscriber count of the author at processing time |
| `is_verified` | Whether the author's account carries a verified badge |
| `saves_count` | Times viewers saved the item, on sources that expose it |
| `file_ext` | Container extension of the selected media, such as mp4 or webm |
| `file_size` | Size of the selected media in bytes, exact or approximate |
| `subtitles` | Language codes of published subtitle tracks; auto-captions excluded |
| `chapters` | Chapter markers with title and start and end time in seconds |

### What inputs can I configure?

The effective schema offers:

| Input | Required | Meaning |
|---|---:|---|
| `video_url` | Yes | One publicly accessible X post URL containing video. |
| `video_quality` | No | `metadata`, `low`, `medium`, or `high`; metadata skips file storage. |

The URL field contains a status-link example. The optional quality field has no prefill, preserving whether the caller explicitly chose a mode; the runtime falls back to metadata when it is omitted. There is no comment-limit property because X replies are not a supported public retrieval feature in this Actor.

No username, profile, hashtag, query, date, language, country, batch, thread, cookie, or credential filter exists. A caller that needs several posts must submit separate runs or orchestrate them externally.

### What platforms and markets does X Twitter Video Downloader cover?

Coverage is URL-based rather than country-based. The intended input is an individual video post on X; legacy `twitter.com` status links may be recognized by the underlying extractor, but release tests should prioritize current `x.com` URLs.

There is no market or language filter. Post availability can depend on deletion, author protection, account state, age controls, region rules, guest access, and X platform changes. A post that opens in a signed-in browser is not necessarily public to an Actor without credentials.

Before release, use a small access matrix: one clearly public video post, one public text-only post, one deleted post, and one protected or login-gated post. Expect a normalized item only when accessible video media exists. Keep the input, run status, redacted logs, and output shape for each case so the boundary is reviewable.

### Why use X Twitter Video Downloader?

The Actor can turn an authorized X video post into data that is easier to automate than a manual browser workflow. A communications team can preserve the post ID, publication time, author, thumbnail, and available engagement values alongside an approved media file. A researcher can create a reproducible record for one cited post. A developer can connect the Dataset result to a webhook or downstream media pipeline.

Metadata-first testing reduces transfer and exposes access problems before file work. The thumbnail-first Dataset overview makes individual media records easier to recognize. Nullable fields prevent the documentation from pretending that X exposes every cross-platform metric.

### Who is X Twitter Video Downloader for?

Developers can add a one-post ingestion step to an application. Media, communications, trust-and-safety, and research teams can document publicly accessible video posts within their permissions and retention policies. AI teams can send an authorized stored file to a separate transcription, caption, or classification tool.

Console users can test one post without writing code after the Actor is published.

This Actor is not a profile scraper, search API, thread reader, replies collector, audience monitor, protected-content bypass, or rights-clearance service. It does not determine whether downloading or retaining a post is lawful for a particular purpose; the caller remains responsible for authorization, platform terms, privacy, and storage policy.

### How can I use X Twitter Video Downloader through the API or MCP?

The following request uses the same illustrative post:

```bash
curl -X POST "https://api.apify.com/v2/acts/truefetch~x-twitter-video-downloader/runs?token=$APIFY_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"video_url":"https://x.com/SpaceX/status/1732824684683784516","video_quality":"metadata"}'
```

The matching hosted MCP configuration and example arguments are:

```json
{
  "mcpServers": {
    "apify-x-video": {
      "url": "https://mcp.apify.com?tools=truefetch/x-twitter-video-downloader",
      "headers": {
        "Authorization": "Bearer <APIFY_TOKEN>"
      }
    }
  },
  "exampleToolArguments": {
    "video_url": "https://x.com/SpaceX/status/1732824684683784516",
    "video_quality": "metadata"
  }
}
```

Protect the token and follow the [official Apify MCP instructions](https://docs.apify.com/integrations/mcp).

### How much does X Twitter Video Downloader cost?

The local metadata contains flat event prices, not a verified published offer:

| Declared event | Unit | Local price |
|---|---|---:|
| `apify-actor-start` | Actor start | $0.01 |
| `actor_usage` | Metered usage event | $0.00001 |
| `metadata` | One post processed without file download | $0.11 |
| `download` | One post processed with file storage | $0.24 |

The smallest metadata run declares $0.12 in fixed start and metadata events, before metered usage or platform costs. A download uses the $0.24 event instead of the metadata event.

Verify publication settings and the completed run’s charges before scaling. No volume tiers or discounts are present locally.

### How does X Twitter Video Downloader compare with alternatives?

| Option | Good fit | Limitation |
|---|---|---|
| X Twitter Video Downloader | One accessible X video post needs normalized metadata or a stored file | Publication and representative access tests remain pending. |
| Manual browser workflow | A person needs to inspect or save one permitted post | Harder to integrate with Dataset, API, and repeatable automation. |
| X API | An authorized application needs supported platform data endpoints | Access, fields, quotas, and media delivery follow X’s current API product. |
| Best Video Downloader | Input URLs span multiple supported video hosts | Broader scope with fewer X-specific access explanations. |

Choose based on the needed contract. This Actor is narrow and media-focused; the official API is the appropriate reference when the requirement is broader X data access.

### What are the limits and troubleshooting steps?

Only one post URL is accepted. There are no credentials, profile, thread, search, batch, comments, or market controls. Fields can be null, and quality is a preference. Repeating a run creates another processing attempt rather than deduplicating an earlier Dataset item.

If metadata fails, open the exact post in a private browser window. Confirm that it contains video and does not require login. Remove tracking fragments, preserve the `/status/<id>` URL, and retry metadata mode. A text-only post is not a valid video result.

If `video` remains empty after a download request, inspect the run log and key-value store. The source may offer no compatible media, or the post may have become unavailable. Never treat a missing engagement value as a measured zero. The Store and Issues surfaces were unavailable at the checkpoint, so live defect history is unknown.

X can delete posts, protect accounts, suspend authors, or change guest media access after a successful run. Scheduled workflows must expect later failure and must not use an older stored file as proof that the source is still public.

### Frequently asked questions

#### Does it download an entire X profile or thread?

No. It accepts one post URL per run.

#### Can it retrieve replies or comments?

No public comments input exists; the reserved array is normally empty.

#### Can it access protected posts?

No login or cookie input exists. Use only genuinely accessible posts.

#### Does high quality guarantee 4K?

No. The source post’s available renditions determine the result.

#### Why are some engagement fields null?

The extractor did not receive those values. Null is not zero.

#### Can I use a `twitter.com` link?

The underlying extractor may recognize legacy status links, but current `x.com` status URLs are the primary release target.

#### Can I schedule the Actor?

Yes, but a schedule repeats one configured URL and availability may change.

#### What happens if the post has no video?

The run ends without a Dataset item and no result event is charged. A text-only post, an image post, or a quote tweet whose media belongs to the quoted post all produce this outcome. Submit the status URL that actually hosts the video.

#### Which post URL should I submit for a thread?

Use the status URL of the individual post that carries the video, not the thread root. Each run resolves exactly one status, so a thread containing several videos needs one run per post.

#### How do I keep costs predictable across many posts?

Each run processes exactly one status and writes at most one Dataset item, so cost scales linearly with the number of posts you submit rather than with thread length or video duration. Stay in `metadata` mode while you validate that your status URLs resolve, then promote only the posts you actually need as files. Because a post without playable video ends the run with no Dataset item, failed lookups do not add result charges, and an account-level spending limit remains the reliable ceiling for a large batch.

### Related TrueFetch Actors

- [Best Video Downloader](https://apify.com/truefetch/best-video-downloader) handles mixed video-host inputs.
- [Video To Text](https://apify.com/truefetch/video-to-text) produces a speech transcript from authorized media.
- [Video Subtitles Downloader](https://apify.com/truefetch/video-subtitles-downloader) retrieves available caption tracks.

### Support

- [Apify Actor dashboard](https://apify.com/truefetch/x-twitter-video-downloader)
- [Apify Actor API reference](https://apify.com/truefetch/x-twitter-video-downloader/api)
- [Apify MCP documentation](https://docs.apify.com/integrations/mcp)
- [yt-dlp supported-sites reference](https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md)
- [TrueFetch community](https://t.me/TrueFetch)
- [Direct support](https://t.me/AiAgentApi)

Include the public Actor link, stable ID, redacted input, access condition, and run ID in support requests.

**[Run a one-result test](https://apify.com/truefetch/x-twitter-video-downloader)**

**[View API](https://apify.com/truefetch/x-twitter-video-downloader/api)**

# Actor input Schema

## `video_url` (type: `string`):

Publicly accessible X post URL containing one video.

## `video_quality` (type: `string`):

Preferred download quality, or metadata-only mode without a video file.

## Actor input object example

```json
{
  "video_url": "https://x.com/SpaceX/status/1732824684683784516"
}
```

# Actor output Schema

## `results` (type: `string`):

All video details and optional download links with full engagement stats and comments

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "video_url": "https://x.com/SpaceX/status/1732824684683784516"
};

// Run the Actor and wait for it to finish
const run = await client.actor("truefetch/x-twitter-video-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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "video_url": "https://x.com/SpaceX/status/1732824684683784516" }

# Run the Actor and wait for it to finish
run = client.actor("truefetch/x-twitter-video-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 '{
  "video_url": "https://x.com/SpaceX/status/1732824684683784516"
}' |
apify call truefetch/x-twitter-video-downloader --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=truefetch/x-twitter-video-downloader",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/vmK13aug1pQtO11XF/builds/XOjmu6RLssLLcspJa/openapi.json