> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# How do I organize a Douyin creator's posts and choose cases worth studying?

> Fix the creator and research purpose, build a traceable post table, and review coverage and post age before selecting cases without claiming complete history.

To organize a Douyin creator’s posts, copy the identifier after `/user/` in the creator’s public profile URL and pass the identifier as `sec_user_id` to `douyin.app.v3.fetch_user_post_videos`. Follow the returned cursor and save each response, then export `posts.csv` with `export_creator_posts.py`, or convert the same saved data into an XLSX workbook with `posts_to_xlsx.py`.

For example, to study a home creator’s storage videos from last month, keep the captions, publication dates, counts and video IDs, then select the posts that show installation. When you share the table, include the observed dates, the pages checked and the stop reason.

## Choose the question before the page budget

| Research question                           | Starting material                                            | Basis for further review                                                             |
| ------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| Recent topics and expression                | Descriptions and posts in a defined observation window       | Human themes with exact text, not invented speech.                                   |
| Which works deserve case study              | Relevant descriptions, publication times and actual counters | Content fit first, considering age and collection time rather than totals alone.     |
| Has publishing cadence changed?             | Publication times inside the covered window                  | Check missing pages and interval completeness before inferring reduced activity.     |
| What should we verify before a partnership? | Target works and comparable metrics                          | Public engagement does not replace completion, price, sales or attribution evidence. |

Start with one page, assess relevance, then approve more pages and their cost. `count` is a per-request cap, and pages can come back short or overlapping, so twenty × pages does not mean that many distinct posts.

## Which cases should I retain from the table?

Before opening `posts.csv`, read `coverage.json` for the successful pages, the distinct posts and the stop reason. In a separate working copy, add a keep/exclude/unverified status, a reason, a research angle and a next action for each post. `export_creator_posts.py` does not make those judgments.

For a **hypothetical** example, an old popular post unrelated to the use case can be excluded, and a recent tutorial with modest engagement that explains a key step can be worth reading. The choice does not show that the old post is bad or that the tutorial will sell, and unmatched totals do not measure quality.

A description shows what the caption says, not the complete speech or visuals. Media addresses and duration do not show that anyone watched the work. Keep `aweme_type` as returned instead of assuming every object is a standard video. Comments and individual detail checks are separate evidence with a separate scope.

## Let teammates trace the selected material

`posts.csv` keeps each post's first observation, `observations.jsonl` keeps repeats and later changes, and `sources.json` together with the original responses makes every row traceable. Two observations of one ID are one case, not two. Keep missing values separate from zero, and publication time separate from collection time.

When you need a workbook, use the local Excel converter `posts_to_xlsx.py` below. Every cell is text, so exact values and long IDs survive; do calculations in a separately verified sheet, without converting the identity columns to numbers. A fresh export does not carry the editorial decisions from your working copy, so keep the reviewed copies and reconcile them by post ID.

In the handoff, include the account, the selection purpose, the actual pages and times, the promising cases, the missing evidence and the next checks. State the unobserved history explicitly; the end of the visible list is not a complete historical recovery.

For example, for a March inventory, check the successful pages and the stop reason in `coverage.json`, then use the publication dates in `posts.csv` to check the range and filter for March. If the archive only reaches mid-March, mark the first half of March as open, and share the last successful page and the page's continuation cursor. After merging pages, spot-check one long ID in Excel against the source.

## Reuse the list before buying more detail

Export and recalculate saved pages locally. When the list response already returns plays or other counters, keep those counters instead of buying a detail call per post for the same fields; missing counters stay missing. Query again only for a new observation, a further page or necessary evidence, each with the action's own contract and budget.

Steps 1–7 below cover the account, paging, export and Excel conversion. Sources: the observed list contracts and offline regression tests; the example account was not collected.

## 1. Identify the creator and approve a page budget

Use the actual `sec_user_id`, not the numeric uid, a nickname or a video’s aweme_id. A full `https://www.douyin.com/user/<sec_user_id>` profile link contains the required identifier after `/user/`; copy the complete segment without query parameters. Resolve a short sharing link to the actual profile first. Do not guess an ID from the short-link token, and do not send the entire URL as sec_user_id.

Start with one page to verify the account and the columns. The requested `count:20` is a maximum, so count unique posts across the pages you actually receive. A 50-page plan allows up to 50 list requests; see [BeatAPI pricing](https://beatapi.io/pricing). Saved pages can be re-exported locally.

The list response returns posts in `data.aweme_list` with counters in `statistics`. The list can return `play_count`; a missing play count stays missing. Do not buy a detail call per post only to get a column the list already has. The list does not give completion rate, unique reach or advertising attribution.

## 2. Save the first request and response

Save the request body below as `request-1.json`, replacing the ID:

```json
{"action":"douyin.app.v3.fetch_user_post_videos","params":{"sec_user_id":"<actual_sec_user_id>","max_cursor":0,"count":20,"sort_type":0,"channel":"normal"}}
```

After the price and scope are approved, send the request once:

```bash
mkdir douyin-page-1 && \
curl --fail-with-body -sS https://api.beatapi.io/v1/social-data/call \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @request-1.json \
  -D douyin-page-1/response.headers \
  -o douyin-page-1/response.json
```

Record the actual HTTP status and a timezone-aware query time. A created JSON file is not proof of success. New directories keep earlier evidence from being overwritten. Use the complete direct Social Data response, not a truncated AI preview or a projection of selected fields.

## 3. Record the exact page chain

Save `pages.json` next to the page directories. The example below shows the format; replace the ID, HTTP status and time with the real values. Record the parameters actually sent, including the explicit defaults:

```json
[{"action":"douyin.app.v3.fetch_user_post_videos","params":{"sec_user_id":"<actual_sec_user_id>","max_cursor":0,"count":20,"sort_type":0,"channel":"normal"},"http_status":200,"collected_at":"2026-11-17T08:00:00+08:00","response_file":"douyin-page-1/response.json"}]
```

For each later approved page, append one entry per saved response. Keep the account, count, sort and channel unchanged. `sort_type: 0` is latest and `1` is hottest. `channel: lite` is an alternative when the normal channel does not show recent posts, but switching channels starts a separate chain at cursor 0: do not merge a channel change into one continuation, and do not pay for a fallback automatically.

## 4. Convert saved pages without another API call

Save the script below as `export_creator_posts.py`, then run `python3 export_creator_posts.py pages.json creator-export-1`. `export_creator_posts.py` accepts up to 200 saved pages per run and never makes network requests. The script checks `author.sec_uid` against the requested creator, keeps the original string `aweme_id` values, checks the cursor chain and refuses to overwrite existing output directories.

```python
import csv
import hashlib
import json
import sys
from datetime import datetime
from pathlib import Path

manifest_file, output = map(Path, sys.argv[1:])
pages = json.loads(manifest_file.read_text(encoding="utf-8"))
if not isinstance(pages, list) or not 1 <= len(pages) <= 200:
    raise SystemExit("Use 1 to 200 saved-page entries")
action = "douyin.app.v3.fetch_user_post_videos"
base = None
expected_cursor = 0
seen_cursors = {0}
seen_requests = set()
seen_files = set()
observations, selected, sources = [], {}, []
last_time = None
next_request = None
stop = "saved_page_limit"
failure_info = None
def integer(value):
    return type(value) is int and 0 <= value <= 9007199254740991
def count(value):
    if value is None: return ""
    if integer(value): return value
    if isinstance(value, str) and value.isascii() and value.isdigit(): return int(value)
    raise ValueError("Expected nonnegative safe integer count or original digit string")
for index, entry in enumerate(pages):
    params = entry.get("params")
    if entry.get("action") != action or not isinstance(params, dict) or set(params) != {"sec_user_id", "max_cursor", "count", "sort_type", "channel"}:
        raise ValueError("Record all five original request parameters for this workflow")
    uid = params["sec_user_id"]
    if not isinstance(uid, str) or not uid.strip() or uid != uid.strip():
        raise ValueError("Use the actual sec_user_id string, not uid, nickname or URL")
    if type(params["count"]) is not int or params["count"] != 20 or type(params["sort_type"]) is not int or params["sort_type"] not in (0, 1) or params["channel"] not in ("normal", "lite"):
        raise ValueError("Keep count=20 and a documented sort/channel")
    if not integer(params["max_cursor"]) or params["max_cursor"] != expected_cursor:
        raise ValueError("Cursor chain differs from the preceding saved response")
    scope = {key: params[key] for key in ("sec_user_id", "count", "sort_type", "channel")}
    if base is None: base = scope
    if scope != base: raise ValueError("Do not mix accounts, sort orders or channels in a pagination chain")
    stamp = datetime.fromisoformat(entry["collected_at"].replace("Z", "+00:00"))
    if stamp.utcoffset() is None or (last_time is not None and stamp < last_time):
        raise ValueError("Use nondecreasing actual observation times with timezone")
    last_time = stamp
    path = (manifest_file.parent / entry["response_file"]).resolve()
    if path in seen_files: raise ValueError("Repeated response file")
    seen_files.add(path)
    raw = path.read_bytes()
    response = json.loads(raw)
    if not isinstance(response, dict): raise ValueError("Expected a JSON response object")
    http = entry.get("http_status")
    if type(http) is not int or not 100 <= http <= 599: raise ValueError("Record a valid HTTP status")
    saved_name = f"raw-page-{index + 1:02d}.json"
    digest = hashlib.sha256(raw).hexdigest()
    sources.append((saved_name, raw, {"file": saved_name, "source_file": str(path), "sha256": digest,
        "params": params, "collected_at": entry["collected_at"], "http_status": http}))
    if http != 200 or response.get("status") != "succeeded":
        error = response.get("error")
        if response.get("status") not in (None, "failed") or not isinstance(error, dict) or not isinstance(error.get("code"), str) or not error["code"].strip():
            raise ValueError("Unrecognized failure envelope; preserve the original response for diagnosis")
        failure_info = {"http_status": http, "error_code": error["code"], "source_file": saved_name}
        failed_request_id = error.get("request_id", response.get("request_id"))
        if isinstance(failed_request_id, str) and failed_request_id.strip(): failure_info["request_id"] = failed_request_id
        stop = "request_failure"
        if index != len(pages) - 1: raise ValueError("Stop the manifest at its failed request")
        break
    if response.get("error") is not None: raise ValueError("Success envelope contains an error")
    if response.get("action") != action or not isinstance(response.get("request_id"), str) or not response["request_id"].strip():
        raise ValueError("Wrong action or missing request ID")
    request_id = response["request_id"]
    if request_id in seen_requests: raise ValueError("Repeated request ID is not another page")
    seen_requests.add(request_id)
    data = response.get("data")
    if not isinstance(data, dict) or not isinstance(data.get("aweme_list"), list) or type(data.get("has_more")) is not int or data["has_more"] not in (0, 1):
        raise ValueError("Expected aweme_list and numeric has_more=0/1")
    items = data["aweme_list"]
    for item in items:
        if not isinstance(item, dict): raise ValueError("Unexpected post object")
        identifier = item.get("aweme_id")
        if not isinstance(identifier, str) or not identifier.isascii() or not identifier.isdigit():
            raise ValueError("Keep the original string-encoded aweme_id")
        author = item.get("author")
        if not isinstance(author, dict) or author.get("sec_uid") != uid:
            raise ValueError("Returned post author does not match the requested account")
        stats = item.get("statistics")
        if stats is None: stats = {}
        if not isinstance(stats, dict): raise ValueError("Invalid statistics object")
        created = item.get("create_time")
        if created is not None and not integer(created): raise ValueError("Invalid publication timestamp")
        desc = item.get("desc")
        if desc is not None and not isinstance(desc, str): raise ValueError("Invalid caption")
        row = {"aweme_id": identifier, "sec_user_id": uid, "caption": desc or "", "create_time_unix": created,
               "share_url": item.get("share_url"), "aweme_type": item.get("aweme_type"),
               **{key: count(stats.get(key)) for key in ("digg_count", "comment_count", "share_count", "collect_count", "play_count")},
               "collected_at": entry["collected_at"], "request_id": request_id, "source_file": saved_name, "source_sha256": digest}
        for field in ("share_url",):
            if row[field] is not None and not isinstance(row[field], str): raise ValueError("Invalid share link")
        if row["aweme_type"] is not None and not integer(row["aweme_type"]): raise ValueError("Invalid post type code")
        observations.append({"aweme_id": identifier, "request_id": request_id, "source_file": saved_name, "collected_at": entry["collected_at"], "item": item})
        if identifier not in selected: selected[identifier] = row
    returned_cursor = data.get("max_cursor")
    if data["has_more"] == 0: stop = "provider_end"
    elif not items: stop = "empty_page_with_more"
    elif not integer(returned_cursor): stop = "missing_or_unsafe_cursor"
    elif returned_cursor in seen_cursors: stop = "repeated_cursor"
    else:
        stop = "saved_page_limit"
        seen_cursors.add(returned_cursor)
        expected_cursor = returned_cursor
        next_request = {"action": action, "params": {**base, "max_cursor": returned_cursor}}
    if stop != "saved_page_limit":
        next_request = None
        if index != len(pages) - 1: raise ValueError("Extra entries after a terminal or anomalous page")
        break
if stop == "request_failure": next_request = None
output.mkdir(exist_ok=False)
columns = ["aweme_id", "sec_user_id", "caption", "create_time_unix", "share_url", "aweme_type", "digg_count", "comment_count", "share_count", "collect_count", "play_count", "collected_at", "request_id", "source_file", "source_sha256"]
with (output / "posts.csv").open("x", encoding="utf-8-sig", newline="") as handle:
    writer = csv.DictWriter(handle, fieldnames=columns)
    writer.writeheader()
    for row in selected.values():
        writer.writerow({key: ("'" + value if isinstance(value, str) and value.lstrip().startswith(("=", "+", "-", "@")) else value) for key, value in row.items()})
with (output / "observations.jsonl").open("x", encoding="utf-8") as handle:
    for observation in observations: handle.write(json.dumps(observation, ensure_ascii=False) + "\n")
for name, raw, _ in sources: (output / name).write_bytes(raw)
(output / "sources.json").write_text(json.dumps([record for _, _, record in sources], ensure_ascii=False, indent=2), encoding="utf-8")
coverage = {"scope": base, "saved_responses": len(sources), "successful_pages": len(seen_requests), "observations": len(observations), "unique_posts": len(selected), "duplicate_observations": len(observations) - len(selected), "stop_reason": stop, "failure": failure_info, "all_historical_posts_collected": False, "policy": "first observation in CSV; all returned observations retained; no network calls"}
(output / "coverage.json").write_text(json.dumps(coverage, indent=2), encoding="utf-8")
if next_request: (output / "next-request.json").write_text(json.dumps(next_request, indent=2), encoding="utf-8")
print(json.dumps(coverage))
```

## 5. Continue only when the report permits it

Read `coverage.json` before requesting another page. The stop reason in `coverage.json` decides the next step:

* `saved_page_limit` with `next-request.json`: the saved chain has a usable new cursor. If you are still within the approved budget, send the exact `next-request.json` body once, save the response in a new directory and append the response's actual metadata to `pages.json`. Re-run the export into a new directory; old saved pages are read locally, not bought again.
* `provider_end`: `has_more=0` ends the returned list. `provider_end` does not show that deleted or private history was obtained.
* `repeated_cursor`, `empty_page_with_more` or `missing_or_unsafe_cursor`: stop and investigate the saved request and response. Do not increment the cursor or replay page one.
* `request_failure`: a recognized gateway error with a nonempty error code. The export keeps the earlier valid observations and the failed raw response, and generates no next-request proposal. Fix or escalate the error before a separately authorized retry.

Malformed successful data, wrong authors, mixed parameters and broken chains stop the script before the export is created; the original saved responses stay available for diagnosis. The 200-page limit is a local processing bound of `export_creator_posts.py`, not an API promise or permission to make 200 calls.

## 6. Deliver and check the results

`posts.csv` keeps the first observation of each `aweme_id` in manifest order. `observations.jsonl` keeps every returned object, including later metric changes. `sources.json` links the raw bytes, SHA-256, original parameters and query time. Use the coverage counts to separate page overlap from distinct posts. Missing counters stay blank, a reported zero stays zero, and text that starts with a formula character is escaped for spreadsheets.

Publication time is `create_time_unix`, and `collected_at` is the recorded query time; the two are not interchangeable. Each row’s `aweme_type` keeps the returned code instead of assuming every post is a video. The media URLs in raw objects can expire. The workflow downloads no media, verifies no transcripts and counts no unique viewers.

Before sharing, compare two CSV rows with the saved raw objects, verify the creator match, and report the stop reason and the unique-post count. A one-page result is a sample, and even `provider_end` covers only the visible returned list. Reuse the original files to change the presentation without further charges.

[Share-link metrics](/guides/douyin-share-snapshot) · [Comment workflow](/guides/douyin-video-comments)

[Profile URL and account identifier preparation](/faq/douyin-account-identifiers).

## 7. Create an Excel workbook without rounding video IDs

Double-clicking a CSV in spreadsheet software can turn long IDs into numbers or dates, so keep `posts.csv` as the source artifact. For an actual .xlsx workbook, use the offline standard-library converter `posts_to_xlsx.py` below, which writes **every cell as text**, including `aweme_id`, counters, timestamps and URL-looking strings. The converter keeps the exact CSV values and cannot repair identifiers that were rounded before export. The converter creates no formulas, macros, clickable hyperlinks or network requests.

Save the code as `posts_to_xlsx.py` and run:

```bash
python3 posts_to_xlsx.py creator-export-1/posts.csv creator-posts-review.xlsx
```

`posts_to_xlsx.py` produces one Posts sheet with a frozen header and a filter. The limits are 50,000 data rows, 100 columns and a 20 MiB source CSV; the limits are an offline safety boundary, not a platform limit. An empty export with a valid header produces a header-only workbook, which is not a successful collection. Existing output files are protected. The workbook keeps the CSV's formula-safety apostrophes literally; when the CSV exporter added such an apostrophe, compare exact caption quotations against the archived raw response.

```python
import csv, hashlib, io, json, pathlib, re, sys, zipfile
from xml.etree import ElementTree as ET
source, target = map(pathlib.Path, sys.argv[1:3])
raw = source.read_bytes()
if len(raw) > 20 * 1024 * 1024: raise ValueError('Use a CSV of at most 20 MiB')
rows = list(csv.reader(io.StringIO(raw.decode('utf-8-sig'), newline='')))
if not rows or not 1 <= len(rows[0]) <= 100 or len(rows) > 50001:
    raise ValueError('Expected header, at most 100 columns and 50000 data rows')
if len(set(rows[0])) != len(rows[0]) or any(not x for x in rows[0]):
    raise ValueError('Header names must be nonempty and distinct')
if 'aweme_id' not in rows[0]: raise ValueError('Expected the documented posts.csv with aweme_id')
for row in rows:
    if len(row) != len(rows[0]): raise ValueError('Ragged CSV')
    for cell in row:
        if len(cell.encode('utf-16-le')) // 2 > 32767 or re.search(r'[\x00-\x08\x0b\x0c\x0e-\x1f\ufffe\uffff]', cell):
            raise ValueError('Cell exceeds spreadsheet text limits or contains invalid XML characters')
ns = 'http://schemas.openxmlformats.org/spreadsheetml/2006/main'
def tag(name): return '{'+ns+'}'+name
def col(n):
    out = ''
    while n: n, r = divmod(n-1,26); out = chr(65+r)+out
    return out
sheet = ET.Element(tag('worksheet'))
views = ET.SubElement(sheet,tag('sheetViews'))
view = ET.SubElement(views,tag('sheetView'),workbookViewId='0')
ET.SubElement(view,tag('pane'),ySplit='1',topLeftCell='A2',activePane='bottomLeft',state='frozen')
data = ET.SubElement(sheet,tag('sheetData'))
for number, row in enumerate(rows,1):
    node=ET.SubElement(data,tag('row'),r=str(number))
    for index, value in enumerate(row,1):
        cell=ET.SubElement(node,tag('c'),r=col(index)+str(number),t='inlineStr')
        text=ET.SubElement(ET.SubElement(cell,tag('is')),tag('t'))
        text.set('{http://www.w3.org/XML/1998/namespace}space','preserve');text.text=re.sub(r'_(?=x[0-9A-Fa-f]{4}_)','_x005F_',value)
ET.SubElement(sheet,tag('autoFilter'),ref='A1:'+col(len(rows[0]))+str(len(rows)))
parts={
'[Content_Types].xml':'<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types"><Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/><Default Extension="xml" ContentType="application/xml"/><Override PartName="/xl/workbook.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"/><Override PartName="/xl/worksheets/sheet1.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/></Types>',
'_rels/.rels':'<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="xl/workbook.xml"/></Relationships>',
'xl/workbook.xml':'<workbook xmlns="'+ns+'" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"><sheets><sheet name="Posts" sheetId="1" r:id="rId1"/></sheets></workbook>',
'xl/_rels/workbook.xml.rels':'<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet" Target="worksheets/sheet1.xml"/></Relationships>',
'xl/worksheets/sheet1.xml':ET.tostring(sheet,encoding='utf-8',xml_declaration=True).replace(b'\r',b'&#13;')}
if target.suffix.lower() != '.xlsx': raise ValueError('Use an .xlsx output filename')
with target.open('xb') as handle:
    with zipfile.ZipFile(handle,'w',compression=zipfile.ZIP_DEFLATED) as z:
        for name, content in parts.items():z.writestr(name,content)
print(json.dumps({'file':str(target),'rows':len(rows)-1,'source_sha256':hashlib.sha256(raw).hexdigest(),'all_cells':'text','network_calls':0}))
```

Accept the workbook in three checks:

1. Compare the reported row count with `posts.csv`.
2. Inspect several full-length `aweme_id` strings and the matching captions.
3. Check that a zero counter and a blank counter stay distinct.

The workbook stores counters as text on purpose, so a spreadsheet SUM does not cover the counters. For calculations, create a separate derived sheet after checking units, missing values and the safe numeric range, and do not convert the evidence ID column to numbers. Keep `posts.csv`, `observations.jsonl`, `sources.json`, `coverage.json` and the raw-page directory with the workbook. The printed SHA-256 identifies the source CSV; the hash is not proof of authenticity.

The workbook is a portable view of the validated creator export. Comments, keyword search, trend indexes and creator quotes are separate workflows with separate budgets. Sources: local synthetic regression tests of the package and text values; opening the workbook in Excel or Numbers is untested. The minimal package follows [Microsoft's SpreadsheetML structure](https://learn.microsoft.com/en-us/office/open-xml/spreadsheet/structure-of-a-spreadsheetml-document).

## Turn the inventory into an account review

Start with a question the evidence can answer, such as whether recent tutorials open more clearly. Tag tutorial, promotion and everyday posts separately. For a median, use a group with comparable values and publication ages. Inspect works above and below the median, and record observable differences, such as whether the introduction shows the finished result. Report the actual sample size and gaps.

For changes to the same work, compare actual observations with the [work snapshot](/guides/douyin-share-snapshot). Account growth, publishing history and private campaign attribution need their own sources. Ask the assistant to deliver findings by topic and confirmed metric, with work sources, possible explanations and one change to try next.