Douyin User Videos
This endpoint turns one Douyin creator identity into a single-page set of public video records. Each record can carry its caption, author context, source URL, publication and collection times, media, duration, and visible play, like, comment, share, or view counts when the source provides them.
Features
- Two ways to identify a creatorSubmit a supported Douyin profile URL or a known user_id. If both fields are present, the direct user_id is used.
- Explicit one-page scopeChoose 1 to 20 requested results, with 20 as the default and maximum; the provider request always starts from its first page.
- Video and creator context togetherKeep normalized captions, public author fields, source URLs, timestamps, media references, and duration in each reel-video record.
- Observation-ready engagement fieldsRetain available plays, likes, comments, shares, and views with collected_at so every visible count remains tied to its collection time.
Parameters
| Parameters | Required | Description |
|---|---|---|
url | Required (at least one) | A Douyin profile reference whose hostname is douyin.com, iesdouyin.com, or a subdomain and whose path contains /user/{identifier}. Provide url or user_id; user_id takes precedence when both are present. |
user_id | Required (at least one) | A known user identifier containing 1 to 256 ASCII letters, numbers, colons, underscores, or hyphens. Provide user_id or url. |
results_limit | Optional | The requested number of records from the single provider page. Accepts integers from 1 to 20 and defaults to 20. |
How to Use
Submit one public creator identity, follow the asynchronous task, then read the stored normalized video records.
- Prepare either a Douyin profile URL on douyin.com or iesdouyin.com with a /user/{identifier} path, or a known user_id.
- POST the identity and an optional results_limit from 1 to 20 to /v1/douyin/user-videos, then save task_id.
- Poll /v1/tasks/{task_id} until the task succeeds or fails.
- Read data.results.items; follow next_cursor only for additional records already stored by SocQ, not another provider page.
curl -X POST "https://api.socq.ai/v1/douyin/user-videos" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"'"$DOUYIN_PROFILE_URL"'","results_limit":20}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and use next_cursor only for stored resultsBest Use Cases
- Creator feed snapshots: Save a bounded set of public videos and collection timestamps for one creator at a chosen observation point.
- Video catalog enrichment: Add normalized captions, author identity, source URLs, publication time, duration, and available media to an existing creator record.
- Creative and format review: Inspect returned captions, duration, and media fields to organize the available videos by content treatment or format.
- Within-snapshot engagement comparison: Compare available play, like, comment, share, and view counts across the returned videos while retaining collected_at.
Pro Tips
- Prefer one identity field per request. If url and user_id are both included, the backend selects user_id.
- Validate URL host and /user/{identifier} path before submission; a generic Douyin video URL does not satisfy this endpoint.
- Set results_limit only when fewer than the default 20 records are useful; it must be an integer from 1 through 20.
- Do not treat the task-result cursor as a Douyin source cursor. The source request is one page with its provider cursor fixed at the first page.
- Allow optional author, media, duration, publication time, and individual metrics to remain null or empty, and use id plus collected_at when storing observations.
Related APIs
Use these APIs when you need a different type of public Douyin data.
- Douyin Live Room Detail API — Retrieve one known Douyin live room by numeric room ID with normalized room context, host identity, media, and visible audience counts.
- Douyin User Profile API
- Douyin Video Comments API
- Douyin Video Detail API
- Douyin Video Search API