# Twitch (/docs/twitch)

Twitch streamer profiles, past videos, clip details, and published stream schedules through one unified API

Twitch streamer profiles, a channel's videos and highlights, individual clip details, and the schedule a streamer has published. Every endpoint is a `GET` and costs 1 credit.

Base URL: `/v1/twitch/...`

  `user/videos` returns one fixed set of up to 100 rows and that is the whole
  result. There is no cursor and nothing to page, so use `filter_by` and
  `sort_by` to make those 100 the right 100 rather than expecting to walk a full
  history.

## Quickstart

### 1. Fetch a profile

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/twitch/profile?handle=ninja" \
  -H "x-api-key: YOUR_API_KEY"
```

### 2. Fetch their content

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/twitch/user/videos?handle=ninja&sort_by=VIEWS" \
  -H "x-api-key: YOUR_API_KEY"
```

### 3. Read computed fields

When an endpoint supports a computed field and the required source inputs are present, the unified response includes that optional field. Depending on the endpoint, optional fields can include `engagement_rate`, `language`, `content_category`, and `estimated_reach`. See [Computed fields](/docs/computed-fields.md) for formulas, clamping rules, and null semantics.

## Channels

| Endpoint                       | Credits | What it returns                                                                          | Key parameters                   |
| ------------------------------ | ------- | ---------------------------------------------------------------------------------------- | -------------------------------- |
| `GET /v1/twitch/profile`       | 1       | Display name, follower count, bio, profile image, broadcast language, partner status     | `handle`                         |
| `GET /v1/twitch/user/videos`   | 1       | Up to 100 videos: title, URL, view count, duration, language, game, thumbnail, qualities | `handle`, `filter_by`, `sort_by` |
| `GET /v1/twitch/user/schedule` | 1       | Each schedule segment's start and end time, title, categories, and cancellation flags    | `handle`                         |

`filter_by` picks the kind, `HIGHLIGHT` or `UPLOAD`, and `sort_by` is `TIME` for newest first or `VIEWS`. Both enums are uppercase.

Archived past broadcasts are not among them. `filter_by=ARCHIVE` is rejected before billing because the upstream deterministically fails it, so `HIGHLIGHT` and `UPLOAD` are what exists.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/twitch/user/schedule?handle=kaicenat" \
  -H "x-api-key: YOUR_API_KEY"
```

## Clips

| Endpoint              | Credits | What it returns                                                                            | Key parameters |
| --------------------- | ------- | ------------------------------------------------------------------------------------------ | -------------- |
| `GET /v1/twitch/clip` | 1       | Title, view count, duration, creator and broadcaster names, game, thumbnail, creation time | `url`          |

`user/videos` covers past broadcasts, `clip` covers one shared moment, and `user/schedule` covers what has not happened yet.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/twitch/clip?url=https://www.twitch.tv/ninja/clip/ExampleClipSlug" \
  -H "x-api-key: YOUR_API_KEY"
```

## All endpoints

## Platform notes

**`channel.schedule` is `null` when the streamer has not published one.** Plenty of channels never fill it in, so treat a null schedule as normal rather than as an error. The call succeeds and returns nothing; do not branch on it failing.

**Nothing on this platform paginates.**

**Identifiers split two ways.** `profile`, `user/videos`, and `user/schedule` take a `handle` without the `@`; `clip` takes the clip `url`.

## Next steps

- [Pagination](/docs/pagination.md): Cursor and page walks, and what has_more actually means.
- [Credits](/docs/credits.md): What each tier costs and when a call is refunded.
- [API reference](/docs/api-reference.md): Every parameter and response field, endpoint by endpoint.
- [Kick](/docs/kick.md): The other live-streaming surface, clips only.
- [Rumble](/docs/rumble.md): Video, comments, transcripts, and keyword search.