# TikTok Public For You Video Scraper (`w3crawler/tiktok-for-you-scraper`) Actor

Capture a public snapshot of the TikTok For You page, visible video cards, page metadata, and bounded embedded data through direct HTTP and a public reader fallback.

- **URL**: https://apify.com/w3crawler/tiktok-for-you-scraper.md
- **Developed by:** [w3crawler](https://apify.com/w3crawler) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.99 / 1,000 for you videos

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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

## TikTok Public For You Page Snapshot

Capture a bounded public snapshot of `https://www.tiktok.com/foryou`. The Actor tries several direct HTTP request profiles and then a public `r.jina.ai` reader representation, parses embedded JSON/JSON-LD and visible HTML/reader content, and stores page metadata, structured entities, and visible TikTok video-card records.

This is not a logged-in personalized For You feed API. The result depends on the public representation returned to the Actor at run time; no account cookies, private recommendations, or hidden feed data are used.

### Example input

```json
{
  "limit": 5
}
```

### Example output

When visible video cards are present, a record may look like this:

```json
{
  "recordType": "tiktok_video",
  "status": "success",
  "dataAvailable": true,
  "source": "tiktok.com",
  "provenance": "public_foryou_page",
  "sourceTransport": "direct",
  "extractionMethod": "visible_video_card_parser",
  "sourceUrl": "https://www.tiktok.com/foryou",
  "videoIndex": 1,
  "videoTitle": "Public video title",
  "creatorName": "Creator",
  "videoUrl": "https://www.tiktok.com/@creator/video/1234567890",
  "metricTokens": ["12K", "340"],
  "scrapedAt": "2026-08-18T00:00:00.000Z"
}
```

If no video cards are recognizable but the public page contains structured entities, the dataset receives `structured_entity` records. If the page is blocked, empty, or unusable, the dataset receives a `tiktok-for-you-access-diagnostic` record and `OUTPUT.status` is `failed`.

### Input

- `limit` (integer, 1–20): Maximum number of page/entity/video records to store. Default: `10`.

The target URL is intentionally fixed. There is no input for profile crawling, personalized cookies, login, comments, hashtags, or arbitrary URL crawling because this local implementation does not perform those operations.

### Output and storage

Page snapshots and visible video records are written to the default dataset. The Output tab links to the dataset and to `OUTPUT` in the default key-value store.

`OUTPUT` contains the fixed target URL, transport selected (`direct` or `reader`), requested limit, stored record count, final status, and an error when the public page could not be used.

### Limitations and cost

The Actor makes bounded HTTP attempts using three direct request profiles and one public reader fallback. It does not run a browser, log in, use a personalized account, scroll indefinitely, or crawl every linked video. HTML and embedded-state markup can change, so fields are optional and visible-card parsing may return no TikTok video records.

Apify compute and HTTP traffic are the main costs. Keep `limit` small while testing and retry responsibly if the target returns a challenge or access diagnostic.

### Code structure

- `src/main.js` is the thin local entrypoint.
- `src/actor.js` owns Apify lifecycle, failure handling, and shutdown.
- `src/runner.js` contains direct/reader requests, public-page parsing, diagnostics, and output persistence.

### FAQ and disclaimer

#### Is this a personalized For You feed?

No. It is a public page snapshot without user cookies or private recommendation data.

#### Why did I receive an access diagnostic?

TikTok or the reader fallback may have returned a challenge, blocked page, short response, or markup without usable public records. Review the diagnostic and `OUTPUT` record before retrying.

#### Does it bypass TikTok access controls?

No. It does not defeat authentication, CAPTCHAs, rate limits, or other access controls.

Use public data for a legitimate purpose, follow TikTok and `r.jina.ai` terms and robots guidance, and review privacy and data-protection obligations. For support, use the Actor Issues tab.

# Actor input Schema

## `limit` (type: `integer`):

Maximum number of records to store from the public page snapshot.

## Actor input object example

```json
{
  "limit": 5
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

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

No description

# 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 = {
    "limit": 5
};

// Run the Actor and wait for it to finish
const run = await client.actor("w3crawler/tiktok-for-you-scraper").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 = { "limit": 5 }

# Run the Actor and wait for it to finish
run = client.actor("w3crawler/tiktok-for-you-scraper").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 '{
  "limit": 5
}' |
apify call w3crawler/tiktok-for-you-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,w3crawler/tiktok-for-you-scraper"
        }
    }
}
```

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/Gu5AqNujh0usDPiz3/builds/lAlw8PhCYreFhFmTS/openapi.json