Twitch Channel & Category Scraper

Scrapes Twitch channel stats and live streams — follower counts, live viewer counts, stream title, category, uptime, recent VODs and top clips. No login, no OAuth, no API key, no developer registration.

Useful for influencer discovery, sponsorship research, competitor tracking, category trend monitoring, and building a live-status dashboard across many channels.

Two modes

• Channels — look up specific channels by name. Live and offline channels both return a row.
• Category — list the streams live in a category right now, e.g. Just Chatting, with each broadcaster's follower count attached.

What makes this different

Follower and live-viewer counts, which the page alone won't give you. These come from the same public gateway the Twitch web app uses. A scraper that only parses the channel HTML gets structured data with clip listings but no follower count and no live viewer count — the two numbers most of this data is actually wanted for.

Offline channels still produce a row. is_live is a real field, not an inference, and an offline channel keeps last_broadcast_title, last_broadcast_game and last_broadcast_started_at. Monitoring a roster of channels tells you what each one last streamed and when — not just silence.

Category ranking that's actually ranked. Twitch's own browse order only approximates viewer count; promoted streams sit near the top regardless of size. Because a whole category arrives in one request, this Actor re-ranks it exactly and stamps a rank on every row. Turn sortByViewers off to keep Twitch's ordering.

category_total_viewers on every category row. Total viewers across the category at scrape time, so a stream's share of its category is a division rather than a second run.

The tags are the real tags. Twitch exposes two tag fields; one is permanently empty and the other is the one the site displays. This reads the one that isn't empty — a detail that silently costs a naive scraper every tag on every row.

Box-art URLs that actually load. Twitch returns category art containing literal {width}/{height} placeholders. Passed through unmodified those 404 in any browser; here they're filled in.

Channel lookups are batched. 25 channels cost one request, not 25 — so a roster of 100 channels with VODs and clips finishes in about four calls.

Uptime is precomputed. stream_uptime_minutes is derived at scrape time, so "who has been live over four hours" is a filter rather than a date-arithmetic pass.

Input

Field	Type	Notes
mode	enum	channels or category.
targets	array	Channel names (URLs accepted) or category names.
includeVideos	integer	Recent VODs per channel, 0 to skip. Channels mode.
includeClips	integer	Top clips per channel, 0 to skip. Channels mode.
clipPeriod	enum	Window clips are ranked within.
maxItems	integer	Streams per category, up to 100.
sortByViewers	boolean	Exact viewer ranking. Default on.
proxyConfiguration	object	Not normally needed.

Two limits worth knowing up front

Category depth caps at 100 streams. Twitch rejects a page size above 100 outright, and gates cursor pagination behind an integrity check that cannot be satisfied without a browser. So 100 per category per run is the honest ceiling — this Actor takes the largest page the API allows and does not pretend to page past it. For a large category, re-run on a schedule instead.

Category names must match Twitch's spelling exactly. Just Chatting, not just chatting or Chatting. A name that doesn't match is reported as a failure for that target rather than returning silently empty.

Output

{
  "channel_id": "twitch.tv:37402112",
  "login": "shroud",
  "display_name": "shroud",
  "follower_count": 11288146,
  "is_partner": true,
  "account_created_at": "2012-11-03T15:50:32Z",
  "is_live": true,
  "stream_title": "going for apache",
  "viewer_count": 11450,
  "stream_uptime_minutes": 273,
  "game_name": "WARDOGS",
  "stream_tags": ["English", "DropsEnabled"],
  "url": "https://www.twitch.tv/shroud"
}

A channel that does not exist is logged and skipped rather than emitting a hollow row. Each run also writes a RUN_COVERAGE record to the key-value store with what was requested, what came back, and any per-target failures — so a partial run is visible rather than silent.

Local development

pip install -r requirements.txt
python test_local.py --mode channels shroud pokimane --videos 5 --clips 5
python test_local.py --mode category "Just Chatting" --max 25 --out sample_output.json

sample_output.json is real output from a live category run.