Twitch user videos API
A channel's videos (up to 100): id, title, views, game, duration and thumbnails.
GET /v1/twitch/user/videos
GET /v1/twitch/user/videos
A channel's videos (up to 100): id, title, views, game, duration and thumbnails.
- Cost: 1 credit
- Cache: Results are kept up to 30 days; send
max_age_daysto reuse them for free. - Timeout: A request still running after about 25 seconds answers
202with a job to poll (Batch and jobs).
Parameters#
| Name | Type | Required | Description |
|---|---|---|---|
handle | string | yes | Username, with or without the leading @. Also accepted as username. |
type | string | no | Kind of video. One of highlight, archive, upload. Also accepted as filter_by, filter. Also accepted values: HIGHLIGHT for highlight, ARCHIVE for archive, UPLOAD for upload. |
sort | string | no | Order of results. Changing it restarts the cursor chain. One of time, views. Also accepted as sort_by, sortBy, order. Also accepted values: TIME for time, VIEWS for views. |
limit | integer | no | How many videos to return, up to 100 (Twitch allows no paging past the first 100 without a browser session, so the response has no cursor). Range 1 to 100. |
Every request also accepts:
cursor: the cursor from the previous page (Pagination).trim:truefor a smaller response withoutnullfields andextra.raw:trueto also get the platform's original object asraw.max_age_days: accept a cached result up to this many days old, for 0 credits (Caching).
Example request#
Set your key in the environment first (see Authentication).
1curl -G "https://api.socialscrape.dev/v1/twitch/user/videos" \2 -H "x-api-key: $SOCIALSCRAPE_API_KEY" \3 --data-urlencode "handle=shroud" \4 --data-urlencode "type=highlight" \5 --data-urlencode "sort=views" \6 --data-urlencode "limit=10"1import os2import requests34params = {5 "handle": "shroud",6 "type": "highlight",7 "sort": "views",8 "limit": "10",9}10res = requests.get(11 "https://api.socialscrape.dev/v1/twitch/user/videos",12 headers={"x-api-key": os.environ["SOCIALSCRAPE_API_KEY"]},13 params=params,14)15body = res.json()1617if body["ok"]:18 print(body["data"])19else:20 print(body["error"]["code"], body["error"]["message"])1const url = new URL("https://api.socialscrape.dev/v1/twitch/user/videos");2url.search = new URLSearchParams({3 "handle": "shroud",4 "type": "highlight",5 "sort": "views",6 "limit": "10"7}).toString();8const res = await fetch(url, {9 headers: { "x-api-key": process.env.SOCIALSCRAPE_API_KEY! },10});11const body = await res.json();1213if (body.ok) {14 console.log(body.data);15} else {16 console.error(body.error.code, body.error.message);17}1{2 "nodes": [3 {4 "name": "SocialScrape Twitch user videos",5 "type": "n8n-nodes-base.httpRequest",6 "typeVersion": 4.2,7 "position": [8 0,9 010 ],11 "parameters": {12 "method": "GET",13 "url": "https://api.socialscrape.dev/v1/twitch/user/videos",14 "sendQuery": true,15 "queryParameters": {16 "parameters": [17 {18 "name": "handle",19 "value": "shroud"20 },21 {22 "name": "type",23 "value": "highlight"24 },25 {26 "name": "sort",27 "value": "views"28 },29 {30 "name": "limit",31 "value": "10"32 }33 ]34 },35 "sendHeaders": true,36 "headerParameters": {37 "parameters": [38 {39 "name": "x-api-key",40 "value": "={{ $env.SOCIALSCRAPE_API_KEY }}"41 }42 ]43 }44 }45 }46 ],47 "connections": {}48}Example response#
This is a sample from a recorded response, lists and long text are shortened. Status 200.
200 OKSample response
1{2 "ok": true,3 "credits_charged": 1,4 "credits_remaining": 4999,5 "cached": false,6 "cached_at": null,7 "request_id": "req_d60acf6cd59f9e464094749b",8 "data": {9 "object": "list",10 "items": [11 {12 "object": "post",13 "platform": "twitch",14 "id": "1526143078",15 "url": "https://www.twitch.tv/videos/1526143078",16 "type": "video",17 "author": {18 "id": "37402112",19 "handle": "shroud",20 "name": "shroud",21 "url": "https://www.twitch.tv/shroud",22 "avatar_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/c754eebf-745b-4e0a-814a-10bcaecaabbc-profile_image-300x300.png",23 "verified": null24 },25 "title": "Highlight: the grind continues......?",26 "text": null,27 "published_at": "2022-07-08T19:28:43Z",28 "duration_seconds": 2616.0,29 "language": "en",30 "hashtags": null,31 "mentions": null,32 "stats": {33 "views": 37725,34 "likes": null,35 "comments": null,36 "shares": null,37 "saves": null,38 "dislikes": null39 },40 "media": {41 "thumbnail_url": "https://static-cdn.jtvnw.net/cf_vods/d2nvs31859zcd8/a79dbbd4e2da30dfc62a_shroud_14459702619_3278251629//thumb/thumb1526143078-320x180.jpg",42 "video_url": null,43 "audio_url": null,44 "image_urls": null,45 "width": null,46 "height": null47 },48 "song": null,49 "location": null,50 "is_pinned": null,51 "is_sponsored": null,52 "extra": {53 "animated_preview_url": "https://d2nvs31859zcd8.cloudfront.net/a79dbbd4e2da30dfc62a_shroud_14459702619_3278251629/storyboards/1526143078-strip-0.jpg",54 "broadcast_type": "highlight",55 "created_at": "2022-07-08T19:28:43Z",56 "game": "VALORANT",57 "game_id": "516575",58 "status": "recorded"59 }60 },61 {62 "object": "post",63 "platform": "twitch",64 "id": "1995417333",65 "url": "https://www.twitch.tv/videos/1995417333",66 "type": "video",67 "author": {68 "id": "37402112",69 "handle": "shroud",70 "name": "shroud",71 "url": "https://www.twitch.tv/shroud",72 "avatar_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/c754eebf-745b-4e0a-814a-10bcaecaabbc-profile_image-300x300.png",73 "verified": null74 },75 "title": "GTA 6 Trailer",76 "text": null,77 "published_at": "2023-12-04T23:40:23Z",78 "duration_seconds": 806.0,79 "language": "en",80 "hashtags": null,81 "mentions": null,82 "stats": {83 "views": 19254,84 "likes": null,85 "comments": null,86 "shares": null,87 "saves": null,88 "dislikes": null89 },90 "media": {91 "thumbnail_url": "https://static-cdn.jtvnw.net/cf_vods/d2nvs31859zcd8/aa4d47db4f3d6723dd36_shroud_72253881914_5037481556/thumb/custom-c67b8f7c-dff9-4184-a710-dcb008063a72-320x180.png",92 "video_url": null,93 "audio_url": null,94 "image_urls": null,95 "width": null,96 "height": null97 },98 "song": null,99 "location": null,100 "is_pinned": null,101 "is_sponsored": null,102 "extra": {103 "animated_preview_url": "https://d2nvs31859zcd8.cloudfront.net/aa4d47db4f3d6723dd36_shroud_72253881914_5037481556/storyboards/1995417333-strip-0.jpg",104 "broadcast_type": "highlight",105 "created_at": "2023-12-04T23:40:23Z",106 "game": "World of Warcraft",107 "game_id": "18122",108 "status": "recorded"109 }110 }111 ],112 "cursor": null,113 "has_more": false,114 "parent": {115 "object": "profile",116 "platform": "twitch",117 "id": "37402112",118 "handle": "shroud",119 "name": "shroud",120 "headline": null,121 "url": "https://www.twitch.tv/shroud",122 "kind": "channel",123 "bio": null,124 "avatar_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/c754eebf-745b-4e0a-814a-10bcaecaabbc-profile_image-300x300.png",125 "banner_url": null,126 "verified": null,127 "is_private": null,128 "external_url": null,129 "links": null,130 "location": null,131 "category": null,132 "created_at": null,133 "stats": {134 "followers": null,135 "following": null,136 "posts": null,137 "likes": null,138 "views": null139 },140 "extra": null141 }142 },143 "cursor": null,144 "has_more": false145}Response#
A list of Post objects in data.items, with data.cursor and data.has_more.
See Data models for every field. The envelope around data is described in Responses.
Errors#
Failures are free: credits_charged is 0. Branch on error.code, never on the message.
| Code | HTTP | Retry | Meaning |
|---|---|---|---|
invalid_params | 400 | no | A parameter is missing, unknown or has the wrong type. |
not_found | 404 | no | The platform says this profile, post or item does not exist. |
Every request can also fail with the account and platform errors listed on the Errors page.
Related endpoints#
- Twitch channel (
GET /v1/twitch/profile) - Twitch stream schedule (
GET /v1/twitch/user/schedule) - Twitch clip transcript (
GET /v1/twitch/clip/transcript) - Twitch clip (
GET /v1/twitch/clip)