Douyin User Profile API

Douyin User Profile

Features

• Two supported identifiersResolve one public profile from either a supported Douyin user URL or a user_id that matches the runtime identifier rule.
• Profile identity and presentationReturn available profile ID, public URL, username, display name, biography, avatar, cover image, and associated website in one account record.
• Explicit account state fieldsPreserve available verification and privacy flags as nullable values instead of inferring a state when the public source omits it.
• Visible profile measurementsNormalize available follower, following, and post counts alongside collected_at for a time-specific view of the public profile.

Parameters

How to Use

Submit one supported profile identifier, track the asynchronous task, and read the normalized account from the stored-result envelope.

1. Prepare either a full Douyin profile URL with a /user/<identifier> path or a supported public user_id.
2. POST one identifier to /v1/douyin/user-profile and save the returned task_id.
3. Poll /v1/tasks/{task_id} until the status is succeeded or failed.
4. Read data.results.items after success; the source lookup produces at most one profile, while the stored result envelope still reports has_more and next_cursor.

curl -X POST "https://api.socq.ai/v1/douyin/user-profile" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"user_id\":\"${DOUYIN_USER_ID}\"}"

# Poll GET /v1/tasks/{task_id}
# Read the normalized account from data.results.items

Best Use Cases

• Creator record enrichment: Add available Douyin identity, biography, images, website, account flags, and public counts to an existing creator record.
• Profile identity checks: Resolve a known profile URL or user identifier into a consistent account object before linking it to an internal entity.
• Public account comparisons: Compare follower, following, and post counts across separately collected profiles using the same normalized metric keys.
• Profile snapshot monitoring: Store identity fields and public metrics with collected_at so later tasks remain distinguishable point-in-time observations.

Pro Tips

• When a canonical user identifier is already available, submit user_id alone; if url and user_id disagree, the provider request uses user_id.
• Before submitting a URL, verify its hostname and require a /user/<identifier> path so links to videos or other Douyin resources are rejected locally.
• Expect zero or one source profile record; the task reader's cursor paginates saved SocQ items and cannot request another provider page for this lookup.
• Treat identity, images, website, account flags, location, and each metric as nullable, and preserve collected_at when comparing repeated snapshots.

Related APIs