# TikTok Trending Videos Scraper - Top Videos & History API (`trendingtiktoksongs/tiktok-trending-videos-history`) Actor

Find trending and popular TikTok videos in the US, Japan, Vietnam, Thailand and Indonesia. Export up to 100 top videos per 7/30-day chart with links, creators, views, rank changes and stored history to track video trends. JSON, CSV or API. No TikTok login. Commercial-content charts; dates may lag.

- **URL**: https://apify.com/trendingtiktoksongs/tiktok-trending-videos-history.md
- **Developed by:** [Trending TikTok Data](https://apify.com/trendingtiktoksongs) (community)
- **Categories:** Social media, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 video observations

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

Find **trending TikTok videos in the US, Japan, Vietnam, Thailand and Indonesia**. Export video links, creators, views and rank changes as JSON or CSV. No TikTok login or proxy configuration is required.

Choose seven-day or thirty-day rankings and export up to 100 videos per chart. Filter US videos by beauty, fashion or lifestyle, compare total and organic views, and track changes across available history.

Use the dataset to find video ideas for your market, compare creative examples and build recurring trend reports. Latest mode returns the newest available rankings; the reporting date is included in every result. These are commercial-content charts, and reporting dates can lag collection dates.

### Export the latest TikTok trending videos

The default exports 10 observations from the latest stored source date:

```json
{ "mode": "latest", "selection": "all", "maxRows": 10 }
```

Set `maxRows` to 100 to export the full available selection. Results include video links and exact video IDs, captions, creator handles and follower counts, period views, lifetime views, organic views, engagement rates and category labels when TikTok supplies them. Media files are not downloaded.

### Trending TikTok videos by country

Use `country` to choose US, Japan, Vietnam, Thailand or Indonesia. The default is `US`.

```json
{ "country": "JP", "mode": "latest", "selection": "all", "periodDays": 30, "maxRows": 100 }
```

Japan (`JP`), Vietnam (`VN`), Thailand (`TH`) and Indonesia (`ID`) support both windows with `category: "all"` and `selection: "all"`. Regional history includes only dates actually archived; the coverage summary lists missing dates. Country identifies the requested TikTok chart market and does not establish a creator's nationality.

### 7-day and 30-day top TikTok videos by category

Choose a chart window with `periodDays` and a category with `category`. The defaults are `7` and `all`.

```json
{ "mode": "latest", "selection": "all", "periodDays": 30, "category": "beauty", "maxRows": 100 }
```

Available categories are `all`, `beauty` (Beauty & Care), `fashion` and `lifestyle` (Lifestyle & Leisure). For US charts, each works with both windows and both selection filters. The chart window describes the measured views; videos can have been posted earlier. A category chart can contain fewer than 100 videos, including zero.

### TikTok organic views vs total views

```json
{ "mode": "latest", "selection": "organic_filter", "maxRows": 100 }
```

For US charts, this uses TikTok's `organicOnly` selection filter. It does **not** mean every reported view is organic. Compare `period_organic_views` with `period_views` and inspect `organic_view_share`. The ratio is expressed from 0 to 1.

### TikTok trending video history and rank changes

```json
{ "mode": "history", "selection": "all", "days": 7, "maxRows": 700 }
```

History returns stored observations in source-date order, then rank order. Use the same `periodDays` and `category` fields to export a specific chart. `days` controls how many archived source dates are requested; `periodDays` controls the chart window. You can use `fromDate` and `toDate` instead of `days`, for a fixed range of up to 30 days. Dates use UTC. History only includes dates actually archived; the run's `OUTPUT` record lists available and missing dates. A video appearing on three dates produces three billable observations.

`rank_change` compares a video with the immediately preceding source date; positive values mean its rank improved. `new_to_chart` describes entry into this selection. `lifetime_views_change` and `lifetime_organic_views_change` compare cumulative counters on consecutive source dates. Missing baselines produce `null`. A decreased cumulative counter sets `counters_revised`; its change is `null`. Comparisons stay within the same country, window, category and selection. Changes in rolling 7-day or 30-day views are not presented as newly gained views.

### Export TikTok video data as JSON, CSV or Excel

Video rows go to the default dataset. Export them as JSON, CSV, Excel or another format supported by Apify. The **Video chart changes** view shows rank and lifetime-counter changes. The `OUTPUT` record contains the resolved source date, coverage, row counts and spending-limit status.

### TikTok trending videos scraper pricing

**$3 per 1,000 video observations**, plus **$0.00005 per run start**. Apify platform usage is included in these event prices. Ten results cost $0.03005; 100 results cost $0.30005. A coverage summary is not a billable video observation.

Set `maxRows` and Apify's maximum run cost to control spending. The Actor stops writing results when the remaining result budget is exhausted and reports `truncated_by_spending_limit` in `OUTPUT`. Empty history ranges return a coverage summary and incur only the start event.

### TikTok trending videos API and scheduled exports

Call the Actor using Apify's API, save an Actor task, or schedule repeated exports in Apify Console. The Actor reads the maintained archive, so a customer run does not start a separate TikTok crawl. You need an Apify account and API token for API calls; a TikTok account is not required.

### Which TikTok videos are covered, and how fresh is the data?

These rankings come from TikTok Creative Center's commercial-content selection. They can include sponsored or campaign-related videos and older posts. The chart covers this selection rather than the entire TikTok feed or every emerging viral video. Supported countries are US, Japan, Vietnam, Thailand and Indonesia. Category and organic-selection filters are available for US charts.

`source_snapshot_date` is TikTok's reporting date. `collected_at` is when that snapshot was archived. Collection runs four times daily, but source dates can lag collection dates. An unchanged reporting date reuses its archived snapshot. Stable pagination keeps an export tied to the same archived data.

Stored observations do not promise unrestricted historical access to TikTok. Video links and cover URLs can expire or disappear. Missing metrics remain `null`; video and creator IDs remain strings so large IDs retain every digit.

### TikTok trending videos FAQ

#### Can I get the latest trending TikTok videos?

Use `mode: "latest"` to export the newest available rankings for your chosen country and window. Check `source_snapshot_date` for the reporting date. This is a dated ranking dataset; it does not refresh TikTok's rankings in real time when a customer starts a run.

#### Which countries have TikTok trending video charts?

Choose `US`, `JP` (Japan), `VN` (Vietnam), `TH` (Thailand) or `ID` (Indonesia), with a seven-day or thirty-day ranking window.

#### Does the organic filter exclude sponsored videos?

The source filter changes the selected chart. Returned total-view metrics can still include paid views, so inspect the separate organic counters.

#### How do I report a problem?

Open an issue on this Actor's Issues tab with the run ID, requested country, selection, chart window, category and source dates. Do not include API tokens or personal credentials.

# Actor input Schema

## `country` (type: `string`):

Choose the country for the video rankings. Category and organic filters are US-only.

## `mode` (type: `string`):

Latest exports one archived source date; history exports available observations across a date range.

## `selection` (type: `string`):

US only: the organic filter selects a different chart; reported total views can include paid views. Other countries require all.

## `periodDays` (type: `integer`):

Enter 7 or 30. This is the video chart window, separate from history days. It measures views in the window and can include older posts.

## `category` (type: `string`):

US category filters. Other countries require all. History and rank changes stay within the same country and chart.

## `maxRows` (type: `integer`):

Each exported video on a source date is one billed result. Latest rankings contain up to 100 rows per selection.

## `days` (type: `integer`):

History mode only. Omit for seven days ending on the latest archived source date. Use this or a fixed date range.

## `fromDate` (type: `string`):

Optional fixed history range; requires toDate. Omit days when using dates.

## `toDate` (type: `string`):

Last source date of a fixed history range. Requires fromDate; dates use UTC.

## Actor input object example

```json
{
  "country": "US",
  "mode": "latest",
  "selection": "all",
  "periodDays": 7,
  "category": "all",
  "maxRows": 10
}
```

# Actor output Schema

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

No description

## `coverage` (type: `string`):

No description

## `changes` (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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("trendingtiktoksongs/tiktok-trending-videos-history").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("trendingtiktoksongs/tiktok-trending-videos-history").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 '{}' |
apify call trendingtiktoksongs/tiktok-trending-videos-history --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,trendingtiktoksongs/tiktok-trending-videos-history"
        }
    }
}
```

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/DbwdNgRDNJOEFO24X/builds/gOPQghY0h22nBPW9s/openapi.json