# Tiktok Posts Collect By Url

> Collect public TikTok post or video records, details, and metadata from one or more exact TikTok post URLs through Frevana, and continue status or result retrieval for tasks created by this operation. Use when exact video or post links are provided; do not use for discovery, profile-detail collection, or TikTok Ads management.

- Skill: `finpeakinc/tiktok-posts-collect-by-url` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx get-skill add finpeakinc/tiktok-posts-collect-by-url`
- Raw SKILL.md: https://api.skillmd.com/api/skills/finpeakinc/tiktok-posts-collect-by-url/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: finpeakinc (https://skillmd.com/u/finpeakinc)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/finpeakinc/tiktok-posts-collect-by-url

---


# TikTok Posts Collect by URL

Use this skill to collect public post records from one or more exact TikTok post URLs. The bundled script owns the complete create, poll, and raw-result flow.

## Required input

Every input object requires TikTok post `url`. Supply one to twenty objects through repeatable `--input-json` or one `--input-file` containing a JSON array.

Read [references/api.md](references/api.md) for all accepted fields and task states.

## Workflow

1. Confirm the exact user input; do not guess keywords or TikTok URLs.
2. Prefer `run` for creation through final raw result. Use `create`, `status`, `wait`, or `result` only when the caller needs separate phases.
3. Treat creation as billable. The script generates and reports a `client_task_id` when omitted. After a creation timeout or transport failure, retry only with that same ID; never submit a new task automatically.
4. Poll at the fixed ten-second interval. Stop without resubmitting on `FAILED`, `EXPIRED`, or `TRIGGER_UNKNOWN`.
5. Return result bytes unchanged. Do not wrap, reshape, merge, deduplicate, or associate records with inputs by result order or count.

## Commands

Resolve `{baseDir}` to the directory containing this `SKILL.md`.

```bash
# Complete flow
bash {baseDir}/scripts/tiktok_task.sh run \
  --input-json '{"url":"https://www.tiktok.com/@mrbeast/video/7553327774983802143","country":"US"}'

# Complete flow with a JSON array file and chosen output
bash {baseDir}/scripts/tiktok_task.sh run \
  --input-file ./inputs.json \
  --output ./out/tiktok-result.json

# Separate phases
bash {baseDir}/scripts/tiktok_task.sh create \
  --client-task-id caller-stable-id \
  --input-json '{"url":"https://www.tiktok.com/@mrbeast/video/7553327774983802143","country":"US"}'
bash {baseDir}/scripts/tiktok_task.sh status --task-id TASK_UUID
bash {baseDir}/scripts/tiktok_task.sh wait --task-id TASK_UUID
bash {baseDir}/scripts/tiktok_task.sh result --task-id TASK_UUID
```

`create --wait` is equivalent to `run`. Run the script with `--help` for all flags.

## Authentication and output

Use `FREVANA_TOKEN` or a one-time `--token` override. Never print the token. The default base URL is `https://ai-factory.frevana.com`; `FREVANA_API_BASE_URL` and `--api-base-url` support another Frevana deployment or local tests.

`create`, `status`, and `result` print the unchanged API JSON. `run`, `create --wait`, and `wait` save the raw final array under `./out/` by default and print the same bytes to stdout. Use `--output` to choose the file.

## Guardrails

- This skill fixes creation to `POST /service/tiktok/posts/collect-by-url`; do not route another TikTok operation through it.
- Do not combine `--input-file` with `--input-json`.
- `limit_per_input` is an optional request-level integer from 1 through 2147483647.
- The complete request must stay within 1 MB.
- The result is available only when `status=READY` and `billing_status=BILLED`; before that the result endpoint returns a task object.

