Clips are the short highlights viewers cut from a Twitch stream, and they are what gets shared on X, Reddit and Discord. If you archive standout moments, measure how far a clip traveled or need to credit the right channel when reposting, you need the clip's data and its video file in a form your code can store.
On 2026-11-17 SocQ added the Twitch Clip Downloader API to the Twitch platform page, next to the existing Twitch Profile and User Videos endpoints. This guide covers what it returns, the request, the price and the limits you should plan for.
Quick answer: Send
{"url": "<clip URL>"}toPOST https://api.socq.ai/v1/twitch/clip. Save the returnedtask_id, pollGET /v1/tasks/{task_id}untilstatusissucceeded, then read the single record indata.results.items. Each request costs 0.5 credits ($0.0025). Download the video file soon, because its link expires after about a day.
What the Endpoint Returns
1 SocQ credit = $0.005.
| Endpoint | What it returns | Price |
|---|---|---|
| Twitch Clip Downloader API | One clip: title, view count, length, creation time, broadcaster with avatar, video file and thumbnail | 0.5 credits ($0.0025) per call |
The record uses SocQ's standard video schema. The fields that matter for clips:
| Field | Meaning |
|---|---|
id | Twitch's numeric clip ID |
shortcode | The clip slug from the URL |
url | The clip URL |
text | The clip title |
published_at | When the clip was created (ISO 8601) |
duration_seconds | Clip length in seconds |
metrics.views_count | Clip views |
author | The broadcaster: id, username, name, url, avatar_url, is_verified |
media[0].url | The clip's MP4 file |
media[0].thumbnail_url | The clip thumbnail |
collected_at | When SocQ collected the record |
Declared fields stay in the record even when they have no value. In the docs example, a 27-second clip returns views_count: 69776, while metrics.likes_count, metrics.comments_count, hashtags and audio are null.
Authentication and the Async Task Flow
All requests authenticate with an API key. The same header is used for submit, task status and result requests:
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Every collection runs as a background task:
submit -> task_id -> queued -> running -> succeeded
\-> failed
The submit call returns immediately with data.task_id and data.status. Poll the task with that ID:
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=50" \
-H "Authorization: Bearer $SOCQ_API_KEY"
When status is succeeded, the response includes result_count, credits_amount and the record in data.results.items. A failed task carries error_message. A client-side timeout does not cancel a task, so resume with the same task ID instead of submitting again. A 402 means the account is out of credits, and a 429 means the key hit a rate or credit limit.
Unlike most SocQ endpoints, the Clip Downloader request body takes only url; it does not list callback_url, so poll the task instead.
Request a Clip
Pass one clip URL in url. Both forms work: twitch.tv/<channel>/clip/<slug> and clips.twitch.tv/<slug>. (docs)
curl -X POST "https://api.socq.ai/v1/twitch/clip" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://www.twitch.tv/staryuuki/clip/CloudySavageMarjoramRuleFive--ErzsYbE7UWvgCMQ"}'
Each request takes one URL and returns one row. For a batch, submit one task per clip and keep each task_id next to its URL so a retry does not submit the same clip twice.
Download the Video Before the Link Expires
The media[0].url link is signed and expires after about a day. If you need a copy of the clip, download it as soon as the task succeeds and store the file in your own storage. Keep the record's id, shortcode and url with the file, so you can request the clip again if you ever need the source link.
A minimal Python flow:
import os, time, requests
API = "https://api.socq.ai"
headers = {"Authorization": f"Bearer {os.environ['SOCQ_API_KEY']}"}
clip_url = "https://clips.twitch.tv/CloudySavageMarjoramRuleFive--ErzsYbE7UWvgCMQ"
task = requests.post(f"{API}/v1/twitch/clip", headers=headers,
json={"url": clip_url}).json()["data"]
while task["status"] in ("queued", "running"):
time.sleep(3)
task = requests.get(f"{API}/v1/tasks/{task['task_id']}",
headers=headers).json()["data"]
if task["status"] != "succeeded":
raise RuntimeError(task.get("error_message"))
clip = task["results"]["items"][0]
video = requests.get(clip["media"][0]["url"], timeout=60)
with open(f"{clip['shortcode']}.mp4", "wb") as f:
f.write(video.content)
Add HTTP status checks, bounded retries and logging before you run it at scale.
When to Use It
- Highlight archives. Save the clips your channel or your talent produce, with title, creation time and views, before the source link changes.
- Reach tracking. Re-run a clip after it has been shared and compare
metrics.views_countwith the first snapshot. Each check costs 0.5 credits. - Attribution.
authornames the broadcaster who streamed the moment, with a profile link, so reposts can credit the right channel. - Content pipelines. Feed the MP4 into editing, captioning or short-form repurposing.
Cost planning: the price is flat, so 100 clips cost 50 credits ($0.25) and 1,000 clips cost 500 credits ($2.50). A weekly views check on 50 tracked clips costs 25 credits ($0.125) per week.
Respect the rights of the broadcaster and of anyone who appears in a clip, and follow Twitch's terms when you reuse the video.
Related Twitch Endpoints
The clip record tells you who streamed it. To go from there to the channel:
- Twitch Profile API returns a public Twitch profile from a
username. - Twitch User Videos API returns one page of a user's public videos, with
filter_by(such asarchive,highlightorupload) andsort_by(timeorviews).
Pass author.username from a clip to either one. For clips and videos from other platforms in the same normalized shape, see the TikTok scraping guide and 7 Best YouTube Scraper APIs.
FAQ
How much does the Twitch Clip Downloader API cost?
0.5 credits per request, which is $0.0025. Each request returns one clip.
Which clip URL formats are accepted?
https://www.twitch.tv/<channel>/clip/<slug> and https://clips.twitch.tv/<slug>.
How long does the video link last?
The link is signed and expires after about a day. Download the file promptly if you need a copy.
Can I send several clips in one request?
No. url takes one clip URL. Submit one task per clip.
Does it return likes or comments for a clip?
The record carries the view count. In the docs example, likes_count and comments_count are null, so do not plan on them.
TWITCH API
Test the workflow with a public Twitch URL
Submit public inputs and receive normalized records with traceable source context.
Explore Twitch APIs