# TikTok Live Status Monitor (`khadinakbar/tiktok-live-status-monitor`) Actor

Check TikTok LIVE status from usernames or profile URLs. Returns isLive, room title, viewer count, and start time. Cookieless public data via ScrapeCreators + SociaVault. For chat/recording/discovery use tiktok-live-scraper. $0.005 per resolved snapshot.

- **URL**: https://apify.com/khadinakbar/tiktok-live-status-monitor.md
- **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community)
- **Categories:** Social media, Automation, MCP servers
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 live status checkeds

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 Live Status Monitor

Turn TikTok usernames or profile URLs into one live-status snapshot per account for brand monitoring, talent scouting, and live-shopping alerts. Each row includes `isLive`, `status`, `roomTitle`, `viewerCount`, `startedAt`, and `liveUrl`. No TikTok login or cookies.

This Actor is a focused **is-live roster checker**. When you need chat capture, recording, or category discovery after a status check, continue with [TikTok Live Scraper](https://apify.com/khadinakbar/tiktok-live-scraper).

TikTok is a trademark of its owner. This independent Actor is not affiliated with, associated with, or endorsed by TikTok.

### Best fit for this Actor

- Poll a known creator roster on an Apify Schedule and keep `isLive` plus offline snapshots.
- Alert when a talent or brand handle starts broadcasting.
- Feed an agent a short handle list and get structured live/offline JSON.

For profile bios or videos, continue with [TikTok Profile Scraper](https://apify.com/khadinakbar/tiktok-profile-scraper) after you have the handles. For comments on published videos (not LIVE rooms), use [TikTok Video Comments Scraper](https://apify.com/khadinakbar/tiktok-video-comments-scraper).

### Practical scenario

A talent scout pastes `tiktok` and `khaby.lame`. The job returns one billed row per public handle: offline accounts still write `isLive: false` so the roster stays complete; an unknown handle finishes as unbilled `VALID_EMPTY` with no dataset row. The scout schedules the same input every 15 minutes and filters `isLive: true` downstream.

### Quick start input

```json
{
  "usernames": ["tiktok"],
  "maxItems": 10,
  "includeOffline": true,
  "includeStreamUrls": false
}
```

`usernames` accepts bare handles, `@handles`, profile URLs, or `/live` URLs. One unique handle produces one dataset row.

### Input reference

| Field | Type | What it controls |
|---|---|---|
| `usernames` | array | Required handles or profile/live URLs. Example: `tiktok`. Max 100 unique via `maxItems`. |
| `maxItems` | integer | Cap on unique accounts processed. Default 20, max 100. |
| `includeOffline` | boolean | Keep offline snapshots so a roster stays complete. Default true. |
| `includeStreamUrls` | boolean | Attach ephemeral HLS/FLV only while `isLive` is true. Default false. |
| `providerOrder` | enum | `scrapecreators-first` (default), `sociavault-first`, or vendor-only pins. |

### What data you receive

One dataset item is one public TikTok account snapshot.

```json
{
  "username": "tiktok",
  "profileUrl": "https://www.tiktok.com/@tiktok",
  "isLive": false,
  "status": "offline",
  "outcome": "OK",
  "provider": "scrapecreators",
  "checkedAt": "2026-09-15T19:39:18.597Z",
  "liveUrl": "https://www.tiktok.com/@tiktok/live",
  "nickname": "TikTok",
  "verified": true,
  "followerCount": 95754368,
  "roomTitle": "Example leftover room title",
  "viewerCount": 0
}
```

| Field | Meaning |
|---|---|
| `isLive` | `true` only when the provider reports the account is broadcasting now |
| `status` | `live` or `offline` for billed rows |
| `roomTitle` | Current title when live; may still appear after a room ends |
| `viewerCount` | Live viewers when broadcasting; `0` when offline |
| `provider` | `scrapecreators` or `sociavault` |
| `checkedAt` | ISO timestamp of this snapshot |

Offline rooms can still expose a leftover `roomTitle`. Treat `isLive` as the source of truth. Stream URLs expire quickly and appear only when you opt in **and** the account is live.

`OUTPUT` and `RUN_SUMMARY` in the default key-value store hold `outcome`, `itemsPushed`, and `chargedEventCounts`.

### Honest live vs leftover-room rule

TikTok payloads often keep `title`, `startTime`, and even signed stream URLs after the broadcast ends. This Actor uses the provider `is_live` flag. A leftover-title room with `isLive: false` is billed as an honest **offline** snapshot.

### Pricing

Pay per event plus Apify platform usage. The live **Pricing** tab is the current source of truth for event names and dollar amounts.

| Event | When it charges | Typical price |
|---|---|---|
| `apify-actor-start` | Once per job | $0.00005 |
| `live-status-checked` | Each persisted live **or** offline snapshot | $0.005 |

Worked example: checking 10 public handles with `includeOffline: true` charges about `10 × $0.005` for snapshots plus the start fee, plus platform usage on the Pricing tab. Unknown handles finish as unbilled `VALID_EMPTY`.

### Use through the API

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('khadinakbar/tiktok-live-status-monitor').call({
  usernames: ['tiktok', 'khaby.lame'],
  maxItems: 10,
  includeOffline: true,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

### Agent / MCP prompt

> Call apify--tiktok-live-status-monitor with usernames \["tiktok","khaby.lame"], includeOffline true, maxItems 10. Read the dataset for isLive/status/roomTitle, then read OUTPUT for outcome and chargedEventCounts. Cost is one live-status-checked event per billed snapshot plus platform usage. Scope is public is-live status only; route chat or recording needs to khadinakbar/tiktok-live-scraper.

### Scheduling a roster

Save the Actor as a Task with your handle list, then attach an Apify Schedule (for example every 15 minutes). Each job is one snapshot batch. Filter `isLive === true` in your downstream webhook or dataset export.

### Best results

- Prefer known public handles over guesswork; unknown accounts stay unbilled.
- Keep `includeOffline: true` for roster completeness; set it false when you only want currently live rows.
- Leave `includeStreamUrls` false unless you will consume the URLs immediately.
- Cap `maxItems` to the roster size you can afford at $0.005 per snapshot.

### Builder's note

I found that provider payloads for ended rooms still ship leftover titles and signed stream URLs. Inferring live from those fields created false positives during the first probe, so the runtime trusts `is_live` only and attaches stream URLs solely when that flag is true. SociaVault’s TikTok live route expects `handle=` (not `username=`), which matters when pinning `sociavault-only`.

### Outcome contract

| Outcome | Meaning | Dataset | Named charge |
|---|---|---|---|
| `COMPLETE` | Every unique handle resolved live or offline | Yes | Yes, one per snapshot |
| `PARTIAL` | Mix of snapshots and upstream issues | Snapshots only | Snapshots only |
| `VALID_EMPTY` | All handles missing or all offline when `includeOffline` is false | No billable rows | No |
| `INVALID_INPUT` | Empty or unusable handle list | No | No |
| `UPSTREAM_FAILED` | Both providers unavailable for every handle | No | No |
| `CONFIG_ERROR` | Required provider keys missing | No | No |

### Responsible use

Use this Actor on public TikTok LIVE pages and profiles you are authorized to monitor. Respect applicable law and TikTok’s terms. Prefer consented brand, talent, and commerce monitoring workflows.

### Related Actors

- [TikTok Live Scraper](https://apify.com/khadinakbar/tiktok-live-scraper) — when you need room details, chat, or currently-live discovery after a status check
- [TikTok Profile Scraper](https://apify.com/khadinakbar/tiktok-profile-scraper) — when you need bios and public profile fields for the same handles
- [TikTok Video Comments Scraper](https://apify.com/khadinakbar/tiktok-video-comments-scraper) — when you need comments on published VOD, not LIVE rooms

# Changelog

This Actor's version history is a separate document: https://apify.com/khadinakbar/tiktok-live-status-monitor/changelog.md

# Actor input Schema

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

TikTok usernames, @handles, profile URLs, or /live URLs to check. Example: tiktok or https://www.tiktok.com/@khaby.lame. Duplicates are removed. Max 100 unique handles via maxItems. This is not a video URL and not a currently-live discovery search.

## `maxItems` (type: `integer`):

Hard cap on unique usernames processed in one run. Example: 10. Default 20, minimum 1, maximum 100. Extra handles after the cap are skipped.

## `includeOffline` (type: `boolean`):

When true (default), every resolved public account is written, including isLive false. Example: true for a roster monitor. Turn off to keep only currently live rows. Offline skips are not billed.

## `includeStreamUrls` (type: `boolean`):

When true, live rows may include ephemeral FLV/HLS/CMAF playback URLs. Example: false. Default false because signed URLs expire quickly. This is not a recorder and does not save MP4 files.

## `providerOrder` (type: `string`):

Which public-data provider to try first. scrapecreators-first is the default. sociavault-first swaps the fallback. \*-only pins one vendor. This is not a TikTok login or cookie field.

## Actor input object example

```json
{
  "usernames": [
    "tiktok",
    "@khaby.lame"
  ],
  "maxItems": 10,
  "includeOffline": true,
  "includeStreamUrls": false,
  "providerOrder": "scrapecreators-first"
}
```

# Actor output Schema

## `datasetItems` (type: `string`):

No description

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

No description

## `outputRecord` (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 = {
    "usernames": [
        "tiktok"
    ]
};

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

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

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,khadinakbar/tiktok-live-status-monitor"
        }
    }
}
```

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/llIdfdZvVbcH1vWPq/builds/anXX1SN42ZcEMpnDd/openapi.json