---
title: "Add Creators to a Watchlist"
method: POST
path: "/api/v1/watchlists/profiles"
---

# Add Creators to a Watchlist

`POST /api/v1/watchlists/profiles`

## Request

- Base URL: `https://viraloutliers.com`
- URL: `https://viraloutliers.com/api/v1/watchlists/profiles`
- Auth: HTTP bearer

Adds creators to one of your watchlists. Pass profileIds (from search_profiles or any search result) and/or handles as {platform, handle} pairs; up to 25 per call. Creators must already be tracked (crawl_profile first if not; unresolved ones come back in notFound). Already-present creators are reported, not duplicated. Free to call. Each added creator counts against your followed-profiles allowance, which comes from a subscription or is earned from API spend; an over-limit call explains what unlocks more.

Cost: free.

## Request body

- object
  - `watchlistId` string, required: Target watchlist id.
  - `profileIds` string[]: Internal profile ids to add.
  - `handles` string: Handle pairs to resolve and add, e.g. [{"platform":"tiktok","handle":"x"}]. profileIds + handles ≤ 25 per call.

## Response `200`

Success

- object

## Other responses

- `401`: Invalid or revoked API key (or, on free skills, no key sent); code key_suspended means the key was suspended when its account was claimed by the email owner and can be reactivated in Settings
- `402`: Payment required. Without an API key (billable skills only) the code is payment_required and error.payment.checkoutUrl (or, when no link is configured, error.payment.pageUrl at https://viraloutliers.com/api-access) buys a key without an account; with a key it is insufficient_credits and error.payment points at create_topup_link.
- `429`: Rate limited

---

[API](https://skmtc.dev/viraloutliers/apis/viral-outliers-agent-api.md) · [All operations](https://skmtc.dev/viraloutliers/apis/viral-outliers-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/viraloutliers/apis/viral-outliers-agent-api/revisions/0099977bd629?raw)