Live streaming API

Twitch

Private · profile challenged

Retrieve Twitch profiles, video pages, weekly schedules and complete public clips.

Four authenticated endpoints with full source records and bounded retrieval. Videos, schedules and clips passed live acceptance on the deployment host. Profile retrieval is currently challenged by Twitch on this host and returns an explicit failure.

Base URLhttp://localhost:3012

Local development example. Replace with your service origin.

Get a Twitch profile

GET/v1/twitch/profile

Retrieve profile identity, biography, social links, followers, partner status, current stream, videos, home-page video shelves and similar streamers. Social names become lowercase top-level keys. Deployment-host acceptance is currently blocked by an integrity challenge on social links. The worker returns HTTP 502 / upstream_challenged without a reduced profile.

Query parameters

Field	Type	Description
handle	string	Required Twitch login, 1–25 letters, digits or underscores. Normalized to lowercase.

Request cURL

export BASE_URL="http://localhost:3012"
export API_KEY="your-service-key"

curl --get "$BASE_URL/v1/twitch/profile" \
  -H "x-api-key: $API_KEY" \
  --data-urlencode "handle=example"

Response fields

Field	Type	Description
id	string	Always included.
isLive	boolean	Always included.
currentViewersCount	integer \| null	Current stream viewers; null when offline.
stream	object	Current live stream object, or {} when offline.
handle	string	Required Twitch login, 1–25 letters, digits or underscores. Normalized to lowercase.
displayName	string	Always included.
profileImageURL	string \| null	Profile image at the reference size of 150 pixels.
bannerImageURL	string \| null	Source banner URL, or null.
description	string \| null	Always included.
followers	integer	Current follower count; it can change between requests.
isPartner	boolean	Published Twitch partner flag.
allVideos	array	Up to 12 latest videos, with full owner/game, restrictions, tags and logged-out self metadata.
recentBroadcasts	array	Present when Twitch supplies a nonempty latest-broadcasts shelf. Preserves its source records; this field can be absent from the reference service even when Twitch supplies it.
featuredClips	array	Public top-clips shelf, including isFeatured on each item, creator, broadcaster, game and guest participants. Omitted when no populated shelf is supplied.
similarStreamers	array	Up to 15 public recommendations; an empty source shelf yields an empty array.
requestId	string	Operation identifier for correlation.
accounting	object	Upstream HTTP attempts, total decoded bytes, and elapsed milliseconds.
success	boolean	True when the primary requested data is usable.
status	string	success, partial, failed or challenged. Inspect coverage on HTTP 200.
sourceUrl	string	Canonical public Twitch page URL.
fetchedAt	string	UTC retrieval timestamp.
coverage	object	Public GraphQL coverage. Clip auxiliary query errors produce partial with auxiliary_graphql_error; missing required primary fields fail.

Nested fields and every response variant are in the OpenAPI specification.

Response 200 · synthetic example

{
  "id": "1",
  "isLive": false,
  "currentViewersCount": null,
  "stream": {},
  "handle": "example",
  "displayName": "Example",
  "profileImageURL": "https://example.test/avatar",
  "bannerImageURL": null,
  "description": "Synthetic profile",
  "followers": 0,
  "isPartner": false,
  "allVideos": [
    {
      "id": "3",
      "animatedPreviewURL": null,
      "lengthSeconds": 12,
      "game": {
        "id": "2",
        "slug": "example",
        "name": "Example",
        "displayName": "Example",
        "boxArtURL": "https://example.test/game",
        "__typename": "Game"
      },
      "owner": {
        "id": "1",
        "login": "example",
        "displayName": "Example",
        "profileImageURL": "https://example.test/avatar",
        "primaryColorHex": null,
        "roles": {
          "isPartner": false,
          "__typename": "UserRoles"
        },
        "__typename": "User"
      },
      "previewThumbnailURL": "https://example.test/thumb",
      "publishedAt": "2026-09-10T00:00:00Z",
      "title": "Synthetic video",
      "viewCount": 0,
      "contentTags": [],
      "resourceRestriction": null,
      "self": {
        "isRestricted": false,
        "viewingHistory": null,
        "__typename": "VideoSelfEdge"
      },
      "__typename": "Video"
    }
  ],
  "recentBroadcasts": [
    {
      "id": "3",
      "animatedPreviewURL": null,
      "lengthSeconds": 12,
      "game": {
        "id": "2",
        "slug": "example",
        "name": "Example",
        "displayName": "Example",
        "boxArtURL": "https://example.test/game",
        "__typename": "Game"
      },
      "owner": {
        "id": "1",
        "login": "example",
        "displayName": "Example",
        "profileImageURL": "https://example.test/avatar",
        "primaryColorHex": null,
        "roles": {
          "isPartner": false,
          "__typename": "UserRoles"
        },
        "__typename": "User"
      },
      "previewThumbnailURL": "https://example.test/thumb",
      "publishedAt": "2026-09-10T00:00:00Z",
      "title": "Synthetic video",
      "viewCount": 0,
      "contentTags": [],
      "resourceRestriction": null,
      "self": {
        "isRestricted": false,
        "viewingHistory": null,
        "__typename": "VideoSelfEdge"
      },
      "__typename": "Video"
    }
  ],
  "featuredClips": [
    {
      "id": "4",
      "slug": "SyntheticClip",
      "clipTitle": "Synthetic clip",
      "clipViewCount": 0,
      "curator": {
        "id": "5",
        "login": "creator",
        "displayName": "Creator",
        "__typename": "User"
      },
      "clipGame": {
        "id": "2",
        "slug": "example",
        "name": "Example",
        "displayName": "Example",
        "boxArtURL": "https://example.test/game",
        "__typename": "Game"
      },
      "broadcaster": {
        "id": "1",
        "login": "example",
        "displayName": "Example",
        "profileImageURL": "https://example.test/avatar",
        "primaryColorHex": null,
        "roles": {
          "isPartner": false,
          "__typename": "UserRoles"
        },
        "__typename": "User"
      },
      "thumbnailURL": "https://example.test/thumb",
      "createdAt": "2026-09-10T00:00:00Z",
      "durationSeconds": 12,
      "isFeatured": true,
      "guestStarParticipants": null,
      "__typename": "Clip"
    }
  ],
  "similarStreamers": [],
  "youtube": "https://youtube.com/example",
  "success": true,
  "status": "success",
  "requestId": "00000000-0000-4000-8000-000000000099",
  "sourceUrl": "https://www.twitch.tv/example",
  "fetchedAt": "2026-09-10T00:00:00.000Z",
  "coverage": {
    "source": "public_graphql",
    "complete": true,
    "warnings": []
  },
  "accounting": {
    "upstreamRequests": 2,
    "responseBytes": 4000,
    "durationMs": 500
  }
}

Get user videos

GET/v1/twitch/user/videos

Retrieve the first page of up to 100 videos, with optional type and sort filters. Source hasNextPage and cursor metadata are returned for compatibility; continuation requests are not supported because the logged-out source rejects them with an integrity challenge.

Query parameters

Field	Type	Description
handle	string	Required Twitch login, 1–25 letters, digits or underscores. Normalized to lowercase.
filter_by	string	Optional HIGHLIGHT, ARCHIVE or UPLOAD. Omit to include all source video types.
sort_by	string	TIME (default) or VIEWS.

Request cURL

export BASE_URL="http://localhost:3012"
export API_KEY="your-service-key"

curl --get "$BASE_URL/v1/twitch/user/videos" \
  -H "x-api-key: $API_KEY" \
  --data-urlencode "handle=example" \
  --data-urlencode "filter_by=ARCHIVE" \
  --data-urlencode "sort_by=TIME"

Response fields

Field	Type	Description
videos	array	Complete video records with game, owner, broadcast identifier, media previews, tags, timestamps, duration and views. Empty when there are no results.
hasNextPage	boolean	Whether Twitch indicates more records exist. The current worker retrieves only the first page.
cursor	string \| null	Last source edge cursor, or null. Returned as metadata only; this endpoint does not accept a continuation cursor.
requestId	string	Operation identifier for correlation.
accounting	object	Upstream HTTP attempts, total decoded bytes, and elapsed milliseconds.
success	boolean	True when the primary requested data is usable.
status	string	success, partial, failed or challenged. Inspect coverage on HTTP 200.
sourceUrl	string	Canonical public Twitch page URL.
fetchedAt	string	UTC retrieval timestamp.
coverage	object	Public GraphQL coverage. Clip auxiliary query errors produce partial with auxiliary_graphql_error; missing required primary fields fail.

Nested fields and every response variant are in the OpenAPI specification.

Response 200 · synthetic example

{
  "videos": [
    {
      "id": "3",
      "animatedPreviewURL": null,
      "lengthSeconds": 12,
      "game": {
        "id": "2",
        "slug": "example",
        "name": "Example",
        "displayName": "Example",
        "boxArtURL": "https://example.test/game",
        "__typename": "Game"
      },
      "owner": {
        "id": "1",
        "login": "example",
        "displayName": "Example",
        "profileImageURL": "https://example.test/avatar",
        "primaryColorHex": null,
        "roles": {
          "isPartner": false,
          "__typename": "UserRoles"
        },
        "__typename": "User"
      },
      "previewThumbnailURL": "https://example.test/thumb",
      "publishedAt": "2026-09-10T00:00:00Z",
      "title": "Synthetic video",
      "viewCount": 0,
      "contentTags": [],
      "broadcastIdentifier": {
        "id": "6",
        "__typename": "Broadcast"
      }
    }
  ],
  "hasNextPage": true,
  "cursor": "synthetic_cursor",
  "success": true,
  "status": "success",
  "requestId": "00000000-0000-4000-8000-000000000099",
  "sourceUrl": "https://www.twitch.tv/example/videos",
  "fetchedAt": "2026-09-10T00:00:00.000Z",
  "coverage": {
    "source": "public_graphql",
    "complete": true,
    "warnings": []
  },
  "accounting": {
    "upstreamRequests": 2,
    "responseBytes": 4000,
    "durationMs": 500
  }
}

Get user schedule

GET/v1/twitch/user/schedule

Retrieve the current calendar week, Monday 00:00 UTC through the next Monday. Includes schedule segments, cancellation metadata, interruption, next segment, current stream and this week’s recent broadcasts.

Query parameters

Field	Type	Description
handle	string	Required Twitch login, 1–25 letters, digits or underscores. Normalized to lowercase.

Request cURL

export BASE_URL="http://localhost:3012"
export API_KEY="your-service-key"

curl --get "$BASE_URL/v1/twitch/user/schedule" \
  -H "x-api-key: $API_KEY" \
  --data-urlencode "handle=example"

Response fields

Field	Type	Description
id	string	Always included.
primaryColorHex	string \| null	Always included.
lastBroadcast	object \| null	Source last-broadcast metadata or null.
broadcastSettings	object	Published channel broadcast title and ID.
stream	JSON	Live metadata including both preview orientations, dimensions and game, or null.
videos	object	Up to 30 archive videos within the current UTC week, preserving edges and source type names.
channel	object	Source channel ID and schedule, including segments, nextSegment and interruption. Schedule can be null.
__typename	string	Always included.
requestId	string	Operation identifier for correlation.
accounting	object	Upstream HTTP attempts, total decoded bytes, and elapsed milliseconds.
success	boolean	True when the primary requested data is usable.
status	string	success, partial, failed or challenged. Inspect coverage on HTTP 200.
sourceUrl	string	Canonical public Twitch page URL.
fetchedAt	string	UTC retrieval timestamp.
coverage	object	Public GraphQL coverage. Clip auxiliary query errors produce partial with auxiliary_graphql_error; missing required primary fields fail.

Nested fields and every response variant are in the OpenAPI specification.

Response 200 · synthetic example

{
  "id": "1",
  "primaryColorHex": null,
  "lastBroadcast": {
    "id": "6",
    "startedAt": "2026-09-09T00:00:00Z",
    "__typename": "Broadcast"
  },
  "broadcastSettings": {
    "id": "1",
    "title": "Synthetic broadcast",
    "__typename": "BroadcastSettings"
  },
  "stream": null,
  "videos": {
    "edges": [],
    "__typename": "VideoConnection"
  },
  "channel": {
    "id": "1",
    "schedule": {
      "id": "schedule",
      "nextSegment": null,
      "interruption": null,
      "segments": [],
      "__typename": "Schedule"
    },
    "__typename": "Channel"
  },
  "__typename": "User",
  "success": true,
  "status": "success",
  "requestId": "00000000-0000-4000-8000-000000000099",
  "sourceUrl": "https://www.twitch.tv/example/schedule",
  "fetchedAt": "2026-09-10T00:00:00.000Z",
  "coverage": {
    "source": "public_graphql",
    "complete": true,
    "warnings": []
  },
  "accounting": {
    "upstreamRequests": 2,
    "responseBytes": 4000,
    "durationMs": 500
  }
}

Get a Twitch clip

GET/v1/twitch/clip

Retrieve the complete public clip and playback metadata. Numeric keys preserve the reference API’s GraphQL batch response: 0 is the clip, 1 related clips, and 2 logged-out viewer data.

Query parameters

Field	Type	Description
url	string	Required HTTPS clips.twitch.tv/<slug> or twitch.tv/<channel>/clip/<slug>. Tracking queries/fragments are removed; credentials, ports and embedded URLs are rejected.

Request cURL

export BASE_URL="http://localhost:3012"
export API_KEY="your-service-key"

curl --get "$BASE_URL/v1/twitch/clip" \
  -H "x-api-key: $API_KEY" \
  --data-urlencode "url=https://clips.twitch.tv/SyntheticClip"

Response fields

Field	Type	Description
0	object	Primary GraphQL response at 0.data.clip, including extensions and videoURL.
1	object	Related-clips GraphQL response. Source errors are retained and produce partial coverage. A working source query returns data even if the reference service has a stale-query error.
2	object	Logged-out viewer response; data.user is null. No Twitch account session is used.
requestId	string	Operation identifier for correlation.
accounting	object	Upstream HTTP attempts, total decoded bytes, and elapsed milliseconds.
success	boolean	True when the primary requested data is usable.
status	string	success, partial, failed or challenged. Inspect coverage on HTTP 200.
sourceUrl	string	Canonical public Twitch page URL.
fetchedAt	string	UTC retrieval timestamp.
coverage	object	Public GraphQL coverage. Clip auxiliary query errors produce partial with auxiliary_graphql_error; missing required primary fields fail.

Clip fields · 0.data.clip

Field	Type	Description
id	string	Public clip ID.
slug	string	Clip slug verified against the requested URL.
url	string	Always included.
embedURL	string	Always included.
title	string	Always included.
viewCount	integer	Current source views, compared strictly during acceptance.
language	string	Always included.
isFeatured	boolean	Always included.
assets	array	All selected source assets, render states, thumbnail URLs, quality variants and portrait metadata.
curator	object \| null	Public clip creator, or null.
game	object \| null	Public game metadata, or null.
broadcast	object \| null	Associated broadcast ID and title, or null.
broadcaster	object	Owner profile, partner flag, follower total, stream, last broadcast and logged-out self metadata.
thumbnailURL	string	Always included.
createdAt	string	Always included.
isPublished	boolean	Must be true for successful retrieval.
durationSeconds	number	Clip duration in seconds.
champBadge	JSON	Source badge metadata or null.
playbackAccessToken	object	Expiring public playback signature and JSON value returned by Twitch. They vary by request and are not logged or cached.
video	JSON	Associated video ID/type/title, or null.
videoOffsetSeconds	number \| null	Source video offset or null.
videoQualities	array	Published source media URLs; never downloaded by this worker.
isViewerEditRestricted	boolean	Logged-out edit restriction flag. It does not imply that public viewing is restricted.
suggestedCropping	JSON	Source crop metadata or null.
__typename	string	Original GraphQL source type.
videoURL	string	First video-quality source URL signed with the current public playback signature/token. Expires with that token; request a fresh clip response when needed.

Nested fields and every response variant are in the OpenAPI specification.

Response 200 · synthetic example

{
  "0": {
    "data": {
      "clip": {
        "id": "4",
        "slug": "SyntheticClip",
        "url": "https://clips.twitch.tv/SyntheticClip",
        "embedURL": "https://clips.twitch.tv/embed?clip=SyntheticClip",
        "title": "Synthetic clip",
        "viewCount": 0,
        "language": "EN",
        "isFeatured": true,
        "assets": [],
        "curator": {
          "id": "1",
          "login": "example",
          "displayName": "Example",
          "profileImageURL": "https://example.test/avatar",
          "primaryColorHex": null,
          "roles": {
            "isPartner": false,
            "__typename": "UserRoles"
          },
          "__typename": "User"
        },
        "game": {
          "id": "2",
          "slug": "example",
          "name": "Example",
          "displayName": "Example",
          "boxArtURL": "https://example.test/game",
          "__typename": "Game"
        },
        "broadcast": {
          "id": "6",
          "title": null,
          "__typename": "Broadcast"
        },
        "broadcaster": {
          "id": "1",
          "login": "example",
          "displayName": "Example",
          "profileImageURL": "https://example.test/avatar",
          "primaryColorHex": null,
          "roles": {
            "isPartner": false,
            "__typename": "UserRoles"
          },
          "__typename": "User",
          "isPartner": false,
          "followers": {
            "totalCount": 0,
            "__typename": "FollowerConnection"
          },
          "stream": null,
          "lastBroadcast": null,
          "self": null
        },
        "thumbnailURL": "https://example.test/thumb",
        "createdAt": "2026-09-10T00:00:00Z",
        "isPublished": true,
        "durationSeconds": 12,
        "champBadge": null,
        "playbackAccessToken": {
          "signature": "synthetic-signature",
          "value": "{\"authorization\": {\"forbidden\": false}, \"expires\": 4102444800, \"clip_slug\": \"SyntheticClip\", \"user_id\": null}",
          "__typename": "PlaybackAccessToken"
        },
        "video": null,
        "videoOffsetSeconds": null,
        "videoQualities": [
          {
            "sourceURL": "https://clips-media-assets2.twitch.tv/example.mp4",
            "__typename": "ClipVideoQuality"
          }
        ],
        "isViewerEditRestricted": true,
        "suggestedCropping": null,
        "__typename": "Clip",
        "videoURL": "https://clips-media-assets2.twitch.tv/example.mp4?sig=synthetic-signature&token=%7B%22authorization%22%3A%20%7B%22forbidden%22%3A%20false%7D%2C%20%22expires%22%3A%204102444800%2C%20%22clip_slug%22%3A%20%22SyntheticClip%22%2C%20%22user_id%22%3A%20null%7D"
      }
    },
    "extensions": {
      "operationName": "ShareClipRenderStatus",
      "durationMilliseconds": 1,
      "requestID": "synthetic-upstream"
    }
  },
  "1": {
    "data": {
      "user": {
        "id": "1",
        "login": "example",
        "clips": {
          "edges": [],
          "pageInfo": {
            "hasNextPage": false,
            "__typename": "PageInfo"
          },
          "__typename": "ClipConnection"
        },
        "__typename": "User"
      }
    },
    "extensions": {
      "operationName": "ClipsCards__User",
      "durationMilliseconds": 1,
      "requestID": "synthetic-related"
    }
  },
  "2": {
    "data": {
      "user": null
    },
    "extensions": {
      "operationName": "GetDisplayName",
      "durationMilliseconds": 1,
      "requestID": "synthetic-upstream"
    }
  },
  "success": true,
  "status": "success",
  "requestId": "00000000-0000-4000-8000-000000000099",
  "sourceUrl": "https://clips.twitch.tv/SyntheticClip",
  "fetchedAt": "2026-09-10T00:00:00.000Z",
  "coverage": {
    "source": "public_graphql",
    "complete": true,
    "warnings": []
  },
  "accounting": {
    "upstreamRequests": 3,
    "responseBytes": 4000,
    "durationMs": 500
  }
}

Coverage & limits

One handle or clip per request; four concurrent operations per worker. No automatic pagination, media download or outbound-link crawling.
20-second total deadline, four upstream HTTP attempts maximum, with one shared transient network/5xx retry. Challenges, redirects, rate limits and GraphQL errors are not retried.
4 MiB combined decoded bytes, depth 24 and 30,000 examined JSON nodes. Incomplete required primary fields, mismatched identities and exceeded bounds fail explicitly.
Profile: 12 latest videos, up to 10 source shelves with 100 items each, and 15 similar streamers. Videos: 100 items per page. Schedule: current UTC week, up to 100 segments and 30 archives. Clip: up to 20 related clips.
Uses Twitch’s public website client identifier and logged-out GraphQL queries. No account credentials, Authorization headers, cookies, private sessions or login flows. Denied/unpublished clips and expired playback tokens fail explicitly.
The public client identifier is discovered from Twitch’s homepage and cached in memory for 15 minutes. No profile, video, schedule or clip response cache; cache_max_age is unsupported.
Nested source fields, nulls, array order and GraphQL type names are preserved. Clip batch extensions retain operational telemetry; only durationMilliseconds and requestID are excluded from parity comparison.
Live counters, playback signatures and playback expiry timestamps can differ between simultaneous requests. They remain in the strict comparison; a difference never counts as exact parity.
Live comparisons: two video pages and two schedules matched exactly. Both profiles contained every matching reference field plus a recent-broadcasts shelf. Both clips contained every primary reference field; only per-request playback values and the reference’s failed related query differed. Strict full-response parity remains false for profiles and clips.
Video history is limited to the first page. A bounded native cursor-continuation read returned failed integrity check. No integrity token, login, or bypass was attempted; cursor input is rejected rather than advertised as working.
Deployed privately in Coolify. Server acceptance passed videos, schedules and primary clip fields; profile socialMedias returned IntegrityCheckFailed. Public About-page HTML contains no replacement social data. All primary fields remain required; profile availability on this host is not accepted.

Errors & partial results

HTTP	Code / status	Meaning
200	partial	Primary clip data is usable but a related-clips or viewer GraphQL query returned source errors.
400	invalid_request	Missing or unsafe input, unknown parameters, invalid filter/sort, or duplicate parameters.
401	unauthorized	Missing or invalid dedicated worker API key.
403	restricted_page	Unpublished clip, denied or expired playback token, or unexpected authenticated viewer.
404	not_found	The requested user/clip is missing or the route is unknown.
429	upstream_rate_limited	Twitch rate limited retrieval.
502	upstream_challenged / public_client_unavailable	Twitch challenged the request or its public client identifier could not be determined.
502	upstream_graphql_error / unsupported_page	Primary query failure or incomplete, unexpected or mismatched data.
502	response_too_large / payload_too_complex	Byte, depth or JSON node limit exceeded.
502	unsafe_redirect / request_limit / upstream_error	Bounded transport could not complete.
503	busy	All worker admission slots are occupied.
504	timeout	The total request deadline expired.