---
title: "Add tracked videos"
method: POST
path: "/videos/tracked"
tags: ["Track Individual Videos"]
---

# Add tracked videos

`POST /videos/tracked`

## Request

- Base URL: `https://viral.app/api/v1`
- URL: `https://viral.app/api/v1/videos/tracked`
- Auth: API key in header `x-api-key`

Adds new individual videos to track for the organization. Initiates data synchronization. Each video that is new to the organization counts against the plan's tracked-video limit; a request that would exceed it is refused with 402 `PLAN_LIMIT_REACHED` (not retryable; the error data names the limit and by how much it would be exceeded). Videos the organization already tracks are re-synced without consuming capacity. A video the organization excluded earlier and does not track now is un-excluded when added on an account with `maxVideos` 0 (individually tracked videos only); re-syncing an already tracked video leaves its exclusion as it is.

## Request body

- object: Request to add tracked videos for organization monitoring
  - `videos` union[], required: Social videos
    - union: Social video
      - object
        - `videoId` string, required: Native platform video id found in the URL of the video
        - `platform` 'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat', required: Social media platform (facebook, instagram, tiktok, youtube, snapchat)
        - `platform_account_id` string: Native platform account id
        - `initial_username` string: Username without leading @
        - `region` string, nullable: Region code (2-letter ISO country code)
        - `tiktokAdvancedScrapingEnabled` boolean
      - object
        - `platformVideoId` string, required: Native platform video id found in the URL of the video
        - `platform` 'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat', required: Social media platform (facebook, instagram, tiktok, youtube, snapchat)
        - `platform_account_id` string: Native platform account id
        - `initial_username` string: Username without leading @
        - `region` string, nullable: Region code (2-letter ISO country code)
        - `tiktokAdvancedScrapingEnabled` boolean
  - `isCompetitor` boolean: Whether the tracked account is marked as a competitor
  - `tags` union[]
    - union
      - object
        - `scope` 'system', required
        - `tagId` string, required: System tag ID with systag_ prefix
      - object
        - `scope` 'org', required
        - `tagId` string, required: Organization tag ID with orgtag_ prefix
      - object
        - `scope` 'project', required
        - `tagId` string, required: Organization project ID with orgproj_ prefix
  - `briefSample` boolean

## Response `200`

OK

- object: Result of adding tracked videos including count and sync job identifiers
  - `count` number, required
  - `eventIds` string[], required
  - `syncRequestId` string, nullable, required: The sync this request started. The `sync.completed` webhook reports it under this id (`sync.id`) once it is over, every item live or failed. Null when nothing was synced, or when viral.app could not record the sync for progress tracking (the sync still runs; no `sync.completed` follows).
  - `videos` object[], required
    - `id` string, required
    - `orgAccountId` string, required
    - `platform` string, required
    - `platformVideoId` string, required
    - `username` string, nullable, required
    - `wasExisting` boolean, required

## Other responses

- `400`: 400
- `401`: 401
- `402`: 402
- `404`: 404
- `408`: 408
- `429`: 429
- `500`: 500

---

[API](https://skmtc.dev/viral/apis/viral-app-api.md) · [All operations](https://skmtc.dev/viral/apis/viral-app-api/llms.txt) · [OpenAPI document](https://skmtc.dev/viral/apis/viral-app-api/revisions/31e97fa79ef1?raw)