Douyin Billboard API: Inspect One Selected Board Page
Read one Douyin high-like or overall board page, validate nested results, and separate historical snapshots from unresolved time windows and growth claims.

A Douyin board page can help you inspect a set of video records. It cannot, by itself, tell you what changed since yesterday. Before adding a monitor, check which board you selected, which page actually came back, and what the provider’s metrics mean. This guide prepares one high-like or overall-video request, preserves the returned IDs and counters, and stops before pagination, URL resolution or scheduling.
This November 8, 2026 repair uses current public schemas, older saved responses and offline code tests. No new business API request was executed. The high-like capture contains eight rows; the overall capture contains 45 rows from page 20. Neither is evidence of a newly executed first-page request or a complete 1,000-video collection.
Key takeaway
- Select one board: high-like, or overall with
sub_type: 1001; the teaching request chooses page 1 and page_size 10.date_windowhas a conflicting default and description. Omit it here without claiming a verified hourly, daily or 24-hour interval.- Validate completed
outputs[0].data, integercode: 0, thendata.objsand returned page metadata.- Keep string item IDs and reported metrics unchanged. A list position, score or single snapshot does not establish global rank or growth.
The retained cover is a conceptual billboard-to-agent diagram. Its counters, synthetic IDs, “canonicalize” stage and monitoring claims are not API results or a workflow executed by this revision.
Choose a Douyin billboard API request
| Selected task | Exact API reference | Teaching body |
|---|---|---|
| Inspect the high-like board | High-like list | {"page":1,"page_size":10} |
| Inspect the overall video board | Overall video list | {"page":1,"page_size":10,"sub_type":1001} |
These are alternatives, not two steps of a required chain. All input fields are optional in the current schemas. Page 1 and page size 10 are explicit local choices matching their documented defaults, not provider maximums or a promise of ten returned rows. The high-like saved request used an empty object; its response has page 1/page_size 10. The overall saved request used page 20/page_size 50, so do not label its records as output from the teaching body.
Overall also documents selectors 1002 for low-follower breakout, 1003 for high completion, 1004 for high follower growth and 1005 for high like rate. Those names are provider categories, not outcomes established by this repair. In particular, subtype 1005 is not proven equivalent to the separate high-like route. This code selects only 1001 when you deliberately choose overall.
A keyword can filter a separately selected topic. Tags are declared as an array of objects, but the object fields are not established here; the example does not manufacture category objects or fetch tags automatically. Keep any future filter change with the result so that two different selections cannot silently become one comparison series.
Historical Douyin catalog with GET navigation paths, an overall-video entry and a selected general-search panel. Its displayed From $0.01 belongs to that older panel, not the current selected $0.001 board routes; this is not a live board response.
The time-window conflict remains unresolved
Both schemas give date_window a default of 24, while describing it as “1 by hour 2 by day.” Neither saved input explicitly supplies the field. There is not enough evidence to reinterpret 24 as 24 hours, choose 1 or 2 as a verified mode, or silently “fix” a server default in client code.
The teaching request therefore omits date_window. Omission avoids asserting an unsupported value, but it does not resolve what the server does by default. Describe the result as a selected provider board snapshot, not an hourly or daily observation. If your business question requires a precise time window, resolve that contract with the provider before using the result for that comparison.
Historical high-like parameter reference: date_window visibly has default 24 beside the 1/hour, 2/day description. The generated response data is empty. The contradiction remains explicit here; this screenshot is not a successful ranking result.
Connect your agent without creating a crawl
If you already have a key, reuse the project’s local SANDBASE_API_KEY configuration and install Python’s requests dependency if necessary. Do not paste the key into a prompt or print it during diagnostics. An existing secret store does not need replacing merely to try another endpoint.
If your agent is already connected, give it the selected board and a stopping rule: prepare one page, validate the response, preserve source field names and stop. Do not ask it to “monitor trends” without clarifying a time window, persistence and a budget; that vague instruction can turn a single read into many unintended calls.
For a new project, provide the setup skill and Markdown quickstart. A concrete request is: “Implement and test one high-like board request using page 1/page_size 10 and my existing local key. Leave date_window out and explain the unresolved window. Do not call a resolver, fetch media, continue pages or install a schedule.” Choose overall explicitly if that is the desired category.
The November 8 inspect lists both endpoints at $0.001 per call. They are eligible for the organization-shared allowance of 100 eligible calls each day, resetting at 00:00 UTC. That is eligibility, not the remaining balance or proof that your next call is free. One selected request lists at $0.001; two intentional requests list at $0.002 before quota effects. No actual charge or fresh availability was measured in this revision.
Python: validate one selected response
Use the Model API POST /v1/api/<model> route below, rather than the GET path displayed in a catalog. The model is encoded in the route, and the JSON body contains operation parameters. This example makes one request and does not retry automatically.
import os
import re
import requests
API = "https://api.sandbase.ai/v1/api/douyin/billboard"
def parse_board(body):
if not isinstance(body, dict) or body.get("status") != "completed":
raise RuntimeError("SandBase request did not complete")
outputs = body.get("outputs")
if not isinstance(outputs, list) or not outputs or not isinstance(outputs[0], dict):
raise RuntimeError("Missing documented outputs[0]")
payload = outputs[0].get("data")
if not isinstance(payload, dict):
raise RuntimeError("Missing documented outputs[0].data object")
if type(payload.get("code")) is not int or payload["code"] != 0:
raise RuntimeError("Douyin board result is not integer code zero")
data = payload.get("data")
if not isinstance(data, dict):
raise RuntimeError("Missing board data object")
rows, page = data.get("objs"), data.get("page")
if not isinstance(rows, list) or any(not isinstance(row, dict) for row in rows):
raise RuntimeError("Missing or malformed board objs array")
for row in rows:
if not isinstance(row.get("item_id"), str) or not re.fullmatch(r"[0-9]+", row["item_id"]):
raise RuntimeError("Expected an unchanged decimal string item_id")
if (not isinstance(page, dict)
or any(type(page.get(k)) is not int for k in ("page", "page_size", "total"))
or page["page"] < 1 or page["page_size"] < 1 or page["total"] < 0):
raise RuntimeError("Missing or malformed board page metadata")
return payload
def first_request(board):
if board == "high_like":
route = "hot-total-high-like-list"
params = {"page": 1, "page_size": 10}
elif board == "overall":
route = "hot-total-video-list"
params = {"page": 1, "page_size": 10, "sub_type": 1001}
else:
raise ValueError("Choose high_like or overall")
# date_window deliberately omitted: its default and description conflict.
key = os.environ.get("SANDBASE_API_KEY", "").strip()
if not key:
raise ValueError("Set SANDBASE_API_KEY locally")
try:
response = requests.post(
f"{API}/{route}",
headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
json=params, timeout=(10, 90), allow_redirects=False,
)
if not 200 <= response.status_code < 300:
raise RuntimeError(f"SandBase HTTP {response.status_code}; request stopped")
body = response.json()
except requests.RequestException:
raise RuntimeError("Network request failed; no automatic retry made") from None
except ValueError:
raise RuntimeError("SandBase returned invalid JSON") from None
payload = parse_board(body)
page = payload["data"]["page"]
if page["page"] != 1 or page["page_size"] != 10:
raise RuntimeError("Returned page metadata differs from the selected first request")
return payload
if __name__ == "__main__":
result = first_request("high_like")
print("Returned records:", len(result["data"]["objs"]))For the other task, replace result = first_request("high_like") with result = first_request("overall"); do not append a second call. The positive page values and decimal-string ID check are conservative local guards for these references, not a claim about all possible provider records. Optional counters and flags are returned unchanged rather than normalized to zero.
parse_board can inspect a previously saved envelope at any positive page. first_request additionally requires the returned page/page_size to match its selected first page. This separation lets the offline test parse the real page-20 reference while correctly rejecting it as a response to the new page-1 plan. Tests never change that historical page metadata to make a mock look successful.
A completed transport envelope is not enough: missing arrays, nonzero provider code and malformed data all fail. Strict integer checking also prevents Python’s False == 0 behavior from turning an invalid status into success. The saved successful message is empty, so the code does not require a guessed “success” string. An explicit empty objs array is valid, but does not prove the board has no content elsewhere.
On HTTP errors, redirects, invalid JSON, non-completed runs, timeouts or unexpected page metadata, stop and inspect the cause. The error does not print upstream bodies, signed URLs or secrets. A timeout leaves the result uncertain; choosing to retry is a separate decision after checking the request and accounting, not an implicit loop in this example.
Saved high-like and overall references are different evidence
The high-like saved example 9b892f8c-413f-4e67-9078-82537434c27e was created October 7, 2026 at 17:37:02.062 UTC, with input {}. Its available capture has eight records and page/page_size/total of 1/10/1000. Selected fields of its first record are reproduced exactly below, without signed media references:
{
"item_id": "7692681489309628406",
"like_cnt": 1218230,
"play_cnt": 13545023,
"like_rate": 0.089939,
"fans_cnt": 7287,
"follow_cnt": 3774,
"follow_rate": 0.00029,
"score": 1215906,
"publish_time": 1791091983,
"item_duration": 13652
}The overall example 7358df41-8bd6-4d24-96cb-f06606135dcb, created October 7 at 17:37:33.175 UTC, used empty keyword, page 20, page_size 50, subtype 1001 and empty tags. The capture has 45 records, with page/page_size/total 20/50/1000. Its first captured record has these values:
{
"item_id": "7692701792556425715",
"like_cnt": 436943,
"play_cnt": 13576423,
"like_rate": 0.032184,
"fans_cnt": 36229536,
"follow_cnt": 8327,
"follow_rate": 0.00062,
"score": 193300,
"publish_time": 1791104400,
"item_duration": 260800
}Eight is not ten and 45 is not 50. Those are the available captured counts; this repair does not diagnose the difference or invent absent rows. A reported total of 1000 is not proof that 1000 unique videos are retrievable, that earlier pages were traversed, or that the board covers all Douyin content. The first row of page 20 is especially unsuitable for an enumerate(...)+1 global rank.
The shortened READMEs show different IDs, 7703456989958999305 and 7702397404621350821, with page 1/page_size 10. They are undated trimmed references, tested separately from the complete saved captures. Their one displayed row is not a complete page. Neither reference supplies evidence that the teaching first-page request ran during this repair.
Keep the metrics and clocks separate
Store like_cnt, play_cnt, like_rate, fans_cnt, follow_cnt, follow_rate and score under their original names. The source rates remain separate from the raw counters; this guide does not assert an authoritative formula, denominator or measurement interval. In particular, follow_cnt is not verified as the creator’s following total or net follower gain, and score does not disclose a reproducible ranking algorithm.
publish_time is described in Unix seconds. The provider’s extra.now, the saved example’s creation date and your application’s observation time are different clocks. Keep them separately rather than using one to invent another. The unit of item_duration is not independently established here, so do not convert it to seconds or label it milliseconds based on its magnitude.
Names, avatars and follower-related counters are reported data, not identity verification or evidence of unique audience quality. Favorite flags are returned state, not authorization to favorite anything. Missing values remain unknown, even when zero appears elsewhere in the same response. Board presence alone does not establish a sustained trend or a cause of audience growth.
Why the old resolver and monitor were removed
The board already includes an exact string item_id. Its item_url and cover links can be expiring signed media references; they are not verified share-link resolver inputs. This request does not download them, resolve them, or grant media reuse rights. Preserve IDs as strings rather than converting large values through floating-point numbers.
The original September 27 code resolved each row and kept an in-memory SEEN set. That set only remembers values while its process remains alive, and ignores metric changes on already-seen IDs. It could not justify the promise that every scheduled execution reports “only what changed.” The six bilingual Python blocks are preserved verbatim in the historical code archive and hashes, not offered as the current integration.
Historical aweme-id reference with a URL input and an empty generated response. The resolver is outside this revision; this image does not prove that signed board media URLs are accepted or that an ID-resolution chain ran successfully.
The original JSON below remains an illustration, including its run-shaped ID d4727a3b-18ea-403d-b90b-db093210ecac. It is not a dated business result and must not be used as a substitute for the separate saved examples above.
{
"id": "d4727a3b-18ea-403d-b90b-db093210ecac",
"status": "completed",
"model": "douyin/billboard/hot-total-high-like-list",
"outputs": [
{
"data": {
"code": 0,
"data": {
"objs": [
{ "item_id": "…", "item_title": "…", "nick_name": "…", "like_cnt": 0, "item_url": "…" }
]
}
}
}
]
}FAQ
Can I label this result “the last 24 hours”? No. The default/description conflict is unresolved, and leaving the field out does not establish a particular interval. A time-specific comparison needs an independently confirmed contract.
Does page_size 10 guarantee ten videos? No. The high-like saved capture has eight. Preserve the actual returned count, page metadata and context; do not insert blank records or call another page just to reach ten.
Can I immediately build a growth alert from these counters? First establish comparable board settings, observation times, persistent storage, duplicate handling and a bounded polling budget. One snapshot cannot validate that design. This tutorial installs no schedule and performs no continuation.
For other capabilities, use the Douyin API hub. If you already selected a creator rather than a board, the creator profile and posts guide addresses that separate task. Keep the first integration small enough that you can explain every input, returned page and unknown metric before extending it.
Found this useful? Share it