Viral Outliers

Create a Creator Watchlist for Scoped Outlier Searches API

Creates an empty watchlist (a named set of creators) and returns its watchlistId. Fill it with add_watchlist_profiles, then pass the id to search_outliers as watchlistId to scope any search to exactly those accounts. Watchlists created here appear in the owner's web app too. Free to call. Watchlists count against a workspace allowance that comes from a subscription or is earned from API spend (every API key holder starts with 1); an over-limit call explains what unlocks more.

Create a named set of creators once, then search only those accounts forever after with a single watchlistId filter on search_outliers. It is the building block for competitor monitoring, client rosters and niche shortlists: curate the set, and every search against it costs the same 1 credit as any other search, no matter how many creators it holds. Free to call.

Free

How to call it

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

cURL

curl -X POST "https://viraloutliers.com/api/v1/watchlists" \
  -H "Authorization: Bearer so_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"example","notes":"example"}'

Python (requests)

import requests

r = requests.post(
"https://viraloutliers.com/api/v1/watchlists",
    headers={"Authorization": "Bearer so_live_YOUR_KEY"},
    json={"name":"example","notes":"example"},
)
print(r.json())

JavaScript (fetch)

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

Parameters

NameTypeDescription
name*stringDisplay name, 1-80 characters (e.g. "Fitness competitors").
notesstringOptional free-text notes, up to 500 characters.

What it does

Returns a new, empty watchlist with its watchlistId, name, notes and timestamps. The id is the handle you pass to search_outliers (watchlistId) and to the other watchlist skills. Watchlists are shared objects: one an agent creates through the API shows up in the owner's web app, and one built in the web app can be used by the agent.

When to use it

Start any workflow that repeatedly searches the same set of accounts: a competitor set you check weekly, a client's own accounts plus rivals, or a shortlist of creators in a niche you are studying. Create the list, add profiles with add_watchlist_profiles (by id from search_profiles, or by platform and handle), then run search_outliers with watchlistId plus your usual filters.

Pricing

This skill is free and never spends credits.

Agent workflows

  • Competitor set: create_watchlist → add_watchlist_profiles → weekly search_outliers with watchlistId → brief on new outliers.

Frequently asked questions

How do I search only a specific set of creators through the API?

Create a watchlist with create_watchlist, add the creators with add_watchlist_profiles, then call search_outliers with the returned watchlistId. All other filters (time window, outlier score, views, sort) still apply on top.

Do watchlists created via the API show up in the web app?

Yes. They are the same objects. An agent-created watchlist appears in the owner's Watchlists page, and a watchlist built in the web app can be used by the agent via its id from list_watchlists.

Also available as an MCP tool.

Related topics: competitor watchlist API · creator list management · scoped social media search · competitor monitoring automation