Twitch API & Scraper
The Twitch API returns streaming data as clean JSON.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
The primary channel endpoint returns a channel's id, login, display name, description, creation date, images and follower count, and you can pull a live stream, videos, clips, search channels and categories, and top games. It is built for streaming analytics and esports tools that need Twitch data without a scraper. One ReefAPI key, one shared credit pool, the standard envelope.
The five Twitch identifiers, and which one belongs in a URL
Twitch hands out several ids that look interchangeable and are not. The most common mistake is building a clip link from the clip id, which does not resolve. Values below are from measured responses.
| Identifier | Measured example | What it is for |
|---|---|---|
| channel id | 37402112 | numeric string, permanent — a streamer can rename their login, the id never changes. Store this, not the handle. |
| login | shroud | the handle in twitch.tv/<login>; every channel action takes it and it is case-insensitive |
| video id | 2854436054 | resolves as twitch.tv/videos/<id> |
| clip id | 2358589597 | numeric — and NOT the value that appears in a clip URL |
| clip slug | TangentialBillowingJalapenoYee-ccA2oB1pEYh4CHWJ | the URL segment: twitch.tv/<login>/clip/<slug>. This is what you link to. |
| category/game id | 509658 (Just Chatting), 32982 (Grand Theft Auto V) | numeric and stable, though the directory URL is built from the display name instead |
A category's returned url contains the display name with literal spaces — measured: https://www.twitch.tv/directory/category/Just Chatting. Percent-encode it before you request it or hand it to an HTTP client.
Real request and response JSON
Captured from the indexed primary action, channel, on .
{
"method": "POST",
"url": "https://api.reefapi.com/twitch/v1/channel",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"login": "shroud"
}
}{
"ok": true,
"meta": {
"api": "twitch",
"endpoint": "channel",
"mode": "live",
"latency_ms": 754,
"record_count": 1,
"bytes": 815,
"cache_hit": false,
"charged_credits": 1,
"version": "1.0.0"
},
"data": {
"channel": {
"id": "37402112",
"login": "shroud",
"display_name": "shroud",
"description": "I'm back baby",
"created_at": "2012-11-03T15:50:32.87847Z",
"profile_image": "https://static-cdn.jtvnw.net/jtv_user_pictures/c754eebf-745b-4e0a-814a-10bcaecaabbc-profile_image-300x300.png",
"banner_image": "https://static-cdn.jtvnw.net/jtv_user_pictures/dbee25e8-55b7-4565-87f0-e9d4661dcc66-profile_banner-480.jpeg",
"follower_count": 11293187,
"is_partner": true,
"is_affiliate": false,
"is_staff": null,
"primary_color": "00ADFF",
"is_live": true,
"stream": {
"id": "320449691740",
"is_live": true,
"title": "playing till we get ddosed",
"viewer_count": 10765,
"started_at": "2026-09-23T17:50:19Z",
"type": "live",
"game": {
"id": "743893402",
"name": "WARDOGS",
"display_name": "WARDOGS"
},
"thumbnail": null
},
"url": "https://www.twitch.tv/shroud"
}
}
}What the Twitch API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| channel | Full channel/user profile by login: id, display name, description, created-at, profile and banner image, follower count, partner/affiliate/staff flags, and the current live stream (title, viewer count, game/category, started-at) if live. | Social-listening tools call channel to get full channel/user profile by login. | login |
| stream | Live status of a channel: whether it is live right now and, if so, the stream id, title, viewer count, game/category, started-at timestamp and a 1080p thumbnail. Returns is_live=false (honest-empty) for an offline channel. | Creator and influencer platforms call stream to get live status of a channel. | login |
| videos | A channel's past broadcasts / VODs (most recent first), up to 100 in one page: id, title, duration, view count, published-at, game/category and thumbnail. Note: Twitch integrity-gates pagination beyond the first page for keyless access. | Brand-monitoring teams call videos to get a channel's past broadcasts / VODs (most recent first), up to 100 in one page. | login, limit, type, sort |
| clips | Top clips of a channel, ranked by views, up to 100 in one page: id, slug, title, view count, created-at, duration, game/category, the clip creator and the clip URL. Filter the time window with `period`. Pagination beyond page one is integrity-gated. | Audience analysts call clips to get top clips of a channel, ranked by views, up to 100 in one page. | login, limit, period |
| search_channels | Search Twitch channels by name/keyword. Returns matching channels with id, login, display name, description, follower count, partner/affiliate flags and live status (viewer count + game when live). | Social-listening tools call search_channels to search Twitch channels by name/keyword. | query, limit |
| search_categories | Search Twitch games/categories by name. Returns matching categories with id, name, display name, current live viewer count and box-art image. | Creator and influencer platforms call search_categories to search Twitch games/categories by name. | query, limit |
| top_games | The top games/categories on Twitch right now, ranked by live viewers: id, name, display name, current viewer count, content tags and box-art image. Up to 30. | Brand-monitoring teams call top_games to get the top games/categories on Twitch right now, ranked by live viewers. | limit |
| top_streams | The top live streams on Twitch right now, ranked by viewers: stream id, title, viewer count, started-at, the broadcasting channel (login, display name) and the game/category. Up to 30. | Audience analysts call top_streams to get the top live streams on Twitch right now, ranked by viewers. | limit |
| game | Game/category detail by name plus its top live streams: category id, display name, total live viewers, description, avatar — and the top channels (up to 30) currently streaming it, each with title, viewer count and broadcaster. | Social-listening tools call game to get game/category detail by name plus its top live streams. | name, limit |
| schedule | A channel's stream schedule: the next upcoming stream (start, title, category) plus the channel's recurring weekly schedule segments — each with start/end time, title, cancelled flag and the planned game/category. Returns honest-empty when the channel has not published a schedule. | Creator and influencer platforms call schedule to get a channel's stream schedule. | login |
| game_clips | Top clips for a whole game/category (site-wide, across all channels), ranked by views, up to 100 in one page: id, slug, title, view count, created-at, duration, the broadcaster the clip is from, the clip creator and the URL. Filter the time window with `period`. Pagination beyond page one is integrity-gated. | Brand-monitoring teams call game_clips to get top clips for a whole game/category (site-wide, across all channels), ranked by views, up to…. | name, limit, period |
| game_videos | Top past broadcasts / VODs for a whole game/category (site-wide, across all channels), up to 100 in one page: id, title, duration, view count, published-at, the owning channel and a thumbnail. Order by views (default) or newest. Pagination beyond page one is integrity-gated. | Audience analysts call game_videos to get top past broadcasts / VODs for a whole game/category (site-wide, across all channels), up to…. | name, limit, sort |
| team | A Twitch team profile by name plus its member channels: team id, name, display name, description, logo/banner image — and the member channels (up to 100), each with login, display name, partner/affiliate status and current live status (viewer count + game when live). | Social-listening tools call team to get a Twitch team profile by name plus its member channels. | name, limit |
Call channel from your stack
curl -X POST https://api.reefapi.com/twitch/v1/channel \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"login":"shroud"}'import requests
r = requests.post(
"https://api.reefapi.com/twitch/v1/channel",
headers={"x-api-key": REEF_KEY},
json={
"login": "shroud"
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/twitch/v1/channel", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"login": "shroud"
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.twitch.channel with {"login":"shroud"}.Who uses this API and why
- Streaming analytics call channel and stream to track a streamer's status and audience.
- Esports tools use top_games and clips to follow trends.
- Discovery uses search_channels and search_categories to find creators.
Questions developers ask before integrating
Why is is_staff null instead of false on a channel?
Because Twitch did not state it, and we do not fill that in. A measured channel lookup on shroud returned is_partner true, is_affiliate false and is_staff null side by side — the first two are asserted, the third is simply absent from the source. Treat null as unknown. If you coerce it to false you will be recording a claim the API never made, and the distinction matters exactly when someone asks you to prove it.
Why does created_at break my date parser?
Twitch emits sub-second precision at an unusual width. A measured channel created_at came back as 2012-11-03T15:50:32.87847Z — five fractional digits, where most strict ISO-8601 parsers expect three or six and will throw. Every other timestamp in this API (published_at on a VOD, created_at on a clip, started_at on a stream) is plain second-precision UTC with a Z. Parse leniently, or truncate the fraction before parsing.
What comes back for an offline channel?
An honest empty, not an error. The stream action returns is_live: false with no stream object rather than a 404, and the channel action returns is_live: false with stream: null — null, not {}. That is deliberate: a polling job that treats 'offline' as a failure will retry forever and burn credits. Check is_live and only then read stream.
How long is a VOD, and can I sort by views?
duration_seconds is an integer, not a formatted string — a measured shroud broadcast returned 29261, which is 8 hours 7 minutes 41 seconds, alongside view_count 494070 and published_at 2026-08-23T17:44:06Z. The videos action defaults to type ARCHIVE (past broadcasts) sorted by TIME; switch type to HIGHLIGHT, UPLOAD or ALL, and sort to VIEWS for a most-watched ranking. Up to 100 in a single page.
Why does a clips call return nothing for an active channel?
Almost always the period default. clips defaults to LAST_WEEK, so a channel that has not streamed in the last seven days has no top clips in that window and legitimately returns an empty list. Set period to LAST_MONTH or ALL_TIME. A measured ALL_TIME call on shroud returned clips from 2023 with view counts above 560,000, which a LAST_WEEK call would never surface.
meta says has_more is true — how do I fetch the next page?
You cannot, and we would rather say so than pretend. Both videos and clips return a single page of up to 100 records; deeper pagination is gated on Twitch's side for keyless access, so has_more reflects what Twitch reported, not what is reachable. Plan around the 100-record page: narrow with type, sort or period instead of paging. stop_reason 'page_limit' in meta is the signal that you hit this ceiling rather than the end of the data.
Is viewer_count live or an average?
It is a point-in-time snapshot taken when you called. top_games measured Just Chatting at 536,077 concurrent viewers and Grand Theft Auto V at 118,650 in the same request, which are concurrents right then — not daily averages and not hours watched. If you need a trend you have to poll and store; nothing in the response is historical. follower_count on a channel is different in kind: it is a lifetime cumulative total (11,287,811 measured for shroud) and only goes up.
Who is the clipper field, and can I find a game's category id?
clipper is the login of the viewer who created the clip, not the streamer — a handle distinct from the channel's on every shroud clip measured, which is what you need for attribution or for finding prolific clippers. For categories, search_categories resolves a game name to its id, current live viewer_count and box art; top_games gives the same shape ranked by concurrent viewers with content tags attached (measured: Just Chatting tagged ['IRL']).
What is the Twitch API?
Twitch API is a ReefAPI endpoint group for twitch It returns live JSON through POST requests under /twitch/v1.
Is the Twitch API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. Twitch calls use the same shared credit balance as every other ReefAPI engine.
Do I need a Twitch login or account?
No login to Twitch is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the Twitch data?
The page example is captured from a live channel call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the Twitch API use?
Twitch actions currently cost 1 credit per successful call. Failed or blocked calls are free. All APIs draw from one credit pool.
Can I call Twitch from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call twitch actions with the same key, credit pool and JSON envelope used by normal REST requests.