UnityClaw Media Engagement Snapshot
Retrieve a structured snapshot for one public social-media post or video. Preserve platform values, localize labels, flag incomplete results, and save engagement.json in the task folder.
Agent Workflow
1. Confirm the content URL
Accept one public post or video URL per invocation. Do not pass a creator homepage, search page, private network address, or URL containing credentials. Use the content-specific form for the platform, such as a Xiaohongshu /explore/ link or TikTok /@user/video/ link. A Douyin user URL is accepted only when it contains a numeric vid query parameter; the CLI converts it to the canonical /video/{vid} request URL while preserving the original source URL.
Use this skill only for public content metrics. Do not bypass authentication, access private content, or infer sensitive traits about viewers or creators.
2. Execute the snapshot
Run scripts/generate.js with --json and an explicit --output-dir. Quote the URL and select --lang from the user's conversation language.
Fetch each content URL once. Allow the CLI to perform transient retries, but do not launch duplicate concurrent requests. For comparisons, capture every URL separately and retain its source URL and update fields.
3. Preserve metric meaning
Use data as the raw platform snapshot. Do not silently convert abbreviated values, round counts, replace missing fields with zero, or merge different metrics. Use localized fields only for presentation; every field retains its raw key.
Metrics are time-dependent and platform-specific. A play, view, collect, share, or like may be defined differently across platforms. Do not present cross-platform counts as directly equivalent without explaining this limitation.
4. Calculate ratios carefully
Do not label a number “engagement rate” without naming the formula and denominator. When the user requests analysis, calculate only from available raw fields and show the formula, for example:
visible interaction rate by plays = (likes + comments + collects + shares) / plays
This is a derived ratio, not a platform-certified metric. Do not calculate it when play_count is missing or zero. Never infer reach, unique viewers, conversions, audience authenticity, or campaign ROI from these counts alone.
5. Validate and deliver
Inspect missingCoreFields and warnings. The CLI warns when no engagement metric or content identity is returned, and when the platform is unrecognized. Accept completion only when success is true and resultPath points to a non-empty engagement.json.
Present requested fields in the user's language, identify the platform, retain the source URL, and distinguish raw values from any calculated ratios.
6. Handle failures deliberately
Retry only when error.retryable is true; respect the CLI retry limit. Correct invalid URLs and homepage/content-page mistakes before retrying. If content is deleted, private, region-restricted, or blocked by the platform, report that limitation instead of fabricating metrics.
Authorization
Provide the API key through the fixed UNITYCLAW_KEY environment variable. Obtain a key from UnityClaw if needed. The runtime installation declaration installs @unityclaw/sdk; for manual execution, run npm install @unityclaw/sdk when the package is unavailable.
Usage
node scripts/generate.js --url "https://www.xiaohongshu.com/explore/xxxx"
node scripts/generate.js --url "https://www.tiktok.com/@user/video/123456" --lang zh --json --output-dir ./tasks
node scripts/generate.js --url "https://www.douyin.com/user/example?vid=123456" --json
Parameters
| Parameter | Short | Required | Default | Description |
|---|---|---|---|---|
--url |
-u |
Yes | - | One public social-media post or video URL |
--lang |
-l |
No | auto |
Presentation-label language: auto, zh, en, or ja; locale variants are accepted |
--output-dir |
- | No | ./tasks |
Task output directory; resolved to an absolute path |
--timeout |
- | No | 900000 |
SDK request timeout in milliseconds, from 1,000 to 3,600,000 |
--retries |
- | No | 1 |
Retry count for transient failures, from 0 to 3 |
--json |
- | No | false |
Emit one machine-readable JSON result without progress output |
--help |
-h |
No | - | Show help |
Known Fields
| Raw key | Meaning |
|---|---|
author_name |
Public author name |
title |
Post or video title |
tag_text |
Tags returned by the platform |
play_count |
Plays or views under the platform's definition |
like_count |
Likes |
comment_count |
Comments |
collect_count |
Collections or saves |
share_count |
Shares |
duration |
Content duration |
created, updated |
Platform-provided time values |
cover |
Cover URL |
download_urls |
Download URL data when returned |
Extra fields returned by the service are preserved.
Output Contract
With --json, the command emits exactly one JSON object. A successful result contains task metadata, resultPath, resultBytes, original sourceUrl, normalized requestUrl, platform, language, raw data, localized fields, missingCoreFields, and warnings. The task folder contains engagement.json plus SDK request and response logs.
A failed result contains a stable error.code, human-readable error.message, error.retryable, attempts, and available task or log information. The process exits non-zero on failure.
Resource Index
- Run
scripts/generate.jsfor engagement retrieval.
