Check Twitch live status and pull clips without a developer key
The Twitch API returns streaming data as clean JSON.
13 active endpoints. Every call is 1 credit.
- POST/twitch/v1/channel
- POST/twitch/v1/stream
- POST/twitch/v1/videos
- POST/twitch/v1/clips
- POST/twitch/v1/search_channels
- POST/twitch/v1/search_categories
- POST/twitch/v1/top_games
- +6 more
What Twitch endpoints does ReefAPI ship?
13 live read endpoints. Read-only data API: no writes, no account actions, no dashboard access on the target site.
Twitch API
3 of 13 endpoints, ready to run
The biggest live streams on Twitch at this second, with viewer counts, titles, start times and the category each one is in.
{ "ok": true, "meta": { "api": "twitch", "endpoint": "top_streams", "mode": "live", "latency_ms": 463.8, "record_count": 30, "cache_hit": false }, "data": { "streams": [ { "id": "321089399513", "title": "GO Day 1 | 2026 Pokémon World Championships", "viewer_count": 69628, "started_at": "2026-08-28T15:30:18Z", "type": "live", "channel": { "id": "116082737" }, "game": { "id": "490655", "name": "Pokémon GO" }, "thumbnail": "https://static-cdn.jtvnw.net/previews-ttv/live_user_pokemongo-640x360.jpg", "url": "https://www.twitch.tv/pokemongo" }, { "id": "317333662455", "title": "VGC Day 1 | 2026 Pokémon World Championships", "viewer_count": 62716, "started_at": "2026-08-28T15:30:28Z", "type": "live", "channel": { "id": "36653045" }, "game": { "id": "1931693784", "name": "Pokémon Champions" }, "thumbnail": "https://static-cdn.jtvnw.net/previews-ttv/live_user_pokemon-640x360.jpg", "url": "https://www.twitch.tv/pokemon" }, { "id": "318453888102", "title": "🔴TOP100🔴ИГРАЕМ🔴ТАЩИМ🔴", "viewer_count": 49532, "started_at": "2026-08-28T16:13:41Z", "type": "live", "channel": { "id": "475757024" }, "game": { "id": "29595", "name": "Dota 2" }, "thumbnail": "https://static-cdn.jtvnw.net/previews-ttv/live_user_rostislav_999-640x360.jpg", "url": "https://www.twitch.tv/rostislav_999" } ] } }
How the Twitch API works
Twitch is a normal ReefAPI surface — the same four rules that hold for every other engine on the key.
No OAuth app, no request signing, no per-site account. One key covers all 184 engines.
Every route is a POST with a JSON body. Parameters are validated against the published schema before anything is charged.
Credits, not seats. Failed and blocked calls are never charged, and cache hits cost nothing.
One envelope everywhere. meta carries latency_ms, record_count and the endpoint that answered.
Is the channel live, and what has it published
The three questions asked of Twitch most often are answered by three calls, none of which needs a token, and all of which came back in about a second.
{"login": "pokimane"}is_live plus, when it is true, the stream id, title, viewer count, category, start time and thumbnail. When it is false you get is_live false and a null stream, under ok:true.
{"login": "pokimane", "limit": 100}A hundred past broadcasts in a single page in 1.0 second, each with duration, view count, ISO publication date and category.
{"login": "pokimane", "limit": 100, "period": "ALL_TIME"}A hundred top clips in 0.6 seconds, reaching back to 2022 on the channel we tested.
Live status, the archive and the highlights, without registering an application or rotating a client secret.
curl -X POST https://api.reefapi.com/twitch/v1/top_streams \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"limit":5}'{
"ok": true,
"data": { … },
"meta": {
"api": "twitch",
"endpoint": "top_streams",
"mode": "live",
"latency_ms": …,
"record_count": …
},
"error": null
}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.
Where the real ceilings are, and what an empty answer means
Measured on 2026-08-28 across fourteen calls covering every action on this engine. Two of these lines go against us.
No client id, no client secret, no OAuth token to refresh, no application to register and have approved. You send a ReefAPI key and a channel name. All fourteen calls we made across this engine answered between half a second and under two seconds, and not one of them was throttled — this is the fastest engine in the batch.
An offline channel returns is_live false and a null stream under ok:true — not an error, not a stale cached stream. When a channel is live the same call returns the stream id, title, viewer count, category, started_at and a full-resolution thumbnail.
Against us. Past broadcasts, a channel's clips and a whole category's clips each returned exactly 100 rows in one call, marked stop_reason page_limit with has_more true — but paging past that first page is gated by Twitch for keyless access. Treat a hundred as the per-call ceiling and reach further by varying the filter — the clip period from a day to all time, the video type between broadcasts, highlights and uploads — rather than by paging.
Against us. The top-streams action accepts a limit of up to 100 and returned thirty whether we asked for twenty or a hundred. Channel search returned thirty for a limit of fifty. The top-games list returned thirty. The rows are real and the counts are live; the ceiling is thirty, and asking for more does not change it.
published_at on past broadcasts, created_at on clips, started_at on live streams, created_at on the channel itself. One all-time clip pull on a single channel reached back to 2022 in that one call, so ranking a channel's whole highlight history needs no date bookkeeping on your side.
Top games with live viewer counts and box art; a game action returning the category's total live viewers plus up to thirty channels currently on it; clips and past broadcasts for a whole category across every channel; and team profiles with their member channels. Category search resolves a name to an id, viewer count and box art.
A channel with no published schedule returned has_schedule false, a null next segment and an empty segment list, rather than an error or an unexplained blank. The same discipline runs through the engine: where there is nothing, the response says which nothing it is.
Public channel, stream, past-broadcast, clip, category and team data. Not chat logs, not subscriber lists, not a channel's revenue or its analytics dashboard — none of which is public, and none of which registering a developer key would have given you either.
What people build with Twitch
The jobs this data is most often used for.
endpoints
credit per call
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.
What Twitch data costs
The cheapest call here is 1 credit, so $15/mo (Pro) buys 10,000 of them — $1.50 per 1,000 credits. Credits roll over and never expire, and failed or blocked calls are not charged.
Full pricing →- 1,000 free credits on signup, no card
- One key, all 184 APIs, one credit pool
- Failed and blocked calls are never charged
- Credits roll over and never expire
Call it in two lines
Sign up, get 1,000 credits and one key that works on every engine. Then this is the whole protocol.
curl -X POST https://api.reefapi.com/twitch/v1/top_streams \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"limit":5}'import requests
r = requests.post(
"https://api.reefapi.com/twitch/v1/top_streams",
headers={"x-api-key": REEF_KEY},
json={
"limit": 5
},
)
print(r.json()["data"])Have a question? We got answers.
The questions people actually ask before wiring up Twitch.
Get a free key →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, and 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.
10 Social Media APIs on the same key
One key, one credit pool, one response envelope. If you are pulling Twitch, you are one call away from the rest of the category — no second contract, no second integration.
Need something this API does not do?
Name the endpoint, the field, or a source we do not carry yet. We ship new APIs every week and you would be first to get the key. Real people read every message and reply the same day.
Try it on your own data before you pay anything
The call above is the real endpoint, not a recording. A free key gives you 1,000 credits, the other 183 APIs, and the same envelope everywhere.
Endpoints, parameters and credit costs on this page are read from the live catalog and cannot drift from what the API accepts. Field notes were captured on 2026-08-28.