# Twitch Live Stream, Channel & VOD Metadata Extractor (`vexaloom-labs/twitch-live-stream-channel-and-vod-metadata`) Actor

Get Twitch top live streams, channel profiles, category directories, VOD metadata and clip details, or resolve any twitch.tv URL into structured data.

- **URL**: https://apify.com/vexaloom-labs/twitch-live-stream-channel-and-vod-metadata.md
- **Developed by:** [vexaloom-labs](https://apify.com/vexaloom-labs) (community)
- **Categories:** Social media, Videos, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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 Live Stream, Channel & VOD Metadata Extractor

Collect **Twitch** metadata without a login, OAuth app, or API key: live streams, channel profiles with social links and published schedules, category directories, category VODs, individual VODs and clips, search results, and resolved twitch.tv links. Every record is public data returned in clean JSON, with empty fields omitted.

### What this actor does

- Returns the live directory globally or inside one category, with viewer counts, language, start time, tags, broadcaster followers, partner status, and stream quality details
- Builds channel profiles with bio, images, follower count, roles, social links, About panels, primary team, upcoming schedule, total VOD count, and emails published in the bio
- Pages channel VODs and clips deeply, with VOD type/sort and clip period/sort controls
- Searches Twitch channels, categories, and videos with independent deep pagination for each index
- Adds category VODs, batch channel/VOD/clip lookup, multi-URL resolution, and category stats on stream records
- Omits empty values at every depth instead of returning `null`, empty strings, or empty objects

### Modes

| Mode | What you get |
|---|---|
| `topStreams` | Current live streams across Twitch, with language, tag, viewer, and sort filters |
| `topGames` | Categories sorted by current viewers, with follower and broadcaster counts |
| `search` | Channels, categories, and videos from Twitch search, with per-index pagination |
| `byChannel` | One or more channel profiles, plus optional recent VODs and clips |
| `byCategory` | Live streams in a category, with category viewer/follower/broadcaster stats attached |
| `byCategoryVideos` | VODs for a category, filtered by type, language, and sort order |
| `topClips` | Top clips for a category over a chosen time window, sorted by views or trending |
| `byVideo` | One or many VODs by numeric ID or VOD URL |
| `byClip` | One or many clips by slug or clip URL |
| `byUrl` | Resolves channel, VOD, clip, and category URLs, including `/videos` and `/clips` tabs |

### Output per record

Every record carries a `recordType` of `stream`, `channel`, `video`, `clip`, or `game`, plus `scrapedAt`. Invalid URLs produce a typed `error` row, which does not count toward `maxItems`.

#### Live stream (`recordType: "stream"`)

| Field | Description |
|---|---|
| `streamId` | Twitch stream ID |
| `title` | Stream title |
| `viewersCount` | Current concurrent viewers |
| `streamType` | Broadcast type |
| `language` | Broadcast language code |
| `startedAt` | Stream start timestamp |
| `previewImageURL` | Live preview thumbnail |
| `channelId` / `channelName` / `displayName` | Broadcaster identifiers |
| `followersCount` | Broadcaster follower count |
| `isPartner` / `isAffiliate` | Broadcaster role flags, when true |
| `gameId` / `gameName` / `gameSlug` | Category identifiers |
| `tags` | Freeform stream tags |
| `isMature` | Mature-content flag |
| `averageFPS` / `height` / `width` | Stream quality details |
| `contentClassificationLabels` | Twitch content labels, when present |
| `broadcaster` | Broadcaster object with images, color, followers, roles, social links |
| `game` | Category object with artwork and category stats when available |
| `url` | Channel URL |

#### Channel (`recordType: "channel"`)

| Field | Description |
|---|---|
| `channelId` / `channelName` / `displayName` | Channel identifiers |
| `description` | Public channel bio |
| `language` | Channel broadcast language |
| `createdAt` | Account creation date |
| `profileImageURL` / `bannerImageURL` / `offlineImageURL` | Channel images |
| `primaryColorHex` | Brand color |
| `isPartner` / `isAffiliate` / `isStaff` | Role flags, when true |
| `followersCount` | Total followers |
| `streamTitle` / `currentGame` | Configured stream title and category |
| `isLive` | Whether the channel is live |
| `liveStream` | Nested live-stream details when live |
| `lastBroadcast` | Most recent broadcast details |
| `socialLinks[]` | Social links shown on the channel page |
| `panels[]` | About-page panels with title, text, image, and link |
| `primaryTeam` | Primary Twitch team, when set |
| `upcomingSchedule[]` | Published upcoming schedule segments |
| `videosCount` | Total current VODs on the channel |
| `contactEmails[]` | Emails published in the public bio |
| `url` | Channel URL |

#### VOD (`recordType: "video"`)

| Field | Description |
|---|---|
| `videoId` | VOD ID |
| `title` / `description` | Title and description when published |
| `lengthSeconds` | Duration in seconds |
| `viewCount` | Total views |
| `createdAt` / `publishedAt` / `updatedAt` / `recordedAt` | Relevant timestamps |
| `previewImageURL` / `animatedPreviewURL` | Thumbnails |
| `broadcastType` / `status` | VOD type and recording status |
| `language` | Video language |
| `contentTags[]` | Twitch content tags |
| `gameId` / `gameName` / `gameSlug` / `game` | Associated category |
| `channelId` / `channelName` / `displayName` / `owner` | Owning channel |
| `url` | VOD URL |

#### Clip (`recordType: "clip"`)

| Field | Description |
|---|---|
| `clipId` / `slug` | Clip identifiers |
| `title` | Clip title |
| `viewCount` | Total views |
| `durationSeconds` | Clip length |
| `createdAt` | Creation timestamp |
| `language` | Clip language |
| `isFeatured` | Featured flag, when true |
| `thumbnailURL` / `embedURL` | Thumbnail and embed URL |
| `videoOffsetSeconds` | Offset into the source broadcast, when known |
| `gameId` / `gameName` / `gameSlug` / `game` | Associated category |
| `channelId` / `channelName` / `displayName` / `broadcaster` | Broadcaster details |
| `curator` | Who created the clip |
| `sourceVideo` | Source VOD ID and title, when linked |
| `url` | Clip URL |

#### Category (`recordType: "game"`)

| Field | Description |
|---|---|
| `gameId` | Category ID |
| `name` / `displayName` / `slug` | Category names and URL slug |
| `viewersCount` / `followersCount` / `broadcastersCount` | Current category stats |
| `boxArtURL` / `logoURL` / `coverURL` | Category artwork |
| `description` | Category description |
| `tags[]` | Category content tags |
| `originalReleaseDate` | Release date when published |
| `developers[]` / `publishers[]` | Companies when published |
| `url` | Category directory URL |

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | string | `topStreams` | One of the ten modes above |
| `searchQuery` | string | `lirik` | Search term for `search` |
| `searchType` | string | `all` | `all`, `channel`, `game`, or `video` |
| `channelName` | string | – | One channel login or URL for `byChannel` |
| `channelNames` | array | `[]` | Batch channel logins or URLs |
| `categorySlug` | string | – | Category slug, name, or directory URL |
| `videoId` | string | – | One VOD ID or URL |
| `videoIds` | array | `[]` | Batch VOD IDs or URLs |
| `clipSlug` | string | – | One clip slug or URL |
| `clipSlugs` | array | `[]` | Batch clip slugs or URLs |
| `twitchUrls` | array | `[]` | URLs for `byUrl` |
| `language` | string | `EN` | Broadcast language, or `(any)` |
| `streamSort` | string | `VIEWER_COUNT` | Most viewers, fewest viewers, recently started, or recommended |
| `streamTags` | array | `[]` | Require all listed freeform tags |
| `streamType` | string | – | VOD type filter |
| `videoSort` | string | `TIME` | Newest or most viewed |
| `clipPeriod` | string | `LAST_WEEK` | Last day, week, month, or all time |
| `clipSort` | string | `VIEWS_DESC` | Most viewed or trending |
| `includeChannelClips` | boolean | `true` | Include clips in `byChannel` |
| `includeChannelVideos` | boolean | `true` | Include VODs in `byChannel` |
| `minViewersCount` | integer | – | Drop streams below this viewer count |
| `minViewCount` | integer | – | Drop VODs and clips below this view count |
| `minFollowersCount` | integer | – | Drop channels and streams below this follower count |
| `maxFollowersCount` | integer | – | Drop channels and streams above this follower count |
| `onlyLive` | boolean | `false` | Drop offline channel profiles |
| `containsKeyword` | string | – | Title keyword filter |
| `maxItems` | integer | `50` | Hard record cap (1–5000) |

#### Example: top live streams in English

```json
{
  "mode": "topStreams",
  "language": "EN",
  "streamSort": "VIEWER_COUNT",
  "maxItems": 50
}
```

#### Example: channel profiles with schedules and media

```json
{
  "mode": "byChannel",
  "channelNames": ["lirik", "xqc", "pokimane"],
  "includeChannelVideos": true,
  "includeChannelClips": true,
  "maxItems": 60
}
```

#### Example: category VODs

```json
{
  "mode": "byCategoryVideos",
  "categorySlug": "minecraft",
  "streamType": "ARCHIVE",
  "videoSort": "VIEWS",
  "maxItems": 100
}
```

#### Example: mixed URL resolution

```json
{
  "mode": "byUrl",
  "twitchUrls": [
    "https://www.twitch.tv/shroud",
    "https://www.twitch.tv/videos/2766365638",
    "https://www.twitch.tv/directory/category/just-chatting/videos"
  ],
  "maxItems": 40
}
```

### Use cases

- **Creator discovery** — find channels by category, language, tags, follower range, or viewer count
- **Sponsorship research** — compare live audiences and follower totals across streamers
- **Clip curation** — pull top or trending clips for a category or channel over a chosen window
- **VOD archives** — collect titles, durations, views, and categories for past broadcasts
- **Market monitoring** — track category viewers, broadcaster counts, and changing top streams
- **Link enrichment** — turn lists of Twitch links into structured channel, VOD, clip, or category rows

### FAQ

**Do I need a Twitch account, OAuth token, or API key?**
No. All modes work without a login or developer credentials.

**Why does a run stop before `maxItems`?**
Twitch sometimes has fewer matching rows than requested. Clip lists stop at about 1,000 rows, search categories at about 30 matches, search channels at about 1,000 per term, and search videos at Twitch's 10,000-match ceiling. In `byUrl`, the cap is shared across the supplied URLs, so a small `maxItems` can stop before every URL is expanded. The actor reports when the source ends or a cap is reached instead of padding the dataset.

**Why are some channel fields missing?**
Social links, schedules, panels, teams, and bio emails are optional on Twitch. They are included when the channel publishes them and omitted otherwise.

**How many live streams can one run return?**
The live directory pages in groups of up to 30. Requesting thousands of rows means many pages and a longer run; the prefill stays small to keep daily tests cheap.

**Can this pull chat messages or video files?**
No. This actor covers stream, channel, VOD, clip, and category metadata only. Chat replays and media downloads are separate tasks.

**What is the difference between `byCategory` and `byCategoryVideos`?**
`byCategory` returns channels that are live in the category now. `byCategoryVideos` returns published VODs for that category.

**How do I find a category slug?**
Open the category on Twitch and copy the last part of its URL, or use `topGames` and read `slug`.

**Are duplicate records removed?**
Yes. Streams, channels, VODs, clips, and categories are deduplicated by their Twitch IDs across pages and batches.

**Is this affiliated with Twitch?**
No. This actor reads public Twitch data and is not affiliated with, endorsed by, or sponsored by Twitch.

# Actor input Schema

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

What to fetch.

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

Free-text query for `mode=search` — matches channels, categories, and videos.

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

Restrict search results to one index. `all` returns channels, categories, and videos.

## `channelName` (type: `string`):

Twitch channel login or channel URL, e.g. `lirik` or `https://www.twitch.tv/lirik`.

## `channelNames` (type: `array`):

Batch channel logins or channel URLs. Duplicates and the single `channelName` are merged.

## `categorySlug` (type: `string`):

Category slug (`just-chatting`), exact name (`Just Chatting`), or directory URL.

## `videoId` (type: `string`):

Twitch VOD ID or VOD URL, e.g. `2766365638`.

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

Batch VOD IDs or VOD URLs. Duplicates and the single `videoId` are merged.

## `clipSlug` (type: `string`):

Twitch clip slug or clip URL, e.g. `AcceptablePleasantAuberginePanicVis-EVdxDQ1vsQAQZpBS`.

## `clipSlugs` (type: `array`):

Batch clip slugs or clip URLs. Duplicates and the single `clipSlug` are merged.

## `twitchUrls` (type: `array`):

Channel, VOD, clip, or category URLs. Category and channel `/videos` and `/clips` tabs are supported.

## `language` (type: `string`):

Filter live streams, VODs, and clips to one broadcast language. Leave on `(any)` for no filter.

## `streamSort` (type: `string`):

Sort live streams by viewers (high to low or low to high), recently started, or recommended.

## `streamTags` (type: `array`):

Only live streams carrying all of these freeform tags, e.g. `English`, `DropsEnabled`, `NoBackseating`.

## `streamType` (type: `string`):

Restrict channel or category VODs to one broadcast type. Leave blank for all types.

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

Sort channel or category VODs by publish time or view count.

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

Time window over which clips were created.

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

Sort clips by views or trending score.

## `includeChannelClips` (type: `boolean`):

Also fetch and emit top clips for each channel.

## `includeChannelVideos` (type: `boolean`):

Also fetch and emit recent VODs for each channel.

## `minViewersCount` (type: `integer`):

Drop live streams (and categories) below this viewer count.

## `minViewCount` (type: `integer`):

Drop VODs and clips below this total view count.

## `minFollowersCount` (type: `integer`):

Drop channels and live streams below this follower count. VODs and clips are unaffected.

## `maxFollowersCount` (type: `integer`):

Drop channels and live streams above this follower count. Useful for finding smaller creators.

## `onlyLive` (type: `boolean`):

Drop channel profile records for channels that are not live right now. Their VODs and clips are still returned.

## `containsKeyword` (type: `string`):

Case-insensitive substring filter on stream, VOD, and clip titles.

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

Hard cap on emitted records. Twitch source caps still apply (e.g. about 1,000 clips per category).

## Actor input object example

```json
{
  "mode": "topStreams",
  "searchQuery": "lirik",
  "searchType": "all",
  "channelNames": [],
  "videoIds": [],
  "clipSlugs": [],
  "twitchUrls": [],
  "language": "EN",
  "streamSort": "VIEWER_COUNT",
  "streamTags": [],
  "streamType": "",
  "videoSort": "TIME",
  "clipPeriod": "LAST_WEEK",
  "clipSort": "VIEWS_DESC",
  "includeChannelClips": true,
  "includeChannelVideos": true,
  "onlyLive": false,
  "maxItems": 3
}
```

# Actor output Schema

## `records` (type: `string`):

Dataset containing all scraped Twitch records (streams, channels, videos, clips, games).

# 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 = {
    "mode": "topStreams",
    "searchQuery": "lirik",
    "searchType": "all",
    "channelNames": [],
    "videoIds": [],
    "clipSlugs": [],
    "twitchUrls": [],
    "language": "EN",
    "streamSort": "VIEWER_COUNT",
    "streamTags": [],
    "streamType": "",
    "videoSort": "TIME",
    "clipPeriod": "LAST_WEEK",
    "clipSort": "VIEWS_DESC",
    "includeChannelClips": true,
    "includeChannelVideos": true,
    "onlyLive": false,
    "maxItems": 3
};

// Run the Actor and wait for it to finish
const run = await client.actor("vexaloom-labs/twitch-live-stream-channel-and-vod-metadata").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 = {
    "mode": "topStreams",
    "searchQuery": "lirik",
    "searchType": "all",
    "channelNames": [],
    "videoIds": [],
    "clipSlugs": [],
    "twitchUrls": [],
    "language": "EN",
    "streamSort": "VIEWER_COUNT",
    "streamTags": [],
    "streamType": "",
    "videoSort": "TIME",
    "clipPeriod": "LAST_WEEK",
    "clipSort": "VIEWS_DESC",
    "includeChannelClips": True,
    "includeChannelVideos": True,
    "onlyLive": False,
    "maxItems": 3,
}

# Run the Actor and wait for it to finish
run = client.actor("vexaloom-labs/twitch-live-stream-channel-and-vod-metadata").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 '{
  "mode": "topStreams",
  "searchQuery": "lirik",
  "searchType": "all",
  "channelNames": [],
  "videoIds": [],
  "clipSlugs": [],
  "twitchUrls": [],
  "language": "EN",
  "streamSort": "VIEWER_COUNT",
  "streamTags": [],
  "streamType": "",
  "videoSort": "TIME",
  "clipPeriod": "LAST_WEEK",
  "clipSort": "VIEWS_DESC",
  "includeChannelClips": true,
  "includeChannelVideos": true,
  "onlyLive": false,
  "maxItems": 3
}' |
apify call vexaloom-labs/twitch-live-stream-channel-and-vod-metadata --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,vexaloom-labs/twitch-live-stream-channel-and-vod-metadata"
        }
    }
}
```

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/awepzbjt4Zv29dF9p/builds/LulWkQbhoV6gIZUhD/openapi.json