Skip to main content
POST
/
v1
/
creators
/
search
Search
curl --request POST \
  --url https://api.upriver.ai/v1/creators/search \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "creator_url": "https://www.youtube.com/@MrBeast",
  "name_or_handle": "MrBeast",
  "creator_name": "MrBeast",
  "query": "@mkbhd",
  "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": "<string>",
  "creator_country": [
    "US"
  ],
  "audience_country": [
    "US"
  ],
  "creator_language": "en"
}
'
{
  "results": [
    {
      "score": 0.5,
      "similarity_score": 0.5,
      "similarity_signals": [
        "<string>"
      ],
      "bio": {
        "skip_reason": {
          "code": "<string>",
          "minimum_subscribers": 123,
          "platform": "<string>"
        },
        "summary": "MrBeast is a YouTube creator known for expensive stunts and philanthropy."
      },
      "channels": [
        {
          "platform": "<string>",
          "handle": "<string>",
          "url": "<string>",
          "platform_id": "UCBcRF18a7Qf58cCRy5xuWwQ",
          "display_name": "MrBeast",
          "channel_relationship": "attached",
          "profile_pic_url": "https://yt3.ggpht.com/...",
          "subscriber_count": 4227,
          "subscriber_count_text": "4.2K",
          "follower_bucket": {
            "id": "<string>",
            "display": "<string>",
            "min_followers": 1,
            "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": "<string>",
                "follower_bucket_id": "<string>",
                "benchmark_date": "<string>",
                "content_category": {
                  "id": "<string>",
                  "name": "<string>"
                }
              },
              "avg_views": {},
              "avg_engagement_rate": {}
            }
          }
        }
      ],
      "associated_creators": [
        {
          "creator_id": "<string>"
        }
      ],
      "labels": [
        {
          "id": "<string>",
          "name": "<string>",
          "level": 1,
          "parent_id": "beauty"
        }
      ],
      "creator_id": "<string>",
      "skipped_enrichments": {
        "fields": [],
        "reason": {
          "code": "<string>",
          "minimum_subscribers": 123,
          "platform": "<string>"
        }
      },
      "tags": [
        {
          "id": "<string>",
          "name": "<string>"
        }
      ],
      "audience": {
        "skip_reason": {
          "code": "<string>",
          "minimum_subscribers": 123,
          "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": [
            {
              "percentage": 50,
              "min_age": 13,
              "max_age": 17
            }
          ],
          "confidence": "medium"
        },
        "geography": {
          "countries": [
            {
              "country": "<string>",
              "country_name": "United States",
              "percentage": 65
            }
          ],
          "international": true,
          "confidence": "medium"
        },
        "languages": {
          "value": "<string>",
          "breakdown": [
            {
              "language": "<string>",
              "percentage": 50
            }
          ],
          "confidence": "medium"
        }
      }
    }
  ],
  "next_cursor": "<string>"
}

Authorizations

​
X-API-Key
string
header
required

Query Parameters

​
include
string[]

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.
  • creator_id: Backward-compatible no-op; creator_id is always returned.

Format:

  • Repeat params: ?include=engagement_metrics&include=bio
  • CSV: ?include=engagement_metrics,bio

/creators/search constraint: include expansions are supported only for exact creator_url lookups. Broad query mode (query/creator_name without creator_url) returns lightweight results without expansions. Use /creators or /creators/{creator_id} to enrich a selected result.

Body

application/json

Input payload for creator discovery.

​
creator_url
string | null

Known social media URL for the creator.

Example:

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

​
name_or_handle
string | null

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.

Example:

"MrBeast"

​
creator_name
string | null
deprecated

Deprecated. Use name_or_handle.

Example:

"MrBeast"

​
query
string | null
deprecated

Deprecated. Use name_or_handle for creator resolution.

Example:

"@mkbhd"

​
platforms
string[] | null

Optional platform filter. Accepts API names (youtube, instagram, tiktok, x, etc.).

Example:
["youtube", "tiktok"]
​
category_ids
string[] | null

Optional category filter using taxonomy IDs (e.g. technology, tech_news_lifestyle).

Example:
["technology", "tech_news_lifestyle"]
​
categories
string[] | null

Free-text category keywords to filter results by content category.

Example:
["gaming and esports", "AI tools"]
​
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

​
follower_bucket
string[] | null

Follower count filter using bucket IDs.

Example:
["10k_50k", "50k_100k"]
​
cursor
string | null

Opaque cursor from a previous response for pagination.

​
creator_country

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.

Example:
["US"]
​
audience_country

Filter by where a creator's audience is located, as one or more ISO 3166-1 alpha-2 country codes. Matches creators whose known audience includes any of these countries, or who are themselves based in them.

Example:
["US"]
​
creator_language
string | null

Optional creator language filter.

Example:

"en"

Response

JSON object containing associated social profiles

Envelope returned by the creator search endpoint.

​
results
CreatorSearchResult · object[]

Ordered list of creator matches. The first result is the best canonical match when an exact creator exists.

​
next_cursor
string | null

Opaque cursor for fetching the next page of results. Null when no more results meet the quality threshold.