01 How it works
You hand us a list of creators you like. We look at what they post, find creators who post the same kind of thing, and rank them. That's the whole idea.
Every request needs Authorization: Bearer <API_KEY> — any authenticated client key, not admin-only. Each route is scoped to your client and the model_id; another client's model or run returns 404, never leaks.
TikTok or Instagram. Set platform on the run — it defaults to tiktok. TikTok and Instagram runs never mix seeds or results. Instagram has one important caveat — see Instagram notes.
02 What "seeds" are
seed creators — the creators you submit. The recommendation grows out of them like seeds, so they define the taste you're targeting.
You give 10–30 of them. Ten is the floor, so there's enough signal to spot a pattern; thirty is the ceiling, so the taste stays focused instead of muddy. In the request body this list is the seed_creators field.
Better seeds mean better suggestions: pick creators that genuinely represent the lane you want more of. Your seeds themselves — and creators the model already follows — never appear in the results.
03 The run lifecycle
A run is a background job, so you don't get results instantly. POST hands you a run_id right away — a ticket. Then you poll until it's done.
recommendations and inferred_niche are filled in.Poll GET until status is terminal:
04 Create a run
202 with a run_id and poll_url. Rate limit: 10 / minute.
# create a run from 10–30 seed handles
curl -s -X POST "https://api.metrix.ac/api/v1/models/{model_id}/recommendations" \
-H "Authorization: Bearer $TM_API_KEY" -H "Content-Type: application/json" \
-d '{"platform":"instagram","seed_creators":["chef.reactions","...10 to 30 handles..."],"limit":50}'| Field | Type | Notes |
|---|---|---|
seed_creators | string[] | Required. 10–30 handles. With or without leading @; case-insensitive. Duplicate spellings collapse. Invalid handles are kept and echoed as status: "invalid", never silently dropped. |
platform | enum | Optional, default tiktok. One of tiktok, instagram. Instagram seeds are scored against Instagram data only — read the Instagram notes first. |
limit | int | Optional, default 50, range 1–100. Max ranked results. |
05 Poll a run
curl -s "https://api.metrix.ac/api/v1/models/{model_id}/recommendations/{run_id}" \
-H "Authorization: Bearer $TM_API_KEY"{
"status": "ready",
"seed_status": { "valid": 10, "usable": 8, "empty": 1, "error": 1 },
"inferred_niche": { "hashtags": ["cooking","recipes"], "sounds": ["7123…"] },
"recommendations": [
{ "creator_id": "homecookhannah", "rank": 1, "score": 12.34 },
{ "creator_id": "onepanwonders", "rank": 2, "score": 9.80 }
]
}empty means the seed genuinely has no videos we can see; error means it couldn't be fetched this time and is retryable — they're kept distinct on purpose. inferred_niche is null until the run is terminal.
06 Feedback — teach the next run
Thumbs-up the good matches and thumbs-down the bad ones. This doesn't change the list you're looking at — it's memory that makes your next run smarter.
201. Append-only — the latest action per creator wins. No rate limit.
curl -s -X POST "https://api.metrix.ac/api/v1/models/{model_id}/recommendations/{run_id}/feedback" \
-H "Authorization: Bearer $TM_API_KEY" -H "Content-Type: application/json" \
-d '{"entity_id":"homecookhannah","value":"up"}'| value | Effect on your next run |
|---|---|
up | Strong boost — pushes this creator (and similar) higher. |
save | Mild boost. |
down | Excluded from ranking entirely. |
hide | Same — banned from future results. |
An up later flipped to down resolves to down — latest wins. Feedback is remembered per model, across every future run.
07 Instagram notes
Set "platform": "instagram" on the run to seed and rank Instagram creators instead of TikTok. The flow — create → poll → feedback — and every response shape are identical; only the data source changes. Two things differ in kind:
Instagram matching is hashtag-graph similarity only. Creators are matched on the hashtags in their recent captions. On TikTok we also use shared trending sounds — the single tightest niche signal there — but cross-creator audio reuse is far rarer on Instagram, so sound overlap contributes ~nothing. Results are credible for niche placement, weaker on fine content-style affinity. (inferred_niche.sounds is usually empty for Instagram.)
Instagram seeds are crawled on demand. We don't hold a broad standing corpus of Instagram posts the way we do for TikTok, so a fresh seed's first run spends longer in waiting_for_crawls while we fetch its posts — and, for a niche no one has seeded before, briefly harvest that niche so there are creators to rank against. Poll a little longer than you would for TikTok.
Everything else is the same: the same seed_status buckets, partial_ready semantics, and feedback values all carry over unchanged.
08 What's next
Today a run starts from creator handles only — that's all the POST body accepts. Hashtags and search terms aren't seed inputs yet.
They're a natural next step — a future version could accept seed_hashtags and seed_keywords to sharpen the niche. Until then, seed with creators and lean on feedback to refine.