douyin/
user-videos

The Douyin User Videos API collects up to 20 public videos from one Douyin profile URL or known user ID, returning normalized content, author, media, duration, timestamps, and visible engagement fields.

Douyin User Videos API

Profile URL or user ID
Up to 20 videos
Normalized reel-video records
0.1 credits / request
Ready
Ready

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

README

By SocQ · Updated

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.

Douyin User Videos API 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 per Douyin User Videos API task, 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.

Douyin User Videos API Parameters

ParametersRequiredDescription
urlRequired (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_idRequired (at least one)A known user identifier containing 1 to 256 ASCII letters, numbers, colons, underscores, or hyphens. Provide user_id or url.
results_limitOptionalThe requested number of records from the single provider page. Accepts integers from 1 to 20 and defaults to 20.

How to Use the Douyin User Videos API

Submit one public creator identity to the Douyin User Videos API, follow the asynchronous task, then read the stored normalized video records.

  1. Prepare either a Douyin profile URL on douyin.com or iesdouyin.com with a /user/{identifier} path, or a known user_id.
  2. POST the identity and an optional results_limit from 1 to 20 to /v1/douyin/user-videos, then save task_id.
  3. Poll /v1/tasks/{task_id} until the task succeeds or fails.
  4. 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 results

Douyin User Videos API Use Cases

  • Creator feed snapshots: Use the Douyin User Videos API to 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.

Douyin User Videos API Pro Tips

  • Prefer one identity field per Douyin User Videos API 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.

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

Explore other platforms

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

Douyin User Videos API — FAQ

Douyin User Videos API returns normalized public video records for one creator, including identity, caption, author context, source URL, timestamps, media, duration, and visible engagement fields when available.

Either field satisfies the input requirement. A URL must use a supported Douyin host and contain /user/{identifier}; a known user_id can be supplied directly and wins if both fields are present.

It controls the requested record count for the one provider page. The value must be an integer from 1 to 20 and defaults to 20.

A result can include plays, likes, comments, shares, and views. Each field is optional, so unavailable source values remain null instead of being inferred.

No. The provider request uses its first page only. next_cursor on the SocQ task result reader paginates records already stored for that task.

Each successful Douyin User Videos task costs a fixed 0.10 SocQ credits, independent of the number of records returned within the 20-record cap.