# Twitch API scraper — channel, live stream, VOD, clip, search and directory data: channel profile (id, display name, description, follower count, partner/affiliate status, profile image), live stream status (viewer count, game/category, title, started-at), a streamer's past broadcasts (VODs) and top clips, channel and category/game search, the top live games with viewer counts, and the top live streams site-wide — all from Twitch's public GraphQL, no API key required

> 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.
> ReefAPI engine `twitch` · 13 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/twitch/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /twitch/v1/channel — 1 credit
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.

**Parameters:**
- `login` (string, required) — Twitch channel login name — the handle in twitch.tv/<login> (e.g. 'shroud', 'pokimane', 'xqc'). Case-insensitive.

**Returns:** channel{id, login, display_name, description, created_at, profile_image, banner_image, follower_count, is_partner, is_affiliate, is_live, stream{...}, url}

**Example request body:**
```json
{
  "login": "shroud"
}
```

### POST /twitch/v1/stream — 1 credit
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.

**Parameters:**
- `login` (string, required) — Twitch channel login name — the handle in twitch.tv/<login> (e.g. 'shroud', 'pokimane', 'xqc'). Case-insensitive.

**Returns:** {login, display_name, is_live, stream{id, title, viewer_count, started_at, game{...}, thumbnail}}

**Example request body:**
```json
{
  "login": "shroud"
}
```

### POST /twitch/v1/videos — 1 credit
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.

**Parameters:**
- `login` (string, required) — Twitch channel login name — the handle in twitch.tv/<login> (e.g. 'shroud', 'pokimane', 'xqc'). Case-insensitive.
- `limit` (integer, optional, default 20) — How many VODs to return (1-100, single page).
- `type` (enum, optional, default "ARCHIVE") — Which kind of videos: ARCHIVE (past broadcasts, default), HIGHLIGHT, UPLOAD or ALL. [one of: ARCHIVE, HIGHLIGHT, UPLOAD, ALL]
- `sort` (enum, optional, default "TIME") — Order: TIME (newest first, default) or VIEWS (most viewed). [one of: TIME, VIEWS]

**Returns:** videos[]{id, title, duration_seconds, view_count, published_at, game{...}, thumbnail, url} + meta{has_more}

**Example request body:**
```json
{
  "login": "pokimane",
  "limit": 5
}
```

### POST /twitch/v1/clips — 1 credit
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.

**Parameters:**
- `login` (string, required) — Twitch channel login name — the handle in twitch.tv/<login> (e.g. 'shroud', 'pokimane', 'xqc'). Case-insensitive.
- `limit` (integer, optional, default 20) — How many clips to return (1-100).
- `period` (enum, optional, default "LAST_WEEK") — Time window for top clips: LAST_DAY, LAST_WEEK (default), LAST_MONTH or ALL_TIME. [one of: LAST_DAY, LAST_WEEK, LAST_MONTH, ALL_TIME]

**Returns:** clips[]{id, slug, title, view_count, created_at, duration_seconds, game{...}, clipper, url} + meta{has_more}

**Example request body:**
```json
{
  "login": "xqc",
  "limit": 5,
  "period": "ALL_TIME"
}
```

### POST /twitch/v1/search_channels — 1 credit
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).

**Parameters:**
- `query` (string, required) — Free-text search term.
- `limit` (integer, optional, default 10) — Max channels to return (1-30).

**Returns:** channels[]{id, login, display_name, description, follower_count, is_partner, is_live, viewer_count, game{...}, url}

**Example request body:**
```json
{
  "query": "ninja",
  "limit": 5
}
```

### POST /twitch/v1/search_categories — 1 credit
Search Twitch games/categories by name. Returns matching categories with id, name, display name, current live viewer count and box-art image.

**Parameters:**
- `query` (string, required) — Free-text search term.
- `limit` (integer, optional, default 10) — Max categories to return (1-30).

**Returns:** categories[]{id, name, display_name, viewer_count, box_art, url}

**Example request body:**
```json
{
  "query": "valorant",
  "limit": 5
}
```

### POST /twitch/v1/top_games — 1 credit
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.

**Parameters:**
- `limit` (integer, optional, default 20) — How many top games to return (1-30).

**Returns:** games[]{id, name, display_name, viewer_count, tags[], box_art, url}

**Example request body:**
```json
{
  "limit": 5
}
```

### POST /twitch/v1/top_streams — 1 credit
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.

**Parameters:**
- `limit` (integer, optional, default 20) — How many top streams to return (1-30).

**Returns:** streams[]{id, title, viewer_count, started_at, channel{login, display_name}, game{...}, thumbnail, url}

**Example request body:**
```json
{
  "limit": 5
}
```

### POST /twitch/v1/game — 1 credit
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.

**Parameters:**
- `name` (string, required) — Exact game/category name as Twitch lists it (e.g. 'VALORANT', 'Just Chatting', 'Counter-Strike'). Use search_categories to resolve a fuzzy name first.
- `limit` (integer, optional, default 20) — How many of the game's top live streams to return (1-30).

**Returns:** game{id, name, display_name, viewer_count, description, avatar} + streams[]{id, title, viewer_count, channel{login, display_name}, url}

**Example request body:**
```json
{
  "name": "VALORANT",
  "limit": 5
}
```

### POST /twitch/v1/schedule — 1 credit
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.

**Parameters:**
- `login` (string, required) — Twitch channel login name — the handle in twitch.tv/<login> (e.g. 'shroud', 'pokimane', 'xqc'). Case-insensitive.

**Returns:** {login, display_name, schedule_id, next_segment{start_at, title, categories[]}, segments[]{id, start_at, end_at, title, is_cancelled, categories[]{id, name, box_art}}}

**Example request body:**
```json
{
  "login": "lirik"
}
```

### POST /twitch/v1/game_clips — 1 credit
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.

**Parameters:**
- `name` (string, required) — Exact game/category name as Twitch lists it (e.g. 'VALORANT', 'Just Chatting', 'Counter-Strike'). Use search_categories to resolve a fuzzy name first.
- `limit` (integer, optional, default 20) — How many clips to return (1-100).
- `period` (enum, optional, default "LAST_WEEK") — Time window for top clips: LAST_DAY, LAST_WEEK (default), LAST_MONTH or ALL_TIME. [one of: LAST_DAY, LAST_WEEK, LAST_MONTH, ALL_TIME]

**Returns:** clips[]{id, slug, title, view_count, created_at, duration_seconds, broadcaster{login, display_name}, clipper, game{...}, url} + meta{has_more}

**Example request body:**
```json
{
  "name": "VALORANT",
  "limit": 5,
  "period": "ALL_TIME"
}
```

### POST /twitch/v1/game_videos — 1 credit
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.

**Parameters:**
- `name` (string, required) — Exact game/category name as Twitch lists it (e.g. 'VALORANT', 'Just Chatting', 'Counter-Strike'). Use search_categories to resolve a fuzzy name first.
- `limit` (integer, optional, default 20) — How many VODs to return (1-100).
- `sort` (enum, optional, default "VIEWS") — Order: VIEWS (most viewed, default) or TIME (newest first). [one of: VIEWS, TIME]

**Returns:** videos[]{id, title, duration_seconds, view_count, published_at, owner{login, display_name}, game{...}, thumbnail, url} + meta{has_more}

**Example request body:**
```json
{
  "name": "Just Chatting",
  "limit": 5
}
```

### POST /twitch/v1/team — 1 credit
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).

**Parameters:**
- `name` (string, required) — Twitch team name/slug (lowercase, as in the team page URL twitch.tv/team/<name> — e.g. 'tsm', 'fnatic', 'cloud9').
- `limit` (integer, optional, default 25) — Max member channels to return (1-100).

**Returns:** team{id, name, display_name, description, logo, banner} + members[]{login, display_name, is_partner, is_live, viewer_count, game{...}, url}

**Example request body:**
```json
{
  "name": "tsm",
  "limit": 5
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=twitch
- Human docs page: https://reefapi.com/docs/twitch
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt