A social insights API for ad generation platforms. It provides structured signals, like psychographics, behavioral insights, trends, and audience language, to help AI models generate relevant, higher-converting ads.
Find canonical creators who make content similar to an anchor creator.
Provide either a creator_id returned by another creator endpoint for similarity across that creator's eligible channel cluster, or a known channel_url for channel-specific similarity. Each result may qualify through one coherent channel expression; every channel in a creator cluster does not need to match. Default ordering emphasizes shared niche and subject plus specific profession or life-role identity, with reach used only to separate otherwise close peers. Optional platform, category, reach, and country controls constrain which peers may appear. An empty results list is a complete answer; incomplete_results is true only when an internal time budget truncated the evaluation and a retry may return more. The first returned channel is the channel that qualified each creator.
Beta: this endpoint is unlisted and its response shape may change without notice.
Input payload for canonical creator-peer discovery.
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.
Maximum number of similar creators to return, from 1 to 50.
Optional platform filter. Supported values are instagram, tiktok, and youtube. A matching result must have an eligible channel on at least one requested platform.
Optional category filter using exact taxonomy IDs. A matching channel may satisfy any supplied category.
Optional minimum follower/subscriber count filter.
Optional maximum follower/subscriber count filter.
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.
Optional creator IDs to exclude from similar results.
Creator API quota exceeded.
Other authentication or request error.
curl https://api.upriver.ai/v1/creators/similar \
--request POST \
--header 'Content-Type: application/json' \
--header 'X-API-Key: YOUR_SECRET_TOKEN' \
--data '{
"creator_id": "cb4f53f0-c905-4c0a-86df-9a6c7551c408",
"limit": 10
}'
{
"beta": "Beta: this endpoint is unlisted and its response shape may change without notice.",
"anchor": {
"scope": "creator",
"requested_creator_id": "d91b83e4-0e38-40dd-ad08-cbf1d2b2e947",
"creator_id": "cb4f53f0-c905-4c0a-86df-9a6c7551c408",
"requested_channel_url": null,
"channel_url": null
},
"ranking_version": "creator-peer-2026-07-13.7",
"results": [
{
"creator_id": "f1985b79-b891-40cc-b7af-df850e197f8d",
"name": "string",
"labels": [
"string"
],
"channel_count": 1,
"channels": [
{
"platform": "instagram",
"url": "https://example.com",
"handle": "@example",
"subscriber_count": 184000
}
],
"similarity": {
"reasons": [
{
"code": "shared_topics",
"values": [
"Consumer technology",
"Product reviews"
]
}
]
}
}
],
"incomplete_results": false
}