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.
Unified creator search for exact, broad, and filter-only queries.
Exact lookup: Provide creator_url (or an exact query) to quickly find the creator and linked channels.
Broad discovery: Provide query with optional filters (platforms, category_ids, follower_bucket, follower range, country/language).
Filter-only browse: Provide category_ids + follower_bucket without a text query to browse creators by category and size.
Pass next_cursor from any search response back as cursor with the same query and filters to fetch the next page.
Use the include query parameter for optional expansions. In /creators/search, include expansions are supported only for exact creator_url lookups.
Optional expansions to include in the response.
The same include options are available on GET /v1/creators (lookup by URL) and GET /v1/creators/{creator_id} (lookup by Upriver creator ID).
Include values and what each adds:
engagement_metrics: Recent per-channel engagement performance (average views, likes, comments, engagement rate). Returned as channels[].engagement_metrics.video_metrics: Per-channel upload cadence and duration-based inventory signals over a trailing 12-week window (YouTube). Returned as channels[].video_metrics.relative_metrics: Per-channel public benchmark summaries compared with similar creators. Returned as channels[].relative_metrics.bio: Creator summary and key context. Returned as top-level bio.audience: Directional audience demographics (age, gender, geography). Returned as top-level audience.brand_safety: Brand safety advisories with citations. Returned as top-level brand_safety.email: Public contact email addresses the creator has published for business inquiries, gathered across their linked channels. Returned as top-level emails.creator_id: Backward-compatible no-op; creator_id is always returned.Format:
?include=engagement_metrics&include=bio?include=engagement_metrics,bio/creators/search modes: include=email is available in every mode (broad query, filter-only browse, and exact creator_url), and may also be passed in the request body. The richer expansions (engagement_metrics, video_metrics, relative_metrics, bio, audience, brand_safety) are returned only for exact creator_url lookups; in broad/filter-only mode they are rejected — call /creators or /creators/{creator_id} to enrich a selected result.
Input payload for creator discovery.
Known social media URL for the creator.
Resolve a specific creator by handle or display name. Matches exactly, by prefix, and by fuzzy substring (e.g. 'beast' finds 'MrBeast'). For discovery, use the category/follower/platform filters instead.
Deprecated. Use name_or_handle.
Deprecated. Use name_or_handle for creator resolution.
Maximum number of creators to return, from 1 to 50.
Optional platform filter. Supported platforms: instagram, podcast, spotify, substack, tiktok, twitch, x, youtube (the alias twitter is accepted for x). Any other value returns a 400 error.
Optional category filter using taxonomy IDs (e.g. technology, tech_news_lifestyle).
Free-text category keywords to filter results by content category.
Optional approximate minimum based on recently observed follower counts.
Optional approximate maximum based on recently observed follower counts.
Approximate audience-size filter using recently observed follower counts.
Opaque cursor from a previous response for pagination.
curl https://api.upriver.ai/v1/creators/search \
--request POST \
--header 'Content-Type: application/json' \
--header 'X-API-Key: YOUR_SECRET_TOKEN' \
--data '{
"creator_url": "https://www.youtube.com/@MrBeast",
"name_or_handle": "MrBeast",
"limit": 10,
"platforms": [
"youtube",
"tiktok"
],
"category_ids": [
"technology",
"tech_news_lifestyle"
],
"categories": [
"gaming and esports",
"AI tools"
],
"min_followers": 10000,
"max_followers": 5000000,
"follower_bucket": [
"10k_50k",
"50k_100k"
],
"cursor": "",
"creator_country": [
"US"
],
"audience_country": [
"US"
],
"creator_language": "en",
"has_email": true,
"include": [
"email"
],
"content_query": "cozy gaming creators"
}'
{
"results": [
{
"score": 0,
"similarity_score": 0,
"similarity_signals": [
"string"
],
"bio": {
"status": "full_coverage",
"skip_reason": {
"code": "below_minimum_subscribers",
"minimum_subscribers": 1,
"platform": "string"
},
"summary": "MrBeast is a YouTube creator known for expensive stunts and philanthropy."
},
"channels": [
{
"platform": "string",
"handle": "string",
"url": "https://example.com",
"platform_id": "UCBcRF18a7Qf58cCRy5xuWwQ",
"display_name": "MrBeast",
"channel_relationship": "attached",
"profile_pic_url": "https://d111111abcdef8.cloudfront.net/creator-avatars/v1/...",
"subscriber_count": 4227,
"subscriber_count_text": "4.2K",
"follower_bucket": {
"id": "10k_50k",
"display": "10K-50K followers",
"min_followers": 10000,
"max_followers": 49999
},
"engagement_metrics": {
"avg_views": 125000,
"avg_likes": 5000,
"avg_comments": 500,
"avg_engagement_rate": 0.05
},
"video_metrics": {
"avg_duration_seconds": 615,
"lookback_weeks": 12,
"pct_over_8m": 66.7,
"uploads_per_week": 1.75,
"weeks_observed": 12,
"window_complete": true
},
"relative_metrics": {
"engagement": {
"benchmark_basis": {
"platform": "youtube",
"follower_bucket_id": "50k_100k",
"specificity": "follower_bucket",
"benchmark_date": "2026-03-17",
"content_category": "[Max Depth Exceeded]"
},
"avg_views": {
"band": "[Max Depth Exceeded]"
},
"avg_engagement_rate": {
"band": "[Max Depth Exceeded]"
}
}
}
}
],
"associated_creators": [
{
"creator_id": "cb4f53f0-c905-4c0a-86df-9a6c7551c408",
"creator_role": "surface"
}
],
"labels": [
{
"id": "sports",
"level": 1,
"name": "Sports",
"type": "category"
},
{
"id": "nfl",
"level": 2,
"name": "NFL",
"parent_id": "sports",
"type": "category"
}
],
"creator_id": "string",
"emails": [
"press@creator.com"
],
"skipped_enrichments": {
"fields": [
"bio"
],
"reason": {
"code": "below_minimum_subscribers",
"minimum_subscribers": 1,
"platform": "string"
}
},
"audience": {
"status": "full_coverage",
"skip_reason": {
"code": "below_minimum_subscribers",
"minimum_subscribers": 1,
"platform": "string"
},
"description": "Young female audience interested in comedy and lifestyle content.",
"gender": {
"value": "female",
"percentage": 72,
"confidence": "medium"
},
"age": {
"min_age": 13,
"max_age": 24,
"segments": [
{
"min_age": 13,
"max_age": 17,
"percentage": 45
}
],
"confidence": "medium"
},
"geography": {
"countries": [
{
"country": "US",
"country_name": "United States",
"percentage": 65
}
],
"international": true,
"confidence": "medium"
},
"languages": {
"value": "English",
"breakdown": [
{
"language": "English",
"percentage": 85
}
],
"confidence": "medium"
}
}
}
],
"next_cursor": "string"
}