Vexaloom Labs
Actors/Twitch Live Stream, Channel & VOD Metadata Extractor

Twitch Live Stream, Channel & VOD Metadata Extractor

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

Open on ApifyGitHub source

Input schema

Input fields, types, required flags, descriptions, defaults, and prefills come from the published definition. Prefill examples are distinct from defaults.

FieldTypeRequiredDescription
modestringrequiredWhat to fetch.
searchQuerystringoptionalFree-text query for `mode=search` — matches channels, categories, and videos.
searchTypestringoptionalRestrict search results to one index. `all` returns channels, categories, and videos.
Show all input fields
FieldTypeRequiredDescription
modestringrequiredWhat to fetch.
searchQuerystringoptionalFree-text query for `mode=search` — matches channels, categories, and videos.
searchTypestringoptionalRestrict search results to one index. `all` returns channels, categories, and videos.
channelNamestringoptionalTwitch channel login or channel URL, e.g. `lirik` or `https://www.twitch.tv/lirik`.
channelNamesarrayoptionalBatch channel logins or channel URLs. Duplicates and the single `channelName` are merged.
categorySlugstringoptionalCategory slug (`just-chatting`), exact name (`Just Chatting`), or directory URL.
videoIdstringoptionalTwitch VOD ID or VOD URL, e.g. `2766365638`.
videoIdsarrayoptionalBatch VOD IDs or VOD URLs. Duplicates and the single `videoId` are merged.
clipSlugstringoptionalTwitch clip slug or clip URL, e.g. `AcceptablePleasantAuberginePanicVis-EVdxDQ1vsQAQZpBS`.
clipSlugsarrayoptionalBatch clip slugs or clip URLs. Duplicates and the single `clipSlug` are merged.
twitchUrlsarrayoptionalChannel, VOD, clip, or category URLs. Category and channel `/videos` and `/clips` tabs are supported.
languagestringoptionalFilter live streams, VODs, and clips to one broadcast language. Leave on `(any)` for no filter.
streamSortstringoptionalSort live streams by viewers (high to low or low to high), recently started, or recommended.
streamTagsarrayoptionalOnly live streams carrying all of these freeform tags, e.g. `English`, `DropsEnabled`, `NoBackseating`.
streamTypestringoptionalRestrict channel or category VODs to one broadcast type. Leave blank for all types.
videoSortstringoptionalSort channel or category VODs by publish time or view count.
clipPeriodstringoptionalTime window over which clips were created.
clipSortstringoptionalSort clips by views or trending score.
includeChannelClipsbooleanoptionalAlso fetch and emit top clips for each channel.
includeChannelVideosbooleanoptionalAlso fetch and emit recent VODs for each channel.
minViewersCountintegeroptionalDrop live streams (and categories) below this viewer count.
minViewCountintegeroptionalDrop VODs and clips below this total view count.
minFollowersCountintegeroptionalDrop channels and live streams below this follower count. VODs and clips are unaffected.
maxFollowersCountintegeroptionalDrop channels and live streams above this follower count. Useful for finding smaller creators.
onlyLivebooleanoptionalDrop channel profile records for channels that are not live right now. Their VODs and clips are still returned.
containsKeywordstringoptionalCase-insensitive substring filter on stream, VOD, and clip titles.
maxItemsintegeroptionalHard cap on emitted records. Twitch source caps still apply (e.g. about 1,000 clips per category).

Download the published input schema

View complete JSON
{
  "description": "Search Twitch, fetch top live streams, browse categories and category VODs, or look up channels, videos, and clips by ID or URL. No Twitch login is required.",
  "properties": {
    "categorySlug": {
      "description": "Category slug (`just-chatting`), exact name (`Just Chatting`), or directory URL.",
      "editor": "textfield",
      "title": "Category slug, name, or URL (mode=byCategory, byCategoryVideos, topClips)",
      "type": "string"
    },
    "channelName": {
      "description": "Twitch channel login or channel URL, e.g. `lirik` or `https://www.twitch.tv/lirik`.",
      "editor": "textfield",
      "title": "Channel login (mode=byChannel)",
      "type": "string"
    },
    "channelNames": {
      "default": [],
      "description": "Batch channel logins or channel URLs. Duplicates and the single `channelName` are merged.",
      "editor": "stringList",
      "prefill": [],
      "title": "Channel logins or URLs (mode=byChannel)",
      "type": "array"
    },
    "clipPeriod": {
      "default": "LAST_WEEK",
      "description": "Time window over which clips were created.",
      "editor": "select",
      "enum": [
        "LAST_DAY",
        "LAST_WEEK",
        "LAST_MONTH",
        "ALL_TIME"
      ],
      "enumTitles": [
        "Last 24 hours",
        "Last 7 days",
        "Last 30 days",
        "All time"
      ],
      "prefill": "LAST_WEEK",
      "title": "Clip time window",
      "type": "string"
    },
    "clipSlug": {
      "description": "Twitch clip slug or clip URL, e.g. `AcceptablePleasantAuberginePanicVis-EVdxDQ1vsQAQZpBS`.",
      "editor": "textfield",
      "title": "Clip slug (mode=byClip)",
      "type": "string"
    },
    "clipSlugs": {
      "default": [],
      "description": "Batch clip slugs or clip URLs. Duplicates and the single `clipSlug` are merged.",
      "editor": "stringList",
      "prefill": [],
      "title": "Clip slugs or URLs (mode=byClip)",
      "type": "array"
    },
    "clipSort": {
      "default": "VIEWS_DESC",
      "description": "Sort clips by views or trending score.",
      "editor": "select",
      "enum": [
        "VIEWS_DESC",
        "TRENDING"
      ],
      "enumTitles": [
        "Most viewed first",
        "Trending"
      ],
      "prefill": "VIEWS_DESC",
      "title": "Clip order",
      "type": "string"
    },
    "containsKeyword": {
      "description": "Case-insensitive substring filter on stream, VOD, and clip titles.",
      "editor": "textfield",
      "title": "Title contains keyword",
      "type": "string"
    },
    "includeChannelClips": {
      "default": true,
      "description": "Also fetch and emit top clips for each channel.",
      "prefill": true,
      "sectionCaption": "Channel Enrichment",
      "title": "Include clips (mode=byChannel)",
      "type": "boolean"
    },
    "includeChannelVideos": {
      "default": true,
      "description": "Also fetch and emit recent VODs for each channel.",
      "prefill": true,
      "title": "Include VODs (mode=byChannel)",
      "type": "boolean"
    },
    "language": {
      "default": "EN",
      "description": "Filter live streams, VODs, and clips to one broadcast language. Leave on `(any)` for no filter.",
      "editor": "select",
      "enum": [
        "",
        "EN",
        "ES",
        "DE",
        "FR",
        "PT",
        "RU",
        "JA",
        "KO",
        "ZH",
        "IT",
        "TR",
        "PL",
        "AR",
        "TH",
        "ID",
        "VI",
        "NL",
        "SV",
        "FI",
        "DA",
        "NO",
        "CS",
        "HU",
        "EL",
        "RO",
        "BG",
        "UK",
        "HE",
        "MS",
        "TL",
        "ASL",
        "OTHER"
      ],
      "enumTitles": [
        "(any)",
        "English (EN)",
        "Spanish (ES)",
        "German (DE)",
        "French (FR)",
        "Portuguese (PT)",
        "Russian (RU)",
        "Japanese (JA)",
        "Korean (KO)",
        "Chinese (ZH)",
        "Italian (IT)",
        "Turkish (TR)",
        "Polish (PL)",
        "Arabic (AR)",
        "Thai (TH)",
        "Indonesian (ID)",
        "Vietnamese (VI)",
        "Dutch (NL)",
        "Swedish (SV)",
        "Finnish (FI)",
        "Danish (DA)",
        "Norwegian (NO)",
        "Czech (CS)",
        "Hungarian (HU)",
        "Greek (EL)",
        "Romanian (RO)",
        "Bulgarian (BG)",
        "Ukrainian (UK)",
        "Hebrew (HE)",
        "Malay (MS)",
        "Tagalog (TL)",
        "American Sign Language (ASL)",
        "Other"
      ],
      "prefill": "EN",
      "sectionCaption": "Filters & Sorting",
      "title": "Broadcast language",
      "type": "string"
    },
    "maxFollowersCount": {
      "description": "Drop channels and live streams above this follower count. Useful for finding smaller creators.",
      "maximum": 100000000,
      "minimum": 0,
      "title": "Maximum followers",
      "type": "integer"
    },
    "maxItems": {
      "default": 50,
      "description": "Hard cap on emitted records. Twitch source caps still apply (e.g. about 1,000 clips per category).",
      "maximum": 5000,
      "minimum": 1,
      "prefill": 3,
      "sectionCaption": "Limits",
      "title": "Max items",
      "type": "integer"
    },
    "minFollowersCount": {
      "description": "Drop channels and live streams below this follower count. VODs and clips are unaffected.",
      "maximum": 100000000,
      "minimum": 0,
      "title": "Minimum followers",
      "type": "integer"
    },
    "minViewCount": {
      "description": "Drop VODs and clips below this total view count.",
      "maximum": 100000000,
      "minimum": 0,
      "title": "Minimum total views",
      "type": "integer"
    },
    "minViewersCount": {
      "description": "Drop live streams (and categories) below this viewer count.",
      "maximum": 1000000,
      "minimum": 0,
      "title": "Minimum concurrent viewers",
      "type": "integer"
    },
    "mode": {
      "default": "topStreams",
      "description": "What to fetch.",
      "editor": "select",
      "enum": [
        "topStreams",
        "topGames",
        "search",
        "byChannel",
        "byCategory",
        "byCategoryVideos",
        "topClips",
        "byVideo",
        "byClip",
        "byUrl"
      ],
      "enumTitles": [
        "Top live streams",
        "Top games / categories",
        "Search Twitch (channels / categories / videos)",
        "Channel info + recent VODs + clips + schedule",
        "Browse a category (live streams)",
        "Browse a category (VODs)",
        "Top clips for a category",
        "Lookup VODs by video ID",
        "Lookup clips by slug",
        "Resolve Twitch URLs"
      ],
      "prefill": "topStreams",
      "sectionCaption": "Mode & Query",
      "title": "Mode",
      "type": "string"
    },
    "onlyLive": {
      "default": false,
      "description": "Drop channel profile records for channels that are not live right now. Their VODs and clips are still returned.",
      "prefill": false,
      "title": "Only live channels",
      "type": "boolean"
    },
    "searchQuery": {
      "default": "lirik",
      "description": "Free-text query for `mode=search` — matches channels, categories, and videos.",
      "editor": "textfield",
      "prefill": "lirik",
      "title": "Search query (mode=search)",
      "type": "string"
    },
    "searchType": {
      "default": "all",
      "description": "Restrict search results to one index. `all` returns channels, categories, and videos.",
      "editor": "select",
      "enum": [
        "all",
        "channel",
        "game",
        "video"
      ],
      "enumTitles": [
        "All result types",
        "Channels only",
        "Categories only",
        "Videos only"
      ],
      "prefill": "all",
      "title": "Search result type (mode=search)",
      "type": "string"
    },
    "streamSort": {
      "default": "VIEWER_COUNT",
      "description": "Sort live streams by viewers (high to low or low to high), recently started, or recommended.",
      "editor": "select",
      "enum": [
        "VIEWER_COUNT",
        "VIEWER_COUNT_ASC",
        "RECENT",
        "RELEVANCE"
      ],
      "enumTitles": [
        "Most viewers first",
        "Fewest viewers first",
        "Recently started first",
        "Recommended"
      ],
      "prefill": "VIEWER_COUNT",
      "title": "Live stream order",
      "type": "string"
    },
    "streamTags": {
      "default": [],
      "description": "Only live streams carrying all of these freeform tags, e.g. `English`, `DropsEnabled`, `NoBackseating`.",
      "editor": "stringList",
      "prefill": [],
      "title": "Stream tags",
      "type": "array"
    },
    "streamType": {
      "default": "",
      "description": "Restrict channel or category VODs to one broadcast type. Leave blank for all types.",
      "editor": "select",
      "enum": [
        "",
        "ARCHIVE",
        "HIGHLIGHT",
        "UPLOAD",
        "PAST_PREMIERE",
        "PREMIERE_UPLOAD"
      ],
      "enumTitles": [
        "(any)",
        "Archive (past broadcast)",
        "Highlight",
        "Upload",
        "Past Premiere",
        "Premiere Upload"
      ],
      "prefill": "",
      "title": "VOD type",
      "type": "string"
    },
    "twitchUrls": {
      "default": [],
      "description": "Channel, VOD, clip, or category URLs. Category and channel `/videos` and `/clips` tabs are supported.",
      "editor": "stringList",
      "prefill": [],
      "title": "Twitch URLs (mode=byUrl)",
      "type": "array"
    },
    "videoId": {
      "description": "Twitch VOD ID or VOD URL, e.g. `2766365638`.",
      "editor": "textfield",
      "title": "Video ID (mode=byVideo)",
      "type": "string"
    },
    "videoIds": {
      "default": [],
      "description": "Batch VOD IDs or VOD URLs. Duplicates and the single `videoId` are merged.",
      "editor": "stringList",
      "prefill": [],
      "title": "Video IDs or URLs (mode=byVideo)",
      "type": "array"
    },
    "videoSort": {
      "default": "TIME",
      "description": "Sort channel or category VODs by publish time or view count.",
      "editor": "select",
      "enum": [
        "TIME",
        "VIEWS"
      ],
      "enumTitles": [
        "Newest first (TIME)",
        "Most viewed first (VIEWS)"
      ],
      "prefill": "TIME",
      "title": "VOD order",
      "type": "string"
    }
  },
  "required": [
    "mode"
  ],
  "schemaVersion": 1,
  "title": "Twitch Scraper Input",
  "type": "object"
}

Output schema

Published result links and storage locations. This schema is not an exhaustive contract for every field in a dataset record.

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

Download the published output schema

View complete JSON
{
  "actorOutputSchemaVersion": 1,
  "description": "Twitch records — live streams, channels, videos (VODs), clips, and games (categories) with viewers, followers, durations, thumbnails, broadcaster details, socials, schedules, and direct URLs.",
  "properties": {
    "records": {
      "description": "Dataset containing all scraped Twitch records (streams, channels, videos, clips, games).",
      "template": "{{links.apiDefaultDatasetUrl}}/items",
      "title": "Twitch records",
      "type": "string"
    }
  },
  "title": "Twitch Live Stream, Channel & VOD Metadata Extractor Output"
}

Dataset schema

Published dataset views and any declared field definitions. A view can select only a subset of the returned record fields.

Download the published dataset schema

View complete JSON
{
  "actorSpecification": 1,
  "views": {
    "overview": {
      "display": {
        "component": "table",
        "properties": {}
      },
      "title": "Twitch records",
      "transformation": {
        "fields": [
          "recordType",
          "title",
          "channelName",
          "displayName",
          "viewersCount",
          "viewCount",
          "gameName",
          "url"
        ]
      }
    }
  }
}

Key-value schema

Published key-value store definitions, when provided by this build.

This definition is not present in the default published build. See the published README for available documentation.

Published README

Read the full published documentation

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

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

Example: channel profiles with schedules and media

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

Example: category VODs

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

Example: mixed URL resolution

{
  "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.

Python quickstart

Use a schema-derived input and the Python standard library to start a run. An Apify account and token are required for execution.

Open the step-by-step Python guide →

Source build LulWkQbhoV6gIZUhD. Documentation is regenerated from the default published build; private drafts are not included.