# TikTok Public LIVE Room Metadata (`w3crawler/tiktok-live-scraper`) Actor

Resolve public TikTok LIVE room metadata for usernames or LIVE URLs using the public connector and page state; this implementation does not subscribe to event streams.

- **URL**: https://apify.com/w3crawler/tiktok-live-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 live rooms

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 LIVE Room Metadata

Resolve public TikTok LIVE room metadata for usernames or canonical LIVE URLs. The Actor first tries `tiktok-live-connector` room information and then falls back to the public LIVE page and its embedded state when needed.

This implementation is metadata-only. It does **not** subscribe to a LIVE event stream and does not collect chat messages, gifts, likes, follows, joins, shares, or real-time stats.

### Example input

```json
{
  "usernames": ["officialgeilegisela"],
  "maxUsers": 1,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

You can provide usernames, canonical URLs such as `https://www.tiktok.com/@creator/live`, or both. Duplicate broadcasters are removed.

### Example output

```json
{
  "recordType": "tiktok-live-room-info",
  "status": "success",
  "dataAvailable": true,
  "source": "tiktok.com",
  "provenance": "public_tiktok_live_room",
  "sourceTransport": "tiktok-live-connector",
  "extractionMethod": "connector_room_info",
  "sourceUrl": "https://www.tiktok.com/@creator/live",
  "hostUsername": "creator",
  "roomId": "1234567890",
  "liveTitle": "Public LIVE title",
  "liveStatus": 2,
  "currentViewers": 1200,
  "eventStreamAvailable": false,
  "eventStreamStatus": "room-info-route",
  "scrapedAt": "2026-08-18T00:00:00.000Z"
}
```

If the broadcaster is offline, the page is blocked, or no room state is public, the dataset receives a diagnostic record. The `OUTPUT` summary reports success, partial, or failed status.

### Input

- `usernames` (array): Public TikTok usernames without `@`.
- `liveUrls` (array): Public HTTPS TikTok LIVE URLs.
- `maxUsers` (integer, 1–5): Maximum unique broadcasters to process. Default: `5`.
- `proxyConfiguration` (object, optional): Apify Proxy configuration for public page fallback requests. The connector room-info request uses its own HTTP client.

At least one of `usernames` or `liveUrls` is required.

### Output and storage

Room metadata and diagnostics are written to the default dataset. The Output tab links to the dataset and to `OUTPUT` in the default key-value store.

`OUTPUT` contains requested and processed broadcaster counts, metadata count, diagnostic count, failed usernames, and the explicit event-stream limitation.

### Limitations and cost

Room availability is time-dependent: an offline broadcaster may produce an access diagnostic even when the username is valid. Public page state and connector behavior can change as TikTok updates its web client. The Actor does not maintain a persistent socket or collect events after room metadata is resolved.

Connector requests, public HTTP fallback requests, Apify compute, and optional proxy traffic contribute to cost. Keep `maxUsers` small while testing and retry responsibly.

### FAQ and disclaimer

#### Does this Actor collect LIVE chat or gifts?

No. It only resolves public room metadata and sets `eventStreamAvailable` to `false`.

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

The broadcaster may not be live, or TikTok may have returned a page without public room state. Review `accessStatus`, `httpStatus`, and the bounded body sample.

#### Does it use private account cookies or bypass blocks?

No. It does not log in, defeat CAPTCHAs, or bypass private-account controls.

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

# Actor input Schema

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

Public TikTok usernames without the @ symbol.

## `liveUrls` (type: `array`):

Canonical public HTTPS TikTok LIVE URLs.

## `maxUsers` (type: `integer`):

Maximum unique broadcasters to process from the supplied usernames and LIVE URLs.

## `proxyConfiguration` (type: `object`):

Optional Apify Proxy configuration for public page fallback requests. The connector room-info request uses its own HTTP client.

## Actor input object example

```json
{
  "usernames": [
    "officialgeilegisela"
  ],
  "maxUsers": 5,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

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

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

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

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,w3crawler/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/Hy4jLKKLkXpS9odhj/builds/0OjDR2uAkSfsHS3hF/openapi.json