---
title: "Track Video"
method: POST
path: "/api/videos/track"
tags: ["Video Tracking"]
---

# Track Video

`POST /api/videos/track`

## Request

- Base URL: `https://api.kolens.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.kolens.ai/api/videos/track`
- Auth: HTTP bearer

Start tracking a published TikTok video.

Idempotent on ``(user, platform, video_id)``: re-tracking the same video
returns (and re-activates) the existing row. A best-effort first capture
runs inline so the growth curve has a t0 point when Apify is configured;
on failure (or when ``APIFY_API_TOKEN`` is unset) the row is left
immediately due so the scheduler captures on its next tick.

## Headers

- `x-kolens-user-id` string, nullable
- `x-kolens-workspace-id` string, nullable
- `x-kolens-locale` string, nullable

## Request body

- TrackVideoRequest
  - `url` string, required: TikTok video URL, Instagram reel/post URL, a vt.tiktok.com short link, or the whole share message — we extract the link.
  - `label` string: 'own' (your collab) | 'competitor'
  - `note` string, nullable
  - `cadence_hours` integer, nullable: Refresh cadence; defaults to 24h

## Response `201`

Successful Response

- TrackedVideoOut
  - `id` string, required
  - `video_id` string, required
  - `video_url` string, required
  - `platform` string, required
  - `label` string, required
  - `note` string, nullable, required
  - `author_username` string, nullable, required
  - `cadence_hours` integer, required
  - `is_active` boolean, required
  - `last_refreshed_at` string, date-time, nullable, required
  - `next_refresh_at` string, date-time, nullable, required
  - `last_error` string, nullable, required
  - `created_at` string, date-time, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/kolens/apis/kolens-api.md) · [All operations](https://skmtc.dev/kolens/apis/kolens-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kolens/apis/kolens-api/revisions/5d6865ab0a24?raw)