> 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.

# Save Douyin share-link details and engagement to CSV

> Export real detail fields while preserving missing metrics.

To save a Douyin share link's details and engagement to CSV, look up the share link with `douyin.app.v3.fetch_one_video_by_share_url`, then export one CSV row from the saved response with `douyin_snapshot.py`. The row keeps the video ID, caption, engagement counts and observation time. For completion rate, use a campaign or account report you can access for the same video.

## 1. Define the target and cost

Start with one real share link. Check the current price of `data:douyin.app.v3.fetch_one_video_by_share_url` with the free `/v1/capabilities/inspect`. The workflow makes one detail call and exports locally; the workflow does not fetch comments or download media.

## 2. Save the response

```bash
mkdir douyin-query-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' \
  -d '{"action":"douyin.app.v3.fetch_one_video_by_share_url","params":{"share_url":"<share_url>"}}' \
  -D douyin-query-1/headers.txt \
  -o douyin-query-1/detail.json
```

Replace the placeholder link. If the HTTP request fails, stop and keep the error. Keep the raw JSON, and check the business `status` before parsing.

## 3. Convert the actual detail fields

Save the script below as `douyin_snapshot.py`. The script rejects failed or filtered responses, keeps zero separate from missing values, escapes text that starts with a formula character and only creates a new file.

```python
import csv,hashlib,json,pathlib,sys
source,target=map(pathlib.Path,sys.argv[1:3])
source_bytes=source.read_bytes();digest=hashlib.sha256(source_bytes).hexdigest()
r=json.loads(source_bytes)
if not isinstance(r,dict) or r.get("error") is not None or r.get("status")!="succeeded" or r.get("action")!="douyin.app.v3.fetch_one_video_by_share_url":
    raise ValueError("Expected successful share-link detail")
p=r.get("data",{}).get("aweme_detail")
if not isinstance(p,dict) or not p.get("aweme_id"):
    raise ValueError("No usable aweme_detail; inspect filter_list and request_id")
if not isinstance(r.get("request_id"),str) or not r["request_id"].strip():
    raise ValueError("Missing request_id")
if not isinstance(p["aweme_id"],str) or not p["aweme_id"].isascii() or not p["aweme_id"].isdigit() or not any(c!="0" for c in p["aweme_id"]):
    raise ValueError("aweme_id must be a digit string")
for field in ("desc","share_url"):
    if p.get(field) is not None and not isinstance(p[field],str):raise ValueError("Invalid text field: "+field)
if p.get("create_time") is not None and (type(p["create_time"]) is not int or not 0<=p["create_time"]<=9007199254740991):raise ValueError("Invalid publication timestamp")
stats=p.get("statistics")
if stats is None: stats={}
if not isinstance(stats,dict): raise ValueError("Invalid statistics")
for key in ["digg_count","comment_count","share_count","collect_count","play_count"]:
    value=stats.get(key)
    if value is not None and (type(value) is not int or not 0<=value<=9007199254740991):
        raise ValueError("Invalid counter: "+key)
def cell(v):
    if v is None:return ""
    s=str(v)
    return "'"+s if s.lstrip().startswith(("=","+","-","@")) else s
row=[p["aweme_id"],p.get("desc"),p.get("create_time"),p.get("share_url"),
     stats.get("digg_count"),stats.get("comment_count"),stats.get("share_count"),
     stats.get("collect_count"),stats.get("play_count"),r.get("request_id"),str(source.resolve()),digest]
with target.open("x",encoding="utf-8",newline="") as f:
    w=csv.writer(f)
    w.writerow(["aweme_id","caption","published_at","share_url","likes","comments","shares","collects","plays","request_id","source_file","source_sha256"])
    w.writerow([cell(v) for v in row])
print(p["aweme_id"])
```

## 4. Run and verify

```bash
python3 douyin_snapshot.py douyin-query-1/detail.json douyin-snapshot-1.csv
```

Check that the printed `aweme_id` matches the target video. The counters come from `statistics`: `digg_count`, `comment_count`, `share_count`, `collect_count` and `play_count`. `desc` is the caption text, not subtitles. `create_time` is the publication time; record the collection time separately.

## 5. Keep meaningful snapshots

Save the next collection under a new filename. Compare only snapshots of the same `aweme_id`, and only the counters both snapshots contain. Plays are not unique viewers, and `comment_count` does not prove that every comment can be retrieved. Keep the `request_id` and the original response; do not replace filtered results with zeroes, and do not overwrite earlier snapshots.

## 6. Turn saved posts into a delivery-review sheet

For an agreed creator-post delivery, engagement numbers alone do not confirm the intended creator or the required caption. Build an auditable review sheet from the saved details instead of buying every post again. Create `delivery-manifest.json` with each expected video ID and the creator's verified numeric uid, not the display name or sec_uid. `collected_at` is the original observation time, not the time you run the export.

Take the expected IDs from your agreed delivery roster or an independently verified creator record. Do not copy the returned author uid into the expected value to make the check pass. Replace every placeholder and the example time with your own recorded values.

```json
[
  {
    "file": "douyin-query-1/detail.json",
    "expected_aweme_id": "<verified_video_id>",
    "expected_author_uid": "<verified_author_uid>",
    "required_caption_phrase": "<agreed_caption_phrase>",
    "collected_at": "2026-11-16T10:00:00+08:00"
  }
]
```

Save the script below as `review_delivery.py`. The script reads local responses only, rejects a different video or a filtered detail, and leaves unknown metrics blank. The script reports an author mismatch or a missing caption phrase explicitly instead of accepting the delivery automatically.

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

manifest, target = map(Path, sys.argv[1:3])
entries = json.loads(manifest.read_text(encoding="utf-8"))
if not isinstance(entries, list) or not entries:
    raise SystemExit("Manifest must contain reviewed video records.")
rows, seen, requests = [], set(), set()
for entry in entries:
    expected = entry.get("expected_aweme_id")
    expected_author = entry.get("expected_author_uid")
    phrase = entry.get("required_caption_phrase")
    if not isinstance(expected, str) or not expected.isascii() or not expected.isdigit() or not any(c != "0" for c in expected) or expected in seen:
        raise SystemExit("Each expected_aweme_id must be a unique digit string.")
    if not isinstance(expected_author, str) or not expected_author.isascii() or not expected_author.isdigit() or not any(c != "0" for c in expected_author):
        raise SystemExit("expected_author_uid must be a verified digit string, not nickname/sec_uid.")
    if not isinstance(phrase, str) or not phrase.strip():
        raise SystemExit("Set the exact caption phrase you want to check.")
    collected = entry.get("collected_at")
    if not isinstance(collected, str):
        raise SystemExit("Record actual collected_at with timezone.")
    moment = datetime.fromisoformat(collected.replace("Z", "+00:00"))
    if moment.tzinfo is None:
        raise SystemExit("collected_at requires timezone.")
    source = manifest.parent / entry["file"]
    source_bytes = source.read_bytes(); digest = hashlib.sha256(source_bytes).hexdigest()
    raw = json.loads(source_bytes)
    if not isinstance(raw, dict) or raw.get("error") is not None or raw.get("status") != "succeeded" or raw.get("action") != "douyin.app.v3.fetch_one_video_by_share_url":
        raise SystemExit("Expected successful Douyin share-link detail.")
    request_id = raw.get("request_id")
    if not isinstance(request_id, str) or not request_id.strip() or request_id in requests:
        raise SystemExit("Each observation needs a distinct request_id.")
    post = raw.get("data", {}).get("aweme_detail")
    if not isinstance(post, dict) or post.get("aweme_id") != expected:
        raise SystemExit("Missing/filtered detail or aweme_id differs from the manifest.")
    author = post.get("author")
    if author is not None and not isinstance(author, dict):
        raise SystemExit("Invalid author object.")
    uid = (author or {}).get("uid")
    if uid is not None and (not isinstance(uid, str) or not uid.isascii() or not uid.isdigit() or not any(c != "0" for c in uid)):
        raise SystemExit("Invalid returned author uid.")
    caption = post.get("desc")
    if caption is not None and not isinstance(caption, str):
        raise SystemExit("Invalid caption.")
    if caption is not None and caption.strip() in {"[redacted]", "[redacted-depth]"}:
        caption = None
    author_check = "missing" if uid is None else ("match" if uid == expected_author else "mismatch")
    phrase_check = "missing" if caption is None else ("present" if phrase in caption else "absent")
    stats = post.get("statistics")
    if stats is not None and not isinstance(stats, dict):
        raise SystemExit("Invalid statistics.")
    counts = []
    for key in ["digg_count", "comment_count", "share_count", "collect_count", "play_count"]:
        value = (stats or {}).get(key)
        if value is not None and (type(value) is not int or not 0 <= value <= 9007199254740991):
            raise SystemExit(f"Invalid counter: {key}")
        counts.append(None if value is None else int(value))
    rows.append([expected, expected_author, uid, author_check, phrase, phrase_check, caption,
                 *counts, collected, entry["file"], request_id, digest, "", ""])
    seen.add(expected)
    requests.add(request_id)

def cell(value):
    if value is None:
        return ""
    value = str(value)
    return "'" + value if value.lstrip().startswith(("=", "+", "-", "@")) else value

with target.open("x", encoding="utf-8", newline="") as output:
    writer = csv.writer(output)
    writer.writerow(["aweme_id", "expected_author_uid", "actual_author_uid", "author_check", "required_caption_phrase", "phrase_check", "caption", "likes", "comments", "shares", "collects", "plays", "collected_at", "source_file", "request_id", "source_sha256", "review_decision", "review_reason"])
    writer.writerows([[cell(value) for value in row] for row in rows])
print(f"Wrote {len(rows)} delivery-review rows; no API calls made.")
```

```bash
python3 review_delivery.py delivery-manifest.json delivery-review.csv
```

Open the CSV with the ID columns imported as text. Check `author_check` and `phrase_check`, then fill in `review_decision` and `review_reason`. A caption can contain the required phrase while the video says something else, so watch the actual video before accepting brand claims, disclosure or product presentation. The review sheet is an operational check, not a legal compliance certification. The counters are observed totals, not campaign-attributed conversions or unique reach. An unavailable post stays an unresolved item, not a zero-performance delivery.

[Input ID](/faq/douyin-video-id) · [Video URLs](/faq/douyin-video-quality)

Sources: nine historical backend output samples and the current sanitized rendering; both scripts are verified offline.

Both exports include `source_sha256`, the hash of the exact saved response bytes. Keep the original responses with the CSV and the manifest. A hash identifies a local file; a hash is not a platform signature or proof of collection time. Counter values must be safe nonnegative JSON integers: floats, booleans and unsafe bare integers stop the export instead of being rounded into a precise-looking result. IDs must be original nonzero ASCII-digit strings. An existing collection directory blocks another request, and the local export never refreshes a post.

## Review plays and completion separately

For a tutorial retention review, fix the set of works and the observation window. Record plays when the regular snapshot returns `statistics.play_count`. For a Xingtu video report, pass the confirmed report item identifier as `item_id` to `douyin.xingtu_v2.get_item_report_detail`. The report's fixed completion field, unit and general coverage are unconfirmed, so record a completion value only when a report provides the metric and the metric's definition, together with the original value, window and source.

For example, if both tutorials have play counts and only one tutorial has a verified completion rate, compare plays and leave the other completion cell blank. Once both reports are available, align the dates and definitions. Use the lower reported completion to decide what to inspect, such as whether the introduction states the purpose or whether the demonstration has long pauses.