# XFree Video Downloader (`datawatcher/xfree-video-downloader`) Actor

Downloads the video files (.mp4) of xfree.com searches, profiles, tags and video pages into your Apify storage, named creator_video-id.mp4, with the creator and OnlyFans link in the row. Optional ZIP of all files and optional full details (tags, views, likes).

- **URL**: https://apify.com/datawatcher/xfree-video-downloader.md
- **Developed by:** [DataWatcher](https://apify.com/datawatcher) (community)
- **Categories:** Videos
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $6.80 / 1,000 video file saveds

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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## XFree Video Downloader

Scrape video data from xfree.com by search, account, tag or video URL and save **each `.mp4` file** in your run's Key-Value Store. Files are named **`<creator>_video-<id>.mp4`** (for example `creatorname_video-12345.mp4`), so you sort them by creator at once. Every row has the link to the saved file and the creator's **OnlyFans link**. Get the rows as JSON, CSV or Excel, or through the **API**.

- Saved file: `storedFile` (key, public link, size in bytes, type, status).
- File names: `<creator>_video-<id>.mp4`, no folders, the same names inside `videos.zip`. A video without a creator is saved as `unknown_video-<id>.mp4`.
- Short rows by default (files first). Set `extractDetails` to `true` for the full row.
- Optional `videos.zip` with all saved files of the run (`createZip`).

Need only links and data, without files? Use the [XFree Video Scraper](https://apify.com/datawatcher/xfree-scraper).

### ⭐ Why this one

> **1️⃣ One schema across video sites.**
> All our video actors share one output schema and one input schema. Build your pipeline once: our other video actors ([Erome Video Scraper](https://apify.com/datawatcher/erome-scraper), [Redgifs Video Scraper](https://apify.com/datawatcher/redgifs-scraper), [XFree Video Scraper](https://apify.com/datawatcher/xfree-scraper), [Erome Video Downloader](https://apify.com/datawatcher/erome-video-downloader), [RedGIFs Video Downloader](https://apify.com/datawatcher/redgifs-video-downloader)) take the same input and return the same fields, so adding a site means changing the actor name, not your code.

- **Low price, no start fee.** You pay $0.008 per saved file ($8.00 per 1,000). For comparison, the busiest RedGifs downloader charges $0.009 per video and gives links only. Here you get the real files.
- **Real `.mp4` files, named for sorting.** Every video is saved as `<creator>_video-<id>.mp4` in your Key-Value Store, so a folder of downloads sorts by creator at once.
- **One ZIP when you want it.** Set `createZip` and get `videos.zip` with all files of the run under the same names.
- **OnlyFans link on every row.** `creator.onlyfansUrl` sits next to the file link, ready for your lead or creator lists.
- **Skipped and failed files are free.** The row is still returned, and you pay only for files that are saved.
- **Files first, lean rows.** Short rows by default; set `extractDetails` for views, likes, tags and links.
- **Honest runs.** `OUTPUT` counts saved, skipped and failed files, and `RUN_HEALTH` tells you if a run is not `ok`.

### 🔎 What it extracts

One row per unique video, with its file saved. The page types it reads:

| Page type | Example URL | Input to use |
|---|---|---|
| Search | `https://www.xfree.com/search?q=teen` | `searchQueries` or `startUrls` |
| Profile (account) | `https://www.xfree.com/creatorname` | `usernames` or `startUrls` |
| Tag, including language tags | `https://www.xfree.com/tag/Teen`, `https://www.xfree.com/tag/pl-Amatorzy` | `tags` or `startUrls` |
| Video page | `https://www.xfree.com/video?id=12345&user=creatorname` | `videoUrls` or `startUrls` |

- Tag names are kept exactly as the site writes them (`pl-Amatorzy`).
- Search tabs: `all` (default), `post` and `tag`.

### 🚀 How to scrape XFree videos and save the files

1. Open the actor on Apify and click **Try for free**.
2. Fill in a search, usernames or tags, or paste xfree.com URLs into `startUrls` or `videoUrls`.
3. Click **Start**.
4. Open the Output tab: **Files** links to your `.mp4` files in the Key-Value Store, **Saved files** lists the rows. Download the rows as JSON, CSV or Excel, or fetch them with the Apify API.

Example inputs:

```json
{ "videoUrls": ["https://www.xfree.com/video?id=12345&user=creatorname"] }
```

```json
{ "usernames": ["creatorname"], "maxResults": 20, "createZip": true }
```

```json
{ "tags": ["Teen"], "tagSort": "latest", "maxResults": 10, "videoQuality": "preview" }
```

```json
{ "searchQueries": [{ "query": "teen" }], "maxResults": 10, "extractDetails": true }
```

### 🔌 Run it your way

- **Schedule it** with Apify schedules.
- **Call it from the Apify API** and its clients (Python, JavaScript).
- **Connect it** to Make, n8n, Zapier, webhooks or Google Sheets.

### 💾 Where the files are

- On the Output tab, the **Files** link opens the run's default **Key-Value Store**. Each file is there as `<creator>_video-<id>.mp4`. `storedFile.url` is its public link.
- With `createZip` set to `true`, the store also holds `videos.zip` (key `videos.zip`) with all saved files, under the same names. The `OUTPUT` record has `zipUrl` (the signed link to the ZIP) and `fileCount` (files saved).
- Links are signed. A store that is not named is deleted by Apify after about 7 days. Download the files you need before that, or copy them to a named store.
- The storage is billed by Apify to your account, like any run.

`storedFile.status` says what happened to the file:

| Status | Meaning | Charged |
|---|---|---|
| `saved` | The file is in the store. | Yes, `video-file-saved`. |
| `skipped` | Not downloaded: the file is over `maxFileSizeMb`, the run reached `maxTotalDownloadMb`, the video has no file link, or the free plan limit of 50 files per run is reached. `storedFile.error` says which. | No |
| `failed` | The download failed (for example HTTP 404). One retry is made first. `storedFile.error` says why. | No |

The row of a skipped or failed file is still returned, free.

### ⚖️ Rights

Saved videos belong to their creators. You are responsible for having the right to save, keep and use them, and for following the law and xfree.com terms.

### 🎬 Quality

`videoQuality` picks the file to save: `best` is the full-quality `.mp4` (`videoFileUrl`), `preview` is the smaller copy (`previewVideoUrl`).

### 🔗 OnlyFans link

`creator.onlyfansUrl` is the creator's OnlyFans link, e.g. `https://onlyfans.com/creatorname`. It is the link button the site shows with the video. On a profile, a video without a button gets the profile's own OnlyFans link.

### ⚙️ Input

| Input | Type | Default | Range | Meaning |
|---|---|---|---|---|
| `startUrls` | list of URLs | none | xfree.com URLs | Search, profile, tag or video page URLs. The kind is found from the URL. |
| `searchQueries` | list | none | – | Items `{"query": "...", "filter": "all" \| "post" \| "tag"}`. `filter` is optional (default `all`). |
| `usernames` | list of text | none | – | Account handles, with or without `@`, or profile URLs. Every video of each account. |
| `tags` | list of text | none | – | Tag names exactly as the site writes them (e.g. `pl-Amatorzy`), or tag page URLs. |
| `tagSort` | text | empty (site default order) | `latest` or `popular` | Order of tag pages. |
| `videoUrls` | list of URLs | none | – | Video page URLs. One row per video. |
| `extractDetails` | yes/no | `false` | – | `false`: a short row, files first. `true`: the full row (views, likes, tags, tagged accounts, links) plus `storedFile`. |
| `videoQuality` | text | `best` | `best` or `preview` | Which file to save. |
| `maxFileSizeMb` | integer | `250` | 1 to 2,000 | A bigger file is skipped. |
| `maxTotalDownloadMb` | integer | `1024` | 1 to 20,000 | Files stop being saved when the saved files of the run together reach this size. |
| `createZip` | yes/no | `false` | – | Also save `videos.zip`. |
| `maxResults` | integer | `100` | 1 to 1,000 | Maximum videos returned over all inputs. The free Apify plan returns up to 1,000 results per run. |
| `maxRequests` | integer | `200` | 1 to 1,000 | Maximum page requests of the run: listing pages, load-more steps and video pages. |
| `maxPagesPerSource` | integer | `100` | 1 to 100 | Maximum listing pages for one search, profile or tag. |
| `maxScrollsPerPage` | integer | `100` | 1 to 100 | Maximum "load more" steps on one listing page. |
| `maxRequestRetries` | integer | `2` | 0 to 5 | Retries after a network error or a server error (page requests). |
| `requestTimeoutSecs` | integer | `30` | 5 to 120 | Time limit of one request, in seconds. |

Use at least one of `startUrls`, `searchQueries`, `usernames`, `tags` or `videoUrls`.

### 📦 Output: XFree video data

The short row (default) has `id`, `url`, `mediaType` (always `video` on XFree), `title`, `creator` with `onlyfansUrl`, `durationSeconds`, `width`, `height`, `imageUrl` (empty for videos), `storedFile` and `dates`. With `extractDetails` set to `true`, it also has `taggedAccounts`, `views`, `likes`, `thumbnailUrl`, `tags`, `videoFileUrl` and `previewVideoUrl`. A missing text, number or object is `null`. A missing list is `[]`.

| Field | Type | Meaning |
|---|---|---|
| `storedFile.key` | text or null | The store key of the saved file, e.g. `creatorname_video-12345.mp4`. |
| `storedFile.url` | text or null | The public link to the saved file. |
| `storedFile.sizeBytes` | integer or null | The saved file's size in bytes. |
| `storedFile.mimeType` | text or null | The file's content type, e.g. `video/mp4`. |
| `storedFile.quality` | text or null | `best` or `preview`: the copy that was saved. |
| `storedFile.status` | text | `saved`, `skipped` or `failed`. |
| `storedFile.error` | text or null | Why the file was skipped or failed; `null` when saved. |

#### Example: a row

An example row (`videoUrls` input, short row).

```json
{
  "recordType": "video",
  "source": "xfree",
  "id": "12345",
  "url": "https://www.xfree.com/video?id=12345",
  "title": "Example video title",
  "creator": { "username": "creatorname", "displayName": "Creator Name", "profileUrl": "https://www.xfree.com/creatorname", "onlyfansUrl": "https://onlyfans.com/creatorname" },
  "durationSeconds": 25.067,
  "width": 1080,
  "height": 1920,
  "storedFile": {
    "key": "creatorname_video-12345.mp4",
    "url": "https://api.apify.com/v2/key-value-stores/EXAMPLEID/records/creatorname_video-12345.mp4",
    "sizeBytes": 3706343,
    "mimeType": "video/mp4",
    "quality": "best",
    "status": "saved"
  },
  "dates": { "posted": "2025-01-01T12:00:00Z", "scraped": "2025-01-02T12:00:00Z" }
}
```

### 📊 Run stats

Each run saves two records in the key-value store. `OUTPUT` has the run counters and these for the files:

| Key | Meaning |
|---|---|
| `filesSaved`, `filesSkipped`, `filesFailed` | Files by status. |
| `fileCount` | Files saved. |
| `bytesSaved` | Total size of the saved files. |
| `zipUrl` | The signed link to `videos.zip`; `null` without a ZIP. |
| `stopReason` | The cap that ended the run: `maxResults`, `maxRequests`, `maxPagesPerSource`, `maxScrollsPerPage` or `chargeLimit`; else `null`. |

`RUN_HEALTH`: `{"status": "ok" | "degraded" | "failed", "reason": ...}`. `reason` says why a run is not `ok`, for example that some files failed.

### 💰 Pricing

Pay per event, one event: **$0.008** per saved file (**$8.00** per 1,000 files). There is no start fee. The row alone is free, and so are skipped and failed files and duplicate videos.

| Event | Price | When it is charged |
|---|---|---|
| `video-file-saved` | $0.008 ($8.00 per 1,000) | Each video file saved in your store. |

- Free plan: up to 1,000 results per run with full details, and up to 50 files saved per run. Paying plans have no cap per run.
- For comparison, the busiest RedGifs downloader charges $0.009 per video and gives links only. This actor saves the real files.

### 🎯 Use cases

- **Archive a creator's videos:** put the username in `usernames` and save every video as a named `.mp4`.
- **Build a creator and lead list:** export rows with `creator.onlyfansUrl` to Excel or CSV.
- **Collect a niche by tag or search:** run `tags` or `searchQueries` and keep the files sorted by creator.
- **Feed a pipeline:** call the actor from the API and read `storedFile.url` for each file.

### ❓ FAQ

#### How do I download XFree videos in bulk?

Add usernames, tags, searches or video URLs, set `maxResults` and click **Start**. Each video is saved as `<creator>_video-<id>.mp4`, and `createZip` adds one `videos.zip`.

#### Can I get the data through an API?

Yes. Start the actor and fetch the rows with the Apify API or its Python and JavaScript clients. `storedFile.url` in each row is the link to the file.

#### How much does it cost?

$0.008 per saved file. Skipped and failed files, and the rows alone, are free.

#### Can I use it with other video sites?

Yes. Our video actors share one schema, so the same code reads the rows of all of them. See the list below.

#### Where is the video data and where are the downloaded files?

Open the **Files** link on the Output tab of the run. Each file is there as `<creator>_video-<id>.mp4`, and `storedFile.url` in every row links to it.

#### How do I download all videos of one creator?

Put the username in `usernames`, set `maxResults`, and turn on `createZip` to get one `videos.zip`.

#### How do I export XFree videos to Excel or CSV?

Run the actor, open the Output tab and pick Excel or CSV in the export options. JSON, XML and HTML are there too, and the Apify API returns the same data.

### Data notice

This actor returns only what the site shows publicly at run time. We don't store or keep that data and are not its controller — you decide how you use it.

### 🔗 Other video scrapers (same schema)

#### XFree (this site)

- [XFree Video Scraper](https://apify.com/datawatcher/xfree-scraper): links and data

#### Erome

- [Erome Video Scraper](https://apify.com/datawatcher/erome-scraper): links and data
- [Erome Video Downloader](https://apify.com/datawatcher/erome-video-downloader): saves the video files (.mp4)

#### RedGIFs

- [Redgifs Video Scraper](https://apify.com/datawatcher/redgifs-scraper): links and data
- [RedGIFs Video Downloader](https://apify.com/datawatcher/redgifs-video-downloader): saves the video files (.mp4)

### 💬 Feedback and custom work

Need another portal, a field or a custom feed? Open an issue on the Issues tab.

# Changelog

This Actor's version history is a separate document: https://apify.com/datawatcher/xfree-video-downloader/changelog.md

# Actor input Schema

## `startUrls` (type: `array`):

Site URLs of any supported kind: search, account profile, tag or video page. The kind is found from the URL. xfree.com URLs only: https://www.xfree.com/search?q=..., https://www.xfree.com/<username>, https://www.xfree.com/tag/<tag>, https://www.xfree.com/video?id=...

## `searchQueries` (type: `array`):

Searches, each {"query": "...", "filter": "all" | "post" | "tag"} (filter optional, default "all"). A plain text line is read as {"query": text, "filter": "all"}. "post" and "tag" are the site's own search tabs (\&f=post, \&f=tag).

## `usernames` (type: `array`):

Account handles, with or without "@", or profile URLs. Every video of each account.

## `tags` (type: `array`):

Tag names exactly as the site writes them (case and prefixes kept, e.g. pl-Amatorzy), or tag page URLs.

## `tagSort` (type: `string`):

The order of tag pages. Empty - the site's default order.

## `videoUrls` (type: `array`):

Video page URLs. Each is read directly; one row per video.

## `maxResults` (type: `integer`):

Maximum number of videos returned, in total. Shared fairly over the inputs (each search, profile, tag or video URL gets its part; what one cannot fill goes to the others). Free plan Apify users get at most 1000 videos per run, whatever is set here (paying users have no cap).

## `maxRequests` (type: `integer`):

Maximum number of page requests the run makes, in total (listing pages and load-more steps; a direct video URL is one request).

## `maxPagesPerSource` (type: `integer`):

Maximum number of listing pages read for one search, profile or tag.

## `maxScrollsPerPage` (type: `integer`):

Maximum number of "Show more" / load-more steps on one listing page.

## `maxRequestRetries` (type: `integer`):

Retries of a request that failed on a network error or a server error. A block (403, 429, a challenge page) is never retried.

## `requestTimeoutSecs` (type: `integer`):

Time limit of one page request.

## `extractDetails` (type: `boolean`):

false (default): a short row, files first (id, url, title, creator, duration, size, `storedFile`, dates). true: the full row of the links actor (views, likes, tags, tagged accounts, links ...) plus `storedFile`.

## `videoQuality` (type: `string`):

Which file to save. "best" is the full-quality .mp4 (`videoFileUrl`), "preview" the smaller copy (`previewVideoUrl`).

## `maxFileSizeMb` (type: `integer`):

A video bigger than this is not saved (its `storedFile.status` is "skipped"); its row is still written.

## `maxTotalDownloadMb` (type: `integer`):

Stops saving files when the files of this run together reach this size (the rest are "skipped"); rows are still written.

## `createZip` (type: `boolean`):

Also put all saved files into one `videos.zip` in the Key-Value Store (needs disk space for the whole archive).

## Actor input object example

```json
{
  "startUrls": [
    "https://www.xfree.com/tag/Sexy"
  ],
  "searchQueries": [
    {
      "query": "teen",
      "filter": "all"
    }
  ],
  "maxResults": 100,
  "maxRequests": 200,
  "maxPagesPerSource": 100,
  "maxScrollsPerPage": 100,
  "maxRequestRetries": 2,
  "requestTimeoutSecs": 30,
  "extractDetails": false,
  "videoQuality": "best",
  "maxFileSizeMb": 250,
  "maxTotalDownloadMb": 1024,
  "createZip": false
}
```

# Actor output Schema

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

One row per item.

## `runSummary` (type: `string`):

OUTPUT: status, sources, requests used, early stop and its reason, source errors, charged events.

## `runHealth` (type: `string`):

{status, reason}: ok, degraded, or failed.

## `files` (type: `string`):

The saved video files (.mp4) in the run's Key-Value Store. With "Create ZIP", `videos.zip` is among them and its public link is `zipUrl` in the OUTPUT record.

# 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 = {
    "startUrls": [
        "https://www.xfree.com/tag/Sexy"
    ],
    "searchQueries": [
        {
            "query": "teen",
            "filter": "all"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("datawatcher/xfree-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 = {
    "startUrls": ["https://www.xfree.com/tag/Sexy"],
    "searchQueries": [{
            "query": "teen",
            "filter": "all",
        }],
}

# Run the Actor and wait for it to finish
run = client.actor("datawatcher/xfree-video-downloader").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "startUrls": [
    "https://www.xfree.com/tag/Sexy"
  ],
  "searchQueries": [
    {
      "query": "teen",
      "filter": "all"
    }
  ]
}' |
apify call datawatcher/xfree-video-downloader --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,datawatcher/xfree-video-downloader"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

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