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",
  "creator_name": "MrBeast",
  "query": "@mkbhd",
  "platforms": [
    "youtube",
    "tiktok"
  ],
  "category_ids": [
    "technology",
    "ai_news_tools"
  ],
  "categories": [
    "gaming and esports",
    "AI tools"
  ],
  "min_followers": 10000,
  "max_followers": 5000000,
  "follower_bucket": [
    "10k_50k",
    "50k_100k"
  ],
  "cursor": "<string>",
  "creator_country": "US",
  "creator_language": "en"
}
'
{
  "results": [
    {
      "score": 0.5,
      "match_signals": [
        "<string>"
      ],
      "similarity_score": 0.5,
      "similarity_signals": [
        "<string>"
      ],
      "bio": {
        "status": "full_coverage",
        "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>",
                "specificity": "follower_bucket",
                "benchmark_date": "<string>",
                "content_category": {
                  "id": "<string>",
                  "name": "<string>"
                }
              },
              "avg_views": {
                "band": "bottom_25"
              },
              "avg_engagement_rate": {
                "band": "bottom_25"
              }
            }
          }
        }
      ],
      "associated_creators": [
        {
          "creator_id": "<string>",
          "creator_role": "surface"
        }
      ],
      "labels": [
        {
          "id": "<string>",
          "name": "<string>",
          "type": "category",
          "level": 1,
          "parent_id": "beauty"
        }
      ],
      "creator_id": "<string>",
      "skipped_enrichments": {
        "fields": [
          "bio"
        ],
        "reason": {
          "code": "<string>",
          "minimum_subscribers": 123,
          "platform": "<string>"
        }
      },
      "tags": [
        {
          "id": "<string>",
          "name": "<string>"
        }
      ],
      "audience": {
        "status": "full_coverage",
        "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>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.upriver.ai/llms.txt

Use this file to discover all available pages before exploring further.

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 stable 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"

​
creator_name
string | null

Creator name or brand to research.

Example:

"MrBeast"

​
query
string | null

General search query. Supports exact lookups (e.g. @mkbhd, youtube.com/@creator) and broad discovery queries (e.g. tech creators).

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, ai_news_tools).

Example:
["technology", "ai_news_tools"]
​
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
string | null

Optional creator country filter (ISO code when available).

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.