Douyin Creator Video Research API Tutorial | SandBase
Use a known Douyin sec_user_id for one profile or first-page post request, handle failures, and distinguish historical zero play counts from unavailable metrics.

You already have a Douyin creator’s sec_user_id. The next decision is small: do you need the profile, or one page of posted content? This guide starts there, with one request through SandBase. It does not search for accounts, rank every video or quietly add a statistics call. The earlier 2026-10-01 research experiment remains below as dated evidence of what those samples showed.
Key takeaway
- Use
app-v3/user-profilefor a knownsec_user_id, orapp-v3/user-post-videosfor a first post-list page.- For posts,
max_cursor=0starts the first page,countis at most 20, andsort_type=0means latest while1means hottest.- Only read
outputs[0].data. Check the observed providerstatus_code=0and the endpoint-specific structure before using any fields.- The two selected endpoints listed a $0.001 base price and shared organization quota of 100 eligible calls per UTC day on 2026-11-08. Remaining quota was not checked.
Choose one known-account request
| Question | Request |
|---|---|
| What profile information is available for this account? | User Profile, required string sec_user_id |
| What does one page of this account’s posted content look like? | User Videos, required sec_user_id with optional count, max_cursor, sort_type |
Use the exact identifier you already verified. A display name, a keyword, a numeric UID or a profile URL is not interchangeable with sec_user_id. If you only have a keyword, the Douyin API hub is the separate discovery starting point; the example here does not automatically select the first search result.
Choose sort_type=0 when you want a recent-content sample, or 1 for a popularity-ordered sample. These are request options, not a promise of complete coverage or an independent ranking by reach. The example asks for five items, within the documented maximum of 20; it does not assume five will be returned. It always starts at integer cursor 0 and stops after that request.
- Already have a key: configure
SANDBASE_API_KEYin your local environment or secret manager. Keep it out of prompts and committed source files. - Agent already connected: reuse the SandBase connection, discover Douyin and inspect the selected tool’s current schema and price.
- Starting a project: give the agent the setup Skill, Markdown Quickstart, your known identifier and your selected question. Ask it to prepare one request before executing it.
For example: “Prepare one first-page request for this known sec_user_id, count five, latest sorting. Reuse my SandBase connection and show the current parameters and pricing first. Do not search for another account, paginate, retry, or add batch statistics or an LLM step.”
One request, with errors kept visible
The free inspections on 2026-11-08 showed base_price: 0.001 and free_quota of 100 calls per organization, shared across eligible APIs, resetting at 00:00 UTC. That confirms eligibility for these two endpoints, not the remaining allowance or a guaranteed free call. Recheck usage and current pricing before execution. No new paid business query was run for this revision.
Install requests with python -m pip install requests. Set SANDBASE_API_KEY locally and put your known identifier in DOUYIN_SEC_USER_ID. Save this as douyin_first_request.py; running python douyin_first_request.py sends one potentially billable request. profile and posts are alternatives, not steps that both run. The URL uses the Model API POST route, not the historical catalog GET surface.
import os
import requests
def first_request(task, sec_user_id, *, count=5, sort_type=0):
if not isinstance(sec_user_id, str) or not sec_user_id.strip():
raise ValueError("Supply a known sec_user_id, not a nickname or search keyword")
if sec_user_id != sec_user_id.strip() or "://" in sec_user_id:
raise ValueError("Pass the exact sec_user_id string, not a URL")
if task == "profile":
path, params = "user-profile", {"sec_user_id": sec_user_id}
elif task == "posts":
if type(count) is not int or not 1 <= count <= 20:
raise ValueError("Choose an integer count from 1 to 20")
if type(sort_type) is not int or sort_type not in (0, 1):
raise ValueError("Use sort_type 0 for latest or 1 for hottest")
path = "user-post-videos"
params = {"sec_user_id": sec_user_id, "count": count,
"max_cursor": 0, "sort_type": sort_type}
else:
raise ValueError("Choose profile or posts")
key = os.environ.get("SANDBASE_API_KEY", "").strip()
if not key:
raise RuntimeError("Set SANDBASE_API_KEY locally")
try:
response = requests.post(f"https://api.sandbase.ai/v1/api/douyin/app-v3/{path}",
headers={"Authorization": f"Bearer {key}"}, json=params,
timeout=(10, 90), allow_redirects=False)
if not 200 <= response.status_code < 300:
raise RuntimeError(f"SandBase HTTP {response.status_code}; inspect before retrying")
body = response.json()
except ValueError:
raise RuntimeError("SandBase returned invalid JSON") from None
except requests.RequestException:
raise RuntimeError("Request failed; check run history before retrying") from None
if not isinstance(body, dict) or body.get("status") != "completed":
raise RuntimeError("SandBase run did not complete; inspect status and error")
outputs = body.get("outputs")
if not isinstance(outputs, list) or not outputs or not isinstance(outputs[0], dict):
raise RuntimeError("Missing outputs[0]")
payload = outputs[0].get("data")
if not isinstance(payload, dict):
raise RuntimeError("Missing object at outputs[0].data")
# Observed in the selected endpoints' public reference samples.
if type(payload.get("status_code")) is not int or payload["status_code"] != 0:
raise RuntimeError("Douyin failed or omitted its success status")
if task == "profile" and not isinstance(payload.get("user"), dict):
raise RuntimeError("Missing user object; do not infer zero followers")
if task == "posts":
posts = payload.get("aweme_list")
if not isinstance(posts, list) or any(not isinstance(item, dict) for item in posts):
raise RuntimeError("Missing or malformed aweme_list; do not infer zero posts")
return payload
if __name__ == "__main__":
# Choose ONE request; change profile to posts for one first-page request.
payload = first_request("profile", os.environ.get("DOUYIN_SEC_USER_ID"))
print("Payload keys:", sorted(payload))Both current public reference samples inspected on 2026-11-08 show status_code: 0; Profile has a user object and User Videos has an aweme_list. These are observed sample structures. The helper is deliberately strict about them and reports missing status or structure rather than converting it into an empty successful result. It does not add an extra provider data wrapper or accept the old top-level SandBase output fallback.
A valid empty list is preserved as an empty page, not proof that the account has never posted. A missing follower count remains absent. The helper prints only payload keys and makes no ranking or rate calculation. If a request times out or fails, inspect run history before deciding whether to retry; transport failure alone does not establish that no execution took place. The code was tested offline against controlled responses, not a new live creator result.
Historical evidence: 2026-10-01
The original experiment combined search, profiles, pagination and batch statistics. Its run IDs, trimmed response and four original screenshots are retained below. Original Python blocks are archived verbatim in repository evidence with hashes; their fallback, retry and zero-filling behavior is obsolete and is not the current integration path. The current revision validates only the two selected endpoint contracts and the one-request helper above.
Historical screenshot (2026-10-01): The Douyin catalog on SandBase. It lists endpoints as GET /apis/v1/douyin/..., including app-v3/multi-video-statistics, and the side panel shows the selected endpoint as Available, Free. This tutorial calls the Model API POST /v1/api/douyin/... routes instead. The screenshot was captured during API Free Week, when Free was the listed price; that promotion has ended. This old screenshot does not establish current eligibility or remaining quota.
Historical account discovery
I searched for 中国国家地理 (Chinese National Geography, the magazine). Each page returned 30 accounts with has_more: true and cursor: 30. Sending that cursor back gave the second page (runs 563bdc12-2bbc-403f-b918-a1b964306571 and 4b610646-336c-49b7-9f64-3b35cac0da98). The first hit was the magazine’s main account with about 5.64 million followers. It was followed by its sub-brands (Landscape, Channel, Local Culture, and Explore) and a few unrelated science accounts.
Two details matter here. First, the field is called user_id, but its value looked like MS4wLjABAAAA..., which is the sec_user_id format the app-v3 endpoints ask for. Passing it straight to the profile call worked. Second, the reference page describes this endpoint as supporting fan-count and user-type filters, but its request schema lists only keyword and cursor. I didn’t send undocumented filters. That observation does not expand the current two-endpoint example into a search workflow.
Historical screenshot (2026-10-01): The douyin/search/user-search-v2 reference: POST /v1/api/douyin/search/user-search-v2 with optional cursor (default 0) and keyword. The documented response example leaves outputs[0].data empty.
Historical profile sample
For the magazine account (run 046c8eae-9a2c-411c-9914-3c8f5ed1f754), the profile came back as unique_id zggjdl, about 5.64 million followers, about 25.7 million total likes, and an enterprise verification naming the magazine’s publishing company. The video count didn’t match search, though. The profile said 538 videos (aweme_count), while search said 545 posts (publish_cnt). On the news account I probed earlier, the gap was much larger (about 12,300 versus 15,900). The discrepancy means those source fields should not be silently equated. A partial post list also cannot establish an exact account-wide total.
Historical post-list sample
The reference used in that experiment said the first page used max_cursor 0 and later pages send the max_cursor from the previous response. The historical responses agreed; continuation was not retested in this revision. Each page returned 20 items, has_more: 1, and a max_cursor that looked like a millisecond timestamp. create_time on each video was in seconds. Here is a trimmed excerpt of the first page (run 28936f25-f639-471c-9f9b-1204e408db4c):
{
"has_more": 1,
"max_cursor": 1789444800000,
"aweme_list": [
{
"aweme_id": "7690953381636017446",
"desc": "【预告片】生命奇观2 川西山地 ...",
"create_time": 1790740800,
"is_top": 0,
"statistics": {
"play_count": 0,
"digg_count": 845,
"comment_count": 34,
"share_count": 16,
"collect_count": 43
}
}
]
}The reported play_count: 0 was not evidence that nobody watched. The historical statistics response below returned 70,966 for one of those posts. Preserve the original value with its source and retrieval date, while marking its meaning as unresolved; do not silently replace it with another endpoint’s value. Missing counts are also different from a returned zero. Neither belongs in a like-to-play calculation as an invented zero denominator.
The sample included apparent image posts (aweme_type: 68) alongside videos. That interpretation was observed, not a stable type contract. The old screenshot omitted sort_type values; the current schema now explicitly describes 0 latest and 1 hottest.
Historical screenshot (2026-10-01): The douyin/app-v3/user-post-videos reference: required sec_user_id, plus optional count (20 or fewer), max_cursor, and sort_type. This old screenshot omitted the values; the current contract specifies 0 latest and 1 hottest.
Historical statistics comparison
In my runs, statistics_list held one item per id, each with aweme_id, play_count, digg_count, share_count, and sometimes download_count. The same image post that showed 0 plays in the post list came back with 70,966 plays here (run dc35d090-ba7a-4391-a4f4-da78349bc42b). The join uses string ids, because both responses returned aweme_id as a string and string keys are safer than numbers this large.
Historical screenshot (2026-10-01): The douyin/app-v3/multi-video-statistics reference: one required aweme_ids string, comma-separated, 50 ids or fewer. The description says most Douyin interfaces no longer return play counts. Its old Price line is historical, not a current quote or availability check.
Historical aggregate result
On 2026-10-01, I ran the archived script verbatim. It made two search calls, one profile call, three post-list calls (1eca7db3-03b1-4af2-866b-30e69a24c249, 3042978c-8207-4915-9fea-a6e6c5d17c1c, d4a0422d-d0d3-409a-b057-4e3600902272), and two statistics calls for the 60 videos (c67a86e8-4129-4205-8790-fa4510bc1b2c, 6ab3f851-f942-436f-8121-0fb222cb77fa). The 60 items covered posts from early January to the end of September 2026. The ranking was lopsided. The top two videos had about 90.4 million and 87.0 million plays, and the third about 11.4 million. The median across all 60 was about 374,000. Among the top five, like-to-play ratios ran from about 1.5% to 4.1%. Those historical samples suggest a skewed distribution, not proof of causal audience preference. A like-to-play ratio needs comparable, available counts and a nonzero denominator; otherwise leave it unknown. The archived ranking code’s missing-to-zero behavior is not recommended.
For the 60-item case, the old arithmetic “profile + three post pages + one statistics call = five” was wrong under its own 50-ID limit. It needed two statistics calls: six calls after account selection, or eight including the two recorded searches. That is historical request accounting, not a current price or availability promise. Batch statistics, further pages and any model summary need separate verification and budgeting; they are not part of the new example.
Original evidence scope (2026-10-01)
| Item | Status |
|---|---|
POST /v1/api/douyin/search/user-search-v2 with keyword, cursor | Documented in the reference |
POST /v1/api/douyin/app-v3/user-profile with sec_user_id | Documented in the reference |
POST /v1/api/douyin/app-v3/user-post-videos with sec_user_id, max_cursor, count | Documented in the reference |
POST /v1/api/douyin/app-v3/multi-video-statistics with aweme_ids (50 or fewer) | Documented in the reference |
Envelope id / status / model / outputs[0].data | Documented in the reference |
Search data.user_list[] with user_id (sec_user_id format), nick_name, fans_cnt; cursor, has_more | Observed only |
Profile user.unique_id, follower_count, total_favorited, aweme_count, enterprise_verify_reason | Observed only |
Post list aweme_list[].statistics, has_more, max_cursor; play_count returned as 0 | Observed only |
Statistics statistics_list[] with aweme_id, play_count, digg_count | Observed only |
Apply the sample without inventing a ranking
For a known account, a profile request can help you inspect which fields are available. One latest-sorted page can help you select a post for closer reading. Save the identifier, sort choice, count and retrieval date with your observations. Do not generalize five returned items to the full catalog, or equate popularity sorting with exact play-count ordering.
Before presenting metrics, keep three states separate: a number actually returned, a missing field, and a request or provider error. A returned zero can still need interpretation, as the dated play-count example demonstrates. Do not fill missing likes with zero, calculate a rate without usable inputs, or claim a source mismatch was reconciled by taking whichever value is larger.
FAQ
Where does sec_user_id come from? Use a verified account identifier you already have. A nickname or numeric UID is not a substitute. Discovery is a separate task, not an automatic first step here.
Can I choose latest or hottest? Yes: the current post-list contract describes integer sort_type 0 and 1 respectively. The example uses count five and max_cursor 0; these are bounded sample choices, not guaranteed result counts.
Are both calls free? Both selected endpoints list a $0.001 base and shared 100-call organization quota per UTC day. Remaining allowance was not checked. This revision makes no current free-quota claim about user search or batch statistics.
Does play_count 0 mean zero actual views? The historical samples do not support that conclusion. Keep the source value and uncertainty; a missing field is also not zero. This guide does not automatically call another endpoint to fill it.
Should an empty page trigger a retry? Not automatically. Inspect the run and provider status first. A successful empty page remains a sample result, not proof of complete coverage or permission to repeat requests.
Use the Douyin API hub when your task expands beyond a known-account first request. Verify the next endpoint and budget before extending the workflow.
For a 2026 pricing comparison of the live SandBase Douyin hub, see Best Douyin API in 2026: Pricing Compared.
Found this useful? Share it