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.
Features
- Username-scoped inventoryResolve 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.
Parameters
| Parameters | Required | Description |
|---|---|---|
username | Required | One public Twitch username, optionally beginning with @, using 1 to 64 letters, numbers, dots, underscores, or hyphens. |
filter_by | Optional | Optional source type: all, archive, archives, highlight, highlights, upload, or uploads. Singular and plural type aliases map to the same provider category. |
sort_by | Optional | Optional source order: time or views. |
How to Use
Submit a Twitch username with optional video-type and sort controls, then read the one source page through the standard asynchronous task flow.
- Choose a public Twitch username and decide whether the source page should cover all videos or one accepted video type.
- POST username, filter_by, and sort_by to /v1/twitch/user-videos, then save the returned task ID.
- Poll /v1/tasks/{task_id} until the task succeeds or fails; do not resubmit after a task ID exists.
- 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=50Best 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 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.
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.
Related APIs
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.