---
title: "Track a new Instagram or TikTok account for the caller."
method: POST
path: "/api/v1/followed-accounts"
tags: ["Followed Accounts"]
---

# Track a new Instagram or TikTok account for the caller.

`POST /api/v1/followed-accounts`

## Request

- Base URL: `https://api.avatarfactory.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.avatarfactory.io/api/v1/followed-accounts`
- Auth: one of:
  - API key in cookie `session`
  - HTTP bearer

<br/>Canonical create endpoint for the Followed Accounts page (Phase 2B,<br/>2026-05-25). Body shape: {platform, handle}. Real profile / follower<br/>enrichment is deferred to a background job and noted as a Phase 2B<br/>follow-up; the row is created with display_name = handle and<br/>follower_count = null until the enrichment worker runs.

## Request body

- TrackNewAccountRequest: Canonical create body for POST /api/v1/followed-accounts. Audit-spec shape (Phase 2B, 2026-05-25): platform + handle. The legacy /add route remains for backwards compat with the older template flow; new clients should call POST "" with this body.
  - `handle` string
  - `platform` string

## Response `201`

Created

- TrackedAccountResponse: Row representation returned by POST /api/v1/followed-accounts. Fields mirror what the list endpoint returns for the same row so the SPA can prepend the new row to its cache without an extra refetch. Real follower-count / profile-pic enrichment is deferred to a background job (Phase 2B follow-up).
  - `display_name` string, nullable
  - `follower_count` integer, nullable
  - `handle` string, required
  - `id` integer, required
  - `is_global` boolean
  - `is_shared` boolean
  - `last_synced_at` string, nullable
  - `platform` string, required
  - `profile_picture_url` string, nullable
  - `reels_indexed` integer, nullable

## Other responses

- `400`: Bad Request
- `409`: Conflict
- `422`: Unprocessable Entity

---

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