Track Individual Videos

Add tracked videos

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.

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

Request body

isCompetitorboolean

Whether the tracked account is marked as a competitor

briefSampleboolean

Example request

{
  "videos": [
    {
      "videoId": "1487463749406225",
      "platform": "facebook"
    },
    {
      "videoId": "74567890689123456789001",
      "platform": "tiktok"
    },
    {
      "videoId": "C2VfGhIjKlM",
      "platform": "instagram"
    },
    {
      "videoId": "7w4uZc7xCzU",
      "platform": "youtube"
    }
  ],
  "isCompetitor": true
}

Response

OK

countnumber required
eventIdsstring[] required
syncRequestIdstring 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).

Example response

{
  "count": 1,
  "eventIds": [
    "01JGXKPQ9MNTV2R4W8KPMB5YT4"
  ],
  "syncRequestId": "sr_V1StGXR8Z5jdHi6BmyT2q",
  "videos": [
    {
      "id": "orgvid_1234567890ab",
      "orgAccountId": "orgacc_1234567890ab",
      "platform": "tiktok",
      "platformVideoId": "76891234567890012345678",
      "username": "creatorname",
      "wasExisting": false
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.