Track Accounts

Add tracked accounts

Adds new accounts to track for the organization. Already-tracked accounts are skipped unchanged (requested tags are still applied) and reported under alreadyTracked. A username-only entry is matched against the username the account had when tracking started, without a live lookup; pass platform_account_id when an old handle has since been taken over by a different account. Use the account update endpoints to change an existing account's limit. Validates against subscription limits and initiates data synchronization for newly added accounts. A request that would exceed the plan's tracked-account or tracked-video limit is refused with 402 PLAN_LIMIT_REACHED (not retryable; the error data names each meter's limit and by how much it would be exceeded). max_videos is clamped onto each platform's offered options — Snapchat supports only 10 or 30 (its public surface stops at the ~29 most recent Spotlights), so higher or unlimited values are stored as 30.

post/accounts/tracked

Request

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

Request body

isCompetitorboolean

Whether the tracked account is marked as a competitor

Example request

{
  "isCompetitor": false,
  "accounts": [
    {
      "platform": "tiktok",
      "username": "viral_creator",
      "max_videos": 100
    },
    {
      "platform": "instagram",
      "username": "fashion_influencer",
      "max_videos": 50
    },
    {
      "platform": "youtube",
      "username": "tech_reviewer",
      "max_videos": 30
    }
  ]
}

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).

alreadyTrackedCountnumber required

Example response

{
  "count": 2,
  "eventIds": [
    "01JGXKPQ9MNTV2R4W8KPMB5YT1",
    "01JGXKPQ9MNTV2R4W8KPMB5YT2"
  ],
  "syncRequestId": "sr_V1StGXR8Z5jdHi6BmyT2q",
  "accounts": [
    {
      "id": "org-account-id",
      "platform": "tiktok",
      "platformAccountId": "6829284838292",
      "maxVideos": 100
    }
  ],
  "alreadyTrackedCount": 1,
  "alreadyTracked": [
    {
      "id": "org-account-id-2",
      "platform": "tiktok",
      "platformAccountId": "6829284838293",
      "username": "viral_creator",
      "maxVideos": 999999999
    }
  ]
}

Changes

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