Viral Outliers

Add Creators to a Watchlist by Id or Handle API

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.

Fill a watchlist with creators in batches of up to 25 per call, by internal profile id or simply by platform and handle. Unresolved handles come back in a notFound list (crawl_profile adds them to the database first), and creators already on the list are reported rather than duplicated. Free to call; each creator counts against your followed-profiles allowance.

Free

How to call it

POST /api/v1/watchlists/profiles. Authenticate with your API key. Same call in three languages:

cURL

curl -X POST "https://viraloutliers.com/api/v1/watchlists/profiles" \
  -H "Authorization: Bearer so_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"watchlistId":"example","profileIds":["tiktok"],"handles":"example"}'

Python (requests)

import requests

r = requests.post(
"https://viraloutliers.com/api/v1/watchlists/profiles",
    headers={"Authorization": "Bearer so_live_YOUR_KEY"},
    json={"watchlistId":"example","profileIds":["tiktok"],"handles":"example"},
)
print(r.json())

JavaScript (fetch)

const res = await fetch("https://viraloutliers.com/api/v1/watchlists/profiles", {
  method: "POST",
  headers: { "Authorization": "Bearer so_live_YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({"watchlistId":"example","profileIds":["tiktok"],"handles":"example"}),
});
const data = await res.json();
console.log(data);

Parameters

NameTypeDescription
watchlistId*stringTarget watchlist id.
profileIdsstring[]Internal profile ids to add.
handles{platform,handle}[]Handle pairs to resolve and add, e.g. [{"platform":"tiktok","handle":"x"}]. profileIds + handles ≤ 25 per call.

What it does

Resolves the identifiers you pass to tracked profiles, inserts the ones not already on the list, and returns added, alreadyPresent, notFound and the new profileCount. Handles are matched exactly on platform + handle, so an agent can go straight from a user's "@creator on tiktok" to a list entry without a search round-trip.

When to use it

Right after create_watchlist to populate it, or whenever the owner asks to track a new competitor. Batch up to 25 per call; for a longer list, page through in 25s. If a handle lands in notFound, call crawl_profile for it and add it again once the crawl completes.

Pricing

This skill is free and never spends credits.

Agent workflows

  • Build a set: search_profiles or a user-supplied handle list → add_watchlist_profiles in batches of 25 → search_outliers with watchlistId.

Frequently asked questions

Can I add creators by handle instead of id?

Yes. Pass handles as {platform, handle} pairs. Anything that is not yet tracked comes back in notFound; run crawl_profile for those and add them once crawled.

What does it cost to add many creators?

Nothing in credits. Each creator uses one slot of your followed-profiles allowance: 50 on Basic, 150 on Pro, unlimited on Agency, or the equivalent earned from API spend ($17, $37 or $149 of credits used within a 30-day window). Removing a creator frees the slot again, and an over-limit call tells you exactly what unlocks more.

Also available as an MCP tool.

Related topics: bulk add creators · watchlist by handle · competitor list building