Apify Public Data & Leads

Twitch Real-Time Live Stream Intelligence and Viewership

twitch_live_streams

Read-only

Extract live Twitch streams, viewer counts, channel metadata, and game categories by language and category, enabling viewership tracking and influencer analysis.

Instructions

Extract real-time live broadcasting streams, viewer counts, channel metadata, and game categories from Twitch.

Behavioral Transparency:

Execution: Network call executed synchronously in the cloud via Apify Actor 'captainhandsome/twitch-live-streams-scraper'.
Side Effects: Reads public sources and creates a billed Actor run and dataset on your Apify account.
Authentication: Requires APIFY_TOKEN environment variable.
Latency & Limits: Typical run duration is 10-25 seconds; timeout capped at 120 seconds.

Usage Guidelines:

When to use: Use for live video broadcasting metrics, concurrent esports viewership tracking, influencer intelligence, and gaming category analysis.
When NOT to use: Do not use for recorded video-on-demand archives, YouTube channels, or employment job boards.
Named alternatives: Use 'glassdoor_jobs_search' for corporate hiring data, 'google_maps_search' for local retail directories, or 'airbnb_listings_search' for travel pricing.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`language`	No	ISO 639-1 language code filter for the live broadcast (e.g. 'en' for English, 'es' for Spanish, 'fr' for French). Defaults to 'en'.	en
`game_name`	No	Twitch category slug, such as minecraft or just-chatting. Defaults to minecraft.	minecraft
`max_results`	No	Maximum number of live stream channels to return. Integer between 1 and 100. Defaults to 10.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`run`	No
`error`	No
`status`	Yes
`results`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed28 schema fields changedv1.1.0Sep 15, 2026

addedInput schema / additionalProperties
```
Added value: +false
```
changedInput schema / properties / game_name / default
```
Previous value: -""New value: +"minecraft"
```

changedInput schema / properties / game_name / description

Previous value: -"Specific video game title or streaming category filter (e.g. 'Fortnite', 'Minecraft', or 'Just Chatting'). Leave empty for top streams across all categories."New value: +"Twitch category slug, such as minecraft or just-chatting. Defaults to minecraft."

addedInput schema / properties / game_name / pattern
```
Added value: +"^[a-z0-9-]+$"
```
addedOutput schema / properties / error
```
Added value: +{
+  "type": "object"
+}
```

removedOutput schema / properties / results / description

Removed value: -"Collection of active real-time Twitch stream broadcast records."

removedOutput schema / properties / results / items / properties / channelName

Removed value: -{
-  "description": "Twitch username or broadcaster channel handle.",
-  "type": "string"
-}

addedOutput schema / properties / results / items / properties / channel_display_name

Added value: +{
+  "description": "Public display name of the channel, preserving capitalization and non-Latin characters. Differs from channel_name, which is the lowercase URL login.",
+  "title": "Channel display name",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / results / items / properties / channel_name

Added value: +{
+  "description": "Twitch channel identifier parsed from its canonical URL.",
+  "minLength": 2,
+  "title": "Channel name",
+  "type": "string"
+}

addedOutput schema / properties / results / items / properties / channel_url

Added value: +{
+  "description": "Canonical public URL of the live channel.",
+  "pattern": "^https?://",
+  "title": "Twitch channel URL",
+  "type": "string"
+}

removedOutput schema / properties / results / items / properties / gameName

Removed value: -{
-  "description": "Primary game title or stream category.",
-  "type": "string"
-}

removedOutput schema / properties / results / items / properties / language

Removed value: -{
-  "description": "Language code of the broadcast.",
-  "type": "string"
-}

addedOutput schema / properties / results / items / properties / live_status

Added value: +{
+  "description": "Point-in-time live-state label.",
+  "title": "Live status",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / results / items / properties / profile_image_url

Added value: +{
+  "description": "Channel profile picture shown on the card, at 50x50 pixels.",
+  "title": "Channel avatar URL",
+  "type": [
+    "string",
+    "null"
+  ]
+}

removedOutput schema / properties / results / items / properties / streamTitle

Removed value: -{
-  "description": "Broadcaster headline title for the active live session.",
-  "type": "string"
-}

removedOutput schema / properties / results / items / properties / streamUrl

Removed value: -{
-  "description": "Canonical HTTPS stream link to the live broadcast channel.",
-  "type": "string"
-}

addedOutput schema / properties / results / items / properties / stream_category

Added value: +{
+  "description": "Game or category the stream is listed under. Populated on multi-category listing URLs such as twitch.tv/directory/all; empty on a single-category page, where the category is your input.",
+  "title": "Stream category",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / results / items / properties / stream_label

Added value: +{
+  "description": "Accessible stream title or preview label.",
+  "minLength": 3,
+  "title": "Stream label",
+  "type": "string"
+}

addedOutput schema / properties / results / items / properties / stream_tags

Added value: +{
+  "description": "Tags shown on the stream card, comma-separated. Mixes language, content and community tags, for example 'justchatting, drops, DropsEnabled'.",
+  "title": "Stream tags",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / results / items / properties / stream_title

Added value: +{
+  "description": "Title the streamer set for the live broadcast, in the original capitalization and without the ' - channel' suffix that stream_label carries.",
+  "title": "Stream title",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / results / items / properties / thumbnail_url

Added value: +{
+  "description": "Point-in-time Twitch stream preview image URL.",
+  "title": "Preview thumbnail URL",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / results / items / properties / verified_badge

Added value: +{
+  "description": "Badge label Twitch renders next to the channel name, 'Verified' for verified channels. Empty when the channel carries no badge.",
+  "title": "Verified badge",
+  "type": [
+    "string",
+    "null"
+  ]
+}

removedOutput schema / properties / results / items / properties / viewerCount

Removed value: -{
-  "description": "Number of concurrent live spectators actively watching the stream.",
-  "type": "integer"
-}

addedOutput schema / properties / results / items / properties / viewer_count

Added value: +{
+  "description": "Point-in-time viewer-count label shown by Twitch.",
+  "title": "Viewer count label",
+  "type": [
+    "string",
+    "null"
+  ]
+}

changedOutput schema / properties / results / items / required

Previous value: -[
-  "channelName",
-  "viewerCount"
-]New value: +[
+  "stream_label",
+  "channel_url",
+  "channel_name"
+]

addedOutput schema / properties / run
```
Added value: +{
+  "type": "object"
+}
```

addedOutput schema / properties / status

Added value: +{
+  "enum": [
+    "success",
+    "empty_unverified",
+    "partial",
+    "error"
+  ],
+  "type": "string"
+}

changedOutput schema / required

Previous value: -[
-  "results"
-]New value: +[
+  "results",
+  "status"
+]

Changed7 schema fields changedv1.0.6Sep 11, 2026

addedInput schema / properties / game_name / default
```
Added value: +""
```

changedInput schema / properties / game_name / description

Previous value: -"e.g. 'Fortnite' or 'Just Chatting'"New value: +"Specific video game title or streaming category filter (e.g. 'Fortnite', 'Minecraft', or 'Just Chatting'). Leave empty for top streams across all categories."

addedInput schema / properties / language / description

Added value: +"ISO 639-1 language code filter for the live broadcast (e.g. 'en' for English, 'es' for Spanish, 'fr' for French). Defaults to 'en'."

addedInput schema / properties / max_results / description

Added value: +"Maximum number of live stream channels to return. Integer between 1 and 100. Defaults to 10."

addedInput schema / properties / max_results / maximum
```
Added value: +100
```
addedInput schema / properties / max_results / minimum
```
Added value: +1
```

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "results": {
+      "description": "Collection of active real-time Twitch stream broadcast records.",
+      "items": {
+        "properties": {
+          "channelName": {
+            "description": "Twitch username or broadcaster channel handle.",
+            "type": "string"
+          },
+          "gameName": {
+            "description": "Primary game title or stream category.",
+            "type": "string"
+          },
+          "language": {
+            "description": "Language code of the broadcast.",
+            "type": "string"
+          },
+          "streamTitle": {
+            "description": "Broadcaster headline title for the active live session.",
+            "type": "string"
+          },
+          "streamUrl": {
+            "description": "Canonical HTTPS stream link to the live broadcast channel.",
+            "type": "string"
+          },
+          "viewerCount": {
+            "description": "Number of concurrent live spectators actively watching the stream.",
+            "type": "integer"
+          }
+        },
+        "required": [
+          "channelName",
+          "viewerCount"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "results"
+  ],
+  "type": "object"
+}

First observedv0.1.0Sep 11, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Even though annotations include readOnlyHint and destructiveHint, the description adds substantial behavioral context: synchronous cloud execution via a named Apify Actor, billing side effects and dataset creation, APIFY_TOKEN authentication requirement, and latency/timeout expectations. This goes well beyond what annotations provide and directly informs invocation decisions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description uses clear headings and bullet-style scannable sections. Every sentence contributes meaningful operational or selection information, and the core purpose is front-loaded before behavioral and usage details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a network-backed tool with billing, authentication, and latency characteristics, the description covers all essential operational context. The output schema exists, so return-value details are not required in the description, and the usage and side-effect sections fully equip an agent to decide and execute correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, with each parameter already documenting its purpose, default, and constraints. The tool description itself adds no additional parameter-level detail, but none is needed given the schema's completeness.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ('Extract real-time live broadcasting streams, viewer counts, channel metadata, and game categories from Twitch'), and differentiates itself from unrelated siblings by explicitly naming alternatives. The title also reinforces the tool's live-streaming focus, leaving no ambiguity about what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description contains a dedicated 'Usage Guidelines' section with both 'When to use' and 'When NOT to use' conditions, and provides named alternatives (glassdoor_jobs_search, google_maps_search, airbnb_listings_search). This gives an agent clear routing criteria and explicitly excludes VOD archives, YouTube channels, and job boards.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server