# Twitch Scraper — Channels, Streams, VODs, Clips, Games & Search (`brilliant_gum/twitch-scraper`) Actor

HTTP-only, no-login Twitch scraper via public GraphQL. Channel profiles, live streams, VODs, clips, top games, search, VOD chapters & chat replay, schedule. Adds analytics, bio lead enrichment, HLS URLs & monitoring.

- **URL**: https://apify.com/brilliant\_gum/twitch-scraper.md
- **Developed by:** [Yuliia Kulakova](https://apify.com/brilliant_gum) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.004 / result record

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

## Twitch Scraper — Channels, Streams, VODs, Clips, Games & Search

HTTP-only, **no login, no cookies, no browser**. Reads Twitch's public data, so every field below is
public. One actor, ten modes, plus analytics, lead enrichment, HLS URLs and monitoring.

![Twitch Scraper](https://api.apify.com/v2/key-value-stores/IuFu0Cw6PpOkNkDV7/records/twitch-scraper-banner.png)

> **Enjoying this Actor?** If it's useful, please leave a ⭐️ rating and a short review — it genuinely helps. **Something not working right?** Open an issue on the Actor's **Issues** tab — I actively maintain this Actor and respond fast to fix problems and help you get things working.

### Modes

| Mode | What you get |
|------|--------------|
| **channel** | Full profile: id, login, display name, bio, avatar/banner, created date, partner/affiliate/staff, follower count, current live stream, last broadcast, panels, social links. Optional: recent videos, top clips, schedule, **analytics**. |
| **live-streams** | Currently-live streams — all of Twitch, or one category via `gameName`. Title, category, viewers, uptime, tags, language, thumbnail, broadcaster. |
| **top-games** | Most-watched games/categories right now: viewers, box art, tags. |
| **videos** | Recent VODs per channel: title, duration, views, date, type, game, thumbnail. |
| **clips** | Top clips per channel over a period: title, views, duration, creator, game, URL, plus direct-download **`mp4Urls`** (1080/720/480/360). |
| **search** | Channels + games/categories by keyword. |
| **vod-details** | One VOD's metadata **+ chapters** (game/segment markers). |
| **vod-comments** | VOD **chat replay** — every message with timestamp, offset and commenter. |
| **schedule** | A channel's upcoming stream schedule segments. |
| **url** | Paste any mix of twitch.tv links (channels, `/videos/ID`, clips, category pages) — auto-routed. |

### Beyond the competition

- **Channel analytics** (no other Twitch actor has this): average stream duration, streams-per-week,
  average VOD views, days since last broadcast, most-played games, current viewers — derived from the
  channel's recent VODs. Turn on `includeAnalytics`.
- **Lead enrichment**: emails, links and social handles (Instagram, X/Twitter, TikTok, YouTube,
  Facebook, Discord, Telegram) mined from the bio and the channel's declared socials into a `leads`
  object. Great for influencer-marketing outreach.
- **Monitoring / growth tracking**: `monitorMode` stores state across runs. Channel records gain a
  `growth` object (follower delta and per-day rate vs the previous run); stream/video/clip/comment
  records are emitted only when new. Schedule it to build a growth time-series.
- **Direct media URLs** (`includeMediaUrls`, on by default): clip records get `mp4Urls` — ready-to-
  download `.mp4` links keyed by quality (1080/720/480/360) plus `mp4Qualities` (with `frameRate`),
  straight from Twitch's public clip data, no login. Live streams and VODs get a playable HLS `.m3u8`
  manifest. Turn it off to skip the extra playback-token call for live/VOD modes.
- **Chapters & chat replay**: full VOD game-markers and chat-replay comments, no login.
- **Dedup, compact/flatten output**, and clean CSV/Excel export.

### Input (essentials)

```json
{
  "mode": "channel",
  "channels": ["shroud", "pokimane"],
  "includeVideos": true,
  "includeClips": true,
  "includeAnalytics": true,
  "maxItems": 20,
  "proxyConfiguration": { "useApifyProxy": true }
}
```

`channels` accepts bare logins, `@handle`, profile URLs or numeric user IDs.

### Proxy

Proxies are **included and configured automatically** — just leave the default in place; it is enough
and cheap for the bulk data, and the actor transparently handles the one field that needs special
routing, so a channel's **declared social links** come back too. Only switch proxies if you ever hit
rate limits.

### Pricing

This Actor uses Apify's **pay-per-event** model: a small **start fee per run** plus a **per-record
charge** for every result written to the dataset (channel, stream, video, clip, game, VOD, comment or
schedule row) — on top of your own Apify platform usage. No monthly minimums. The exact start fee and
per-record rate are shown on the Actor's **Pricing** tab in the Apify Store. Use `maxItems`,
`maxPerChannel` and `maxComments` to cap spend.

### Notes & honest limits

- **Follower/following *lists* are not public** on Twitch (removed in 2022) — only the **follower
  count** is available, and this actor returns it. No no-login tool can list individual followers.
- **Lifetime channel "total views"** was removed by Twitch in 2022 and is no longer exposed by any
  API; use VOD view counts / analytics instead.
- **Media URLs are time-limited.** `mp4Urls` (clips) and the HLS `.m3u8` (live/VOD) are freshly signed
  with Twitch's no-login token, which expires after a few hours — download/fetch them soon after the run.
- This actor reads only public data and sends no credentials. Respect Twitch's Terms of Service and
  applicable laws when using the output.

# Actor input Schema

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

What to scrape. 'channel' = full profile (+ optional live/videos/clips/schedule/analytics). 'live-streams' = live streams (all, or in a category via 'Game / category'). 'top-games' = most-watched categories. 'videos' = VODs per channel. 'clips' = top clips per channel. 'search' = channels + games by keyword. 'vod-details' = one VOD + chapters. 'vod-comments' = VOD chat replay. 'schedule' = upcoming stream schedule. 'url' = paste any twitch.tv links.

## `channels` (type: `array`):

Twitch channels for 'channel', 'videos', 'clips' and 'schedule' modes. Accepts bare logins ('shroud'), '@handle', profile URLs ('https://twitch.tv/pokimane') or numeric user IDs (auto-resolved to logins).

## `searchQuery` (type: `string`):

Keyword for 'search' mode — matched against channels and games/categories.

## `searchType` (type: `string`):

For 'search' mode: which result types to return.

## `gameName` (type: `string`):

For 'live-streams' mode: exact game/category name (e.g. 'Just Chatting', 'League of Legends') to list only live streams in that category. Leave empty to get the top live streams overall.

## `videoIds` (type: `array`):

Numeric VOD IDs or full '/videos/ID' URLs for 'vod-details' and 'vod-comments' modes.

## `urls` (type: `array`):

For 'url' mode: paste any mix of twitch.tv links — channel pages, '/videos/ID', clip links, and '/directory/category/' pages. Each is routed to the right handler automatically.

## `videoType` (type: `string`):

For 'videos' mode: filter VODs by type. 'ALL' returns every type.

## `videoSort` (type: `string`):

For 'videos' mode: ordering of returned VODs.

## `clipPeriod` (type: `string`):

For 'clips' mode (and channel 'Include top clips'): time window for top clips.

## `clipSort` (type: `string`):

For 'clips' mode: ordering of clips within the selected period.

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

Global cap on records written to the dataset in this run, across all targets and pages.

## `maxPerChannel` (type: `integer`):

For 'videos' / 'clips' (and channel 'Include' toggles): cap on items fetched per channel. The global 'Max items' still applies.

## `maxComments` (type: `integer`):

For 'vod-comments' mode: cap on chat-replay messages fetched per VOD.

## `includeVideos` (type: `boolean`):

For 'channel' mode: attach the channel's recent VODs (up to 'Max per channel') as 'recentVideos'.

## `includeClips` (type: `boolean`):

For 'channel' mode: attach the channel's top clips (period from 'Clip period') as 'topClips'.

## `includeSchedule` (type: `boolean`):

For 'channel' mode: attach the channel's upcoming stream schedule as 'schedule'.

## `includeAnalytics` (type: `boolean`):

For 'channel' mode: compute analytics from recent VODs — average stream duration, streams/week, average VOD views, days since last broadcast, top games and current viewers. Adds an 'analytics' object.

## `includeMediaUrls` (type: `boolean`):

Attach direct media URLs. For clips: 'mp4Urls' with ready-to-download .mp4 links per quality (1080/720/480/360) plus 'mp4Qualities' (quality, frameRate, sourceURL). For live streams (channel mode) and VODs (vod-details mode): an HLS '.m3u8' manifest URL. All from Twitch's public no-login data; best-effort. On by default.

## `includeChapters` (type: `boolean`):

For 'vod-details' mode: include the VOD's chapter/game markers ('chapters').

## `enrichLeads` (type: `boolean`):

For 'channel' mode: extract emails, links and social handles (Instagram, Twitter/X, TikTok, YouTube, Facebook, Discord, Telegram) from the bio and declared socials into a 'leads' object.

## `dedup` (type: `boolean`):

Drop duplicate records (same type + id) within a run.

## `monitorMode` (type: `boolean`):

Track state across runs (in a named key-value store). Channel records gain a 'growth' object (follower delta & per-day rate vs the previous run); stream/video/clip/comment records are emitted only when new since the previous run.

## `stateKey` (type: `string`):

Optional label to keep a monitoring campaign's state separate (or shared). Used only when 'Monitor mode' is on.

## `outputPreset` (type: `string`):

Record shape: 'full' (all fields) or 'compact' (the most useful ~20 fields).

## `flattenOutput` (type: `boolean`):

Dot-flatten nested objects (leads.socials.instagram, analytics.streamsPerWeek, …) for clean CSV/Excel export.

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

Proxies are included and configured automatically — leave the default in place. Only switch proxies if you hit rate limits.

## Actor input object example

```json
{
  "mode": "channel",
  "channels": [
    "shroud",
    "pokimane"
  ],
  "searchType": "all",
  "videoIds": [],
  "urls": [],
  "videoType": "ARCHIVE",
  "videoSort": "TIME",
  "clipPeriod": "LAST_WEEK",
  "clipSort": "VIEWS_DESC",
  "maxItems": 20,
  "maxPerChannel": 10,
  "maxComments": 500,
  "includeVideos": false,
  "includeClips": false,
  "includeSchedule": false,
  "includeAnalytics": false,
  "includeMediaUrls": true,
  "includeChapters": true,
  "enrichLeads": true,
  "dedup": true,
  "monitorMode": false,
  "outputPreset": "full",
  "flattenOutput": false,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

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

All Twitch records produced by the run.

# 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 = {
    "channels": [
        "shroud",
        "pokimane"
    ],
    "maxItems": 20,
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("brilliant_gum/twitch-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 = {
    "channels": [
        "shroud",
        "pokimane",
    ],
    "maxItems": 20,
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("brilliant_gum/twitch-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 '{
  "channels": [
    "shroud",
    "pokimane"
  ],
  "maxItems": 20,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call brilliant_gum/twitch-scraper --silent --output-dataset

```

## MCP server setup

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