Skip to main content
POST

Authorizations

​
X-API-Key
string
header
required

Body

application/json

Input payload for canonical creator-peer discovery.

​
creator_id
string | null
required

Optional Upriver creator ID whose eligible channel cluster supplies the similarity anchor. Each returned creator may qualify through one coherent channel expression; every channel in either creator's cluster does not need to match. Provide exactly one of creator_id or channel_url. Reuse the creator_id returned by /v1/creators or /v1/creators/search.

Example:

"cb4f53f0-c905-4c0a-86df-9a6c7551c408"

​
channel_url
string<uri> | null

Optional known Instagram, TikTok, or YouTube profile URL used as a channel-specific similarity anchor. Provide exactly one of creator_id or channel_url.

Minimum string length: 1
Example:

"https://www.youtube.com/@example"

​
limit
integer
default:10

Maximum number of similar creators to return, from 1 to 50.

Required range: 1 <= x <= 50
​
platforms
string[] | null

Optional platform filter. Supported values are instagram, tiktok, and youtube. A matching result must have an eligible channel on at least one requested platform.

Maximum array length: 3
Example:
​
category_ids
string[] | null

Optional category filter using exact taxonomy IDs. A matching channel may satisfy any supplied category.

Maximum array length: 20
Example:
​
min_followers
integer | null

Optional minimum follower/subscriber count filter.

Required range: x >= 0
Example:

10000

​
max_followers
integer | null

Optional maximum follower/subscriber count filter.

Required range: x >= 0
Example:

5000000

​
creator_country
string | null

Filter by where creators are based, as one or more ISO 3166-1 alpha-2 country codes (e.g. US). Location coverage varies by platform, and not every creator has a known location.

Maximum string length: 20
Example:
​
match_content_language
boolean
default:false

When true, require the matching channel to share a material content language with the anchor creator.

​
exclude_creator_ids
string[] | null

Optional creator IDs to exclude from similar results.

Maximum array length: 100
Example:

Response

Ordered canonical creator peers with factual match reasons

Envelope returned by the similar-creators endpoint.

​
anchor
CreatorSimilarAnchor · object
required

Requested and canonical metadata for the similarity anchor.

​
ranking_version
string
required

Opaque version identifier for the ranking behavior.

Minimum string length: 1
Example:

"creator-peer-2026-07-13.7"

​
results
CreatorSimilarResult · object[]
required

Ordered list of creators similar to the requested anchor creator.

Maximum array length: 50
​
beta
string
default:Beta: this endpoint is unlisted and its response shape may change without notice.

Beta status caveat; the response shape may change without notice.