# Twitch (/docs/twitch)



Twitch [#twitch]

Twitch streamer profiles, a channel's past 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/...`

Getting Started [#getting-started]

1\. Fetch a profile [#1-fetch-a-profile]

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

Returns display name, follower count, bio, profile image URL, broadcast language, and partner status.

2\. List what they have broadcast [#2-list-what-they-have-broadcast]

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

3\. Read computed fields [#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.

What you can get [#what-you-can-get]

* **`GET /v1/twitch/profile`** — a channel snapshot by `handle`. The right first call before pulling anything else.
* **`GET /v1/twitch/user/videos`** — up to 100 of a channel's videos, each with title, URL, view count, duration in seconds, language, game, thumbnail, and available qualities. `filter_by` picks the kind — `HIGHLIGHT` or `UPLOAD` — and `sort_by` is `TIME` (newest first) or `VIEWS`. Both enums are uppercase.
* **`GET /v1/twitch/user/schedule`** — the channel's published schedule, with each segment's start time, end time, title, categories, and cancellation flags.
* **`GET /v1/twitch/clip`** — one clip by its `url`: title, view count, duration, creator and broadcaster names, the game, thumbnail, and creation time.

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

Two things to plan around [#two-things-to-plan-around]

**`user/videos` returns one fixed set with no further pages.** Up to 100 rows arrive and that is the whole result — there is no cursor and nothing to page. Use `filter_by` and `sort_by` to make those 100 the right 100 rather than expecting to walk a full history. 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.

**`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, and do not branch on the call failing — it succeeds and returns nothing.

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

curl "https://www.socialcrawl.dev/v1/twitch/clip?url=https://www.twitch.tv/ninja/clip/AmazonianEncouragingLyrebirdAllenHuhu" \
  -H "x-api-key: sc_your_api_key_here"
```

Endpoints [#endpoints]

<PlatformEndpoints platform="twitch" />

Notes [#notes]

* All endpoints use `GET` method with query parameters
* Authentication via `x-api-key` header
* Responses follow the unified SocialCrawl schema
* `profile`, `user/videos`, and `user/schedule` take a `handle` (no `@`); `clip` takes the clip `url`
* Nothing on this platform paginates