---
title: "Add tracked accounts"
method: POST
path: "/accounts/tracked"
tags: ["Track Accounts"]
---

# Add tracked accounts

`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`

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.

## Request body

- object: Request to add tracked accounts for external API access
  - `accounts` object[], required: Social accounts to track
    - `platform` 'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat', required: Social media platform (facebook, instagram, tiktok, youtube, snapchat)
    - `username` string, required: Username without leading @
    - `max_videos` union, required: Video tracking limit for an account. Allowed values: 0, 10, 30, 60, 100, 200, 300, 400, 500, 1000, 2000, 999999999. Use 0 to pause tracking: nothing syncs for the account until a limit is set again (resume), and its existing videos stay available; pausing requires the Data Retention plan feature. Finite values (10, 30, 60, 100, 200, 300, 400, 500, 1000, 2000) sync that many latest videos and are subject to plan limits. Use 999999999 for unlimited account video tracking; this requires the Unlimited Video Tracking plan feature.
      - unknown
      - unknown
      - unknown
      - unknown
      - unknown
      - unknown
      - unknown
      - unknown
      - unknown
      - unknown
      - unknown
      - unknown
    - `platform_account_id` string: Native platform account id
    - `region` string, nullable: Region code (2-letter ISO country code)
  - `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

## Response `200`

OK

- object: Result of adding tracked accounts: newly queued accounts (count, sync job identifiers, inserted records) and already-tracked accounts that were skipped unchanged
  - `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).
  - `accounts` object[], required
    - `id` string, required
    - `platform` 'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat', required: Social media platform (facebook, instagram, tiktok, youtube, snapchat)
    - `platformAccountId` string, required: Native platform account id
    - `maxVideos` union, required
      - unknown
      - unknown
      - unknown
      - unknown
      - unknown
      - unknown
      - unknown
      - unknown
      - unknown
      - unknown
      - unknown
      - unknown
  - `alreadyTrackedCount` number, required
  - `alreadyTracked` object[], required
    - `id` string, required
    - `platform` 'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat', required: Social media platform (facebook, instagram, tiktok, youtube, snapchat)
    - `platformAccountId` string, required: Native platform account id
    - `username` string, required
    - `maxVideos` number, 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)