# TikTok Live Scraper - Search, Status, Rankings & Gifters (`clover_folktale/tiktok-live-scraper`) Actor

Scrape TikTok LIVE: search live rooms by keyword, check whether creators or rooms are live right now with viewers and host stats, read the daily ranking of top live creators and the top gifters of a live room. No login or cookies needed. Export JSON, CSV or Excel.

- **URL**: https://apify.com/clover_folktale/tiktok-live-scraper.md
- **Developed by:** [Silkline](https://apify.com/clover_folktale) (community)
- **Categories:** Social media, Videos
- **Stats:** 1 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.00 / 1,000 live rooms

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

Scrape TikTok LIVE without a login: search live rooms by keyword, check whether creators or rooms are live right now, read the daily ranking of top live creators and see who sits at the top of a live room's gifter ranking. Built for live-commerce research, creator scouting, agency monitoring and alerts when a creator goes live.

### What is TikTok LIVE data?

TikTok LIVE is TikTok's live-streaming section. Every live room shows a title, the host, how many people watch, and a ranking of the viewers who send gifts. This Actor is not affiliated with TikTok; it reads what anyone sees on a live room or in the live rankings and returns it as flat records.

### What data can you get?

| Mode | What it returns |
|---|---|
| `liveSearch` | Live rooms found by keyword: title, viewers now, total viewers, likes, start time, host handle, nickname and follower count, link to the live |
| `liveStatus` | One record per user or room you give: live or offline, and when live the room's title, viewers, start time and host stats. Users are looked up by handle or link, rooms by ID (checked in batches) |
| `liveRanking` | The daily ranking of top live creators, up to 99 rows: rank, creator, followers and the day's score. Today so far or the ranking of yesterday |
| `liveGifters` | The top of a live room's gifter ranking (up to 30 people, often fewer): rank, public user ID, handle, nickname, picture and the coins sent |

Live room records (`type: liveRoom`): `roomId`, `title`, `isLive`, `viewerCount`, `totalViewers`, `likeCount`, `shareCount`, `startedAt`, `coverUrl`, `hostUserId`, `hostHandle`, `hostNickname`, `hostFollowerCount`, `hostFollowingCount`, `liveUrl`, `keyword`.
Status records (`type: liveStatus`): `input`, `status` (`live` or `offline`), `isLive`, `roomId`, `title`, `viewerCount`, `totalViewers`, `startedAt`, `coverUrl`, `hostUserId`, `hostHandle`, `hostNickname`, `hostVerified`, `hostFollowerCount`, `hostFollowingCount`, `hostAvatarUrl`, `liveUrl`. An offline user keeps the host fields and has empty room fields. A room checked by ID has only `status` and `roomId` unless you switch on `includeRoomInfo`.
Ranking rows (`type: liveRankEntry`): `day`, `rank`, `userId`, `handle`, `nickname`, `avatarUrl`, `followerCount`, `score`, `scoreText`.
Gifter rows (`type: liveGifter`): `roomId`, `hostUserId`, `hostHandle`, `rank`, `score`, `userId`, `handle`, `nickname`, `avatarUrl`.

### How to use TikTok Live Scraper

1. Open the Actor and choose a mode.
2. Fill the fields that belong to the mode (keywords, users, room IDs, ranking day); every field is named after its mode in the form.
3. Set the maximum number of results and run.
4. Export the dataset as JSON, CSV or Excel, or read it through the API.

### Input

| Field | Type | Mode | Meaning |
|---|---|---|---|
| `mode` | string | all | One of the four modes. Default `liveSearch` |
| `keywords` | list | liveSearch | Each keyword is a separate search and pays its own start fee |
| `region` | string | liveSearch | Two-letter country code of the search. Default `US` |
| `users` | list | liveStatus, liveGifters | Handles (`@name` or `name`), profile links or live links (`https://www.tiktok.com/@name/live`). Short links are not supported |
| `roomIds` | list | liveStatus, liveGifters | Live room IDs, 15 to 20 digits (the `roomId` of a result) |
| `includeRoomInfo` | boolean | liveStatus | Add title, viewers, likes, start time and host data to every live room given by ID (one more request per live room) |
| `rankDay` | string | liveRanking | `today` (so far) or `yesterday`. Default `today` |
| `maxResults` | integer | all | Per keyword (liveSearch), per room (liveGifters), the number of users and rooms checked (liveStatus), the rows (liveRanking). Up to 1000. Default 20 |

```json
{"mode": "liveSearch", "keywords": ["cat"], "region": "US", "maxResults": 40}
```

```json
{"mode": "liveStatus", "users": ["@anonymomma69", "https://www.tiktok.com/@khaby.lame/live"], "maxResults": 20}
```

### Output example

```json
{"type": "liveRoom", "roomId": "7699295919586167566", "title": "Oh Look A Stray Cat!", "isLive": true, "viewerCount": 6,
 "totalViewers": 1850, "likeCount": 75521, "shareCount": 20, "startedAt": "2026-10-22T01:21:44Z",
 "hostUserId": "6744203391544607750", "hostHandle": "anonymomma69", "hostNickname": "Sweet Like Sugar",
 "hostFollowerCount": 1240, "hostFollowingCount": 279, "liveUrl": "https://www.tiktok.com/@anonymomma69/live", "keyword": "cat"}
```

```json
{"type": "liveRankEntry", "day": "today", "rank": 1, "userId": "6758816569066963973", "handle": "tyler_river",
 "nickname": "Tyler River", "followerCount": 866591, "score": 601257, "scoreText": "601.2K"}
```

### How much does it cost?

You pay per event: a start fee of $0.005 per run, plus per record returned:

| Record | Price |
|---|---|
| Live room (`liveSearch`) or status record (`liveStatus`) | $0.004 |
| Ranking row (`liveRanking`) | $0.002 |
| Gifter row (`liveGifters`) | $0.001 |

- Keyword search pays the start fee again for every further keyword. In `liveGifters` every further room or user pays it again too, because each one needs its own lookups. `liveStatus` and `liveRanking` pay one start fee per run.
- Example: 40 live rooms for one keyword cost $0.005 + 40 x $0.004 = $0.165.
- Example: the status of 50 creators costs $0.005 + 50 x $0.004 = $0.205.
- Example: the full daily ranking (99 rows) costs $0.005 + 99 x $0.002 = $0.203.
- Example: a full gifter ranking of 30 people costs $0.005 + 30 x $0.001 = $0.035; rooms often return fewer.
- A spending limit set on the run is respected: the run stops cleanly when the next record or start fee does not fit.

Free Apify plan: every run returns a sample dataset (a real result of the prefilled input) so you can see the output format; your input is not used and nothing is charged. To run your own queries, use any paid Apify plan.

### Use cases

- Find live rooms about a product, game or topic and see how many people watch.
- Check a list of creators every few minutes and react when they go live (schedule the Actor).
- Scout creators for live commerce and agency work with the daily ranking and their follower counts.
- Watch who gifts the most in the lives of a creator you work with or compete against.

### Integrations and API

Runs can be started through the Apify API, scheduled, and connected to integrations such as webhooks, Zapier or Make.

```python
from apify_client import ApifyClient
client = ApifyClient("<YOUR_APIFY_TOKEN>")
run = client.actor("clover_folktale/tiktok-live-scraper").call(run_input={"mode": "liveStatus", "users": ["@anonymomma69"]})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item["input"], item["status"], item["viewerCount"])
```

### Tips and limits

- Live data is a snapshot of the moment of the run: viewers, likes and the live flag change every minute.
- Search returns 16 to 20 rooms per page and goes on while pages bring rooms you do not have yet. TikTok fills a search with other live rooms when few rooms match, so check the titles.
- A user who is not live is a normal result (`status: offline`). A user who does not exist gives no record; four such users end the run early with a message, so a list full of wrong handles cannot run up costs. Once a run has delivered records, further missing inputs are skipped and the run goes on. A handle the platform rejects counts as a missing user.
- A room given by ID can only be told live or offline. Switch on `includeRoomInfo` to get its title, viewers and host.
- The daily ranking cannot be narrowed by region; it is the list TikTok serves by default. The hourly, weekly and rookie rankings returned nothing in tests and are not offered.
- The gifter ranking is TikTok's list of top viewers of the room: it starts with the people who sent gifts and may continue with viewers whose `score` is 0. A user must be live for `liveGifters`; a room that has ended or is unknown gives no rows.
- Only what the live room shows publicly is returned: handles, nicknames, public IDs, pictures, ranks and scores. No private data.
- Picture addresses are temporary; download what you need soon after the run.
- The first start fee is charged once the platform has answered; an empty answer counts.

### FAQ

**Do I need a TikTok account?** No login or cookies are needed.

**Is it legal?** Only public data is returned. No messages, phone numbers or other private data. You are responsible for how you use it.

**How fresh is the data?** Each run reads the platform at that moment.

**Can I see the chat or watch the stream?** No. The Actor returns room and ranking data, not chat messages or video streams.

**Can I schedule runs and export?** Yes, to JSON, CSV, Excel and more.

### More tools from the same developer

- [TikTok Scraper - Video Search, Hashtags & Author Profiles](https://apify.com/clover_folktale/tiktok-scraper)
- [TikTok Shop Scraper - Products, SKUs, Reviews & Reviewer IDs](https://apify.com/clover_folktale/tiktok-shop-scraper)
- [TikTok Creative Center Scraper - Top Ads, Hashtags & Trends](https://apify.com/clover_folktale/tiktok-creative-center-scraper)
- [Instagram Scraper - Posts, Reels, Profiles & Followers](https://apify.com/clover_folktale/instagram-scraper)
- [YouTube Scraper - Shorts, Channel Videos & Video Search](https://apify.com/clover_folktale/youtube-scraper)

# Actor input Schema

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

What to scrape: live rooms found by keyword, whether given users or rooms are live right now, the daily ranking of top live creators, or the top gifters of a live room.

## `keywords` (type: `array`):

Search keywords; each keyword is a separate search and pays its own start fee. Falls back to "cat" when empty.

## `region` (type: `string`):

Two-letter country code of the search, for example US or GB. Default US.

## `users` (type: `array`):

TikTok handles (@name or name), profile links or live links such as https://www.tiktok.com/@name/live. Short links are not supported. In liveGifters a user must be live; each user pays its own start fee.

## `roomIds` (type: `array`):

Live room IDs (15 to 20 digits, the roomId of a result). liveStatus checks them in batches. In liveGifters each room pays its own start fee.

## `includeRoomInfo` (type: `boolean`):

For every live room given by ID, add title, viewers, likes, start time and host data (one more request per live room).

## `rankDay` (type: `string`):

The ranking of today so far, or the ranking of yesterday.

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

Maximum records for each keyword (liveSearch) or each room (liveGifters), up to 1000; for liveStatus the maximum number of users and rooms checked; for liveRanking the maximum rows (the ranking holds 99). A room ranking holds up to 30 people, often fewer. You are charged per record returned ($0.004 live room or status, $0.002 ranking row, $0.001 gifter row), plus a $0.005 start fee per run. Keyword search and every room in liveGifters pay the start fee again.

## Actor input object example

```json
{
  "mode": "liveSearch",
  "keywords": [
    "cat"
  ],
  "region": "US",
  "includeRoomInfo": false,
  "rankDay": "today",
  "maxResults": 20
}
```

# Actor output Schema

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

All scraped items (JSON, CSV, Excel via the dataset API).

# 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 = {
    "keywords": [
        "cat"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("clover_folktale/tiktok-live-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 = { "keywords": ["cat"] }

# Run the Actor and wait for it to finish
run = client.actor("clover_folktale/tiktok-live-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 '{
  "keywords": [
    "cat"
  ]
}' |
apify call clover_folktale/tiktok-live-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,clover_folktale/tiktok-live-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/jPos7AxdczHlXUXq1/builds/nti40BecGEacsSOGJ/openapi.json