twitch/
user-videos

The Twitch User Videos API collects one page of public Twitch videos for a username, with optional type and order filters, returning creator context, media, duration, and visible engagement.

Twitch User Videos API

Channel videos
Type filters
Visible engagement
0.19 credits / request
Ready
Ready

Enter parameters and send a request. The task status and normalized results will appear here.

README

By SocQ · Updated

Twitch User Videos

Twitch User Videos are public channel archives, highlights, and uploads with descriptions, creator context, media references, duration, publication time, and visible engagement. These records support channel cataloging, format comparison, publishing research, and point-in-time performance reporting.

Twitch User Videos API Features

  • Username-scoped inventoryThe Twitch User Videos API resolves one public Twitch username into the video records returned for that channel in a single source request.
  • Archive, highlight, and upload filtersSelect all videos or narrow the source request with the accepted archive, highlight, or upload values and their plural aliases.
  • Time or view orderingOrder the returned source page by time or visible views to inspect recent publishing or higher-view video records.
  • Normalized video recordsReturn video identity, public URL, description, creator context, media, duration, publication time, audio metadata, and visible engagement in the ReelVideoItem structure.

Twitch User Videos API Parameters

ParametersRequiredDescription
usernameRequiredOne public Twitch username, optionally beginning with @, using 1 to 64 letters, numbers, dots, underscores, or hyphens.
filter_byOptionalOptional source type: all, archive, archives, highlight, highlights, upload, or uploads. Singular and plural type aliases map to the same provider category.
sort_byOptionalOptional source order: time or views.

How to Use the Twitch User Videos API

Submit a Twitch username to the Twitch User Videos API with optional video-type and sort controls, then read the one source page through the standard asynchronous task flow.

  1. Choose a public Twitch username and decide whether the source page should cover all videos or one accepted video type.
  2. POST username, filter_by, and sort_by to /v1/twitch/user-videos, then save the returned task ID.
  3. Poll /v1/tasks/{task_id} until the task succeeds or fails; do not resubmit after a task ID exists.
  4. Read ReelVideoItem records from results.items and use next_cursor only to page through stored task rows.
curl -X POST "https://api.socq.ai/v1/twitch/user-videos" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username":"ninja","filter_by":"all","sort_by":"time"}'

# Poll GET /v1/tasks/{task_id}
# Read GET /v1/tasks/{task_id}?limit=50

Twitch User Videos API Use Cases

  • Channel video cataloging: Use video IDs, public URLs, descriptions, media references, duration, and creator context to build a current inventory for a known channel.
  • Format mix review: Run accepted type filters through the Twitch User Videos API separately and compare archive, highlight, and upload records by publication time and duration.
  • Publishing and view snapshots: Combine publication timestamps with visible view or playback metrics and collected_at to record a point-in-time channel snapshot.

Twitch User Videos API Pro Tips

  • When supplying a username, remove profile URLs and keep only the optional @ plus the accepted 1 to 64 username characters.
  • Use time to inspect recent publishing and views to inspect higher-view records within the returned source page.
  • Choose either singular or plural type aliases consistently in stored request definitions because each pair maps to the same upstream category.
  • Do not add cursor or results_limit to the submit payload; the provider call returns one page, while task-result cursor only pages rows already stored by SocQ.
  • Deduplicate longitudinal collections by video ID and tolerate nullable text, media, audio, author, timestamp, and metric fields.

Beyond the Twitch User Videos API, use these APIs when you need a different type of public Twitch data.

  • Twitch Profile API — Resolve one public Twitch username into a normalized account record with available identity, biography, imagery, account flags, visible metrics, and collection context.
  • Twitch Clip Downloader API — Fetch one public Twitch clip from its clip URL with title, views, length, creation time, broadcaster profile, and a downloadable MP4 link with thumbnail.

Explore other platforms

Combine Twitch data with public data from other supported social platforms.

Twitch User Videos API — FAQ

Twitch User Videos API is a programmatic interface for collecting one page of public video records from a Twitch username. It returns normalized video identity, description, creator context, media, duration, publication time, audio metadata, and visible engagement.

username is required and accepts an optional @ followed by 1 to 64 letters, numbers, dots, underscores, or hyphens. filter_by accepts all, archive, archives, highlight, highlights, upload, or uploads; sort_by accepts time or views.

Each ReelVideoItem can include an ID, public URL, description, creator details, media, hashtags, mentions, duration, audio metadata, publication time, collection time, and visible likes, comments, shares, plays, or views. Source availability determines which nullable fields contain values.

No. The submit contract performs one source request and accepts neither cursor nor results_limit. After completion, next_cursor can page through result rows already stored for that task, but it does not fetch another source page.

Each successful task uses a fixed 0.19 credits, independent of the number of records returned on the source page.

A successful task can contain no items when the public source page has no eligible records for the selected type and order or when matching videos are unavailable. Treat an empty result separately from a failed task.