> ## 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.

# Find Similar Creators (Beta)

> 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, country, and shared-content-language controls constrain which peers may appear. The first returned channel is the channel that qualified each creator.

Beta: this endpoint is unlisted and its response shape may change without notice.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/creators/similar
openapi: 3.1.0
info:
  title: Upriver API
  description: >-
    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.
  version: 1.0.0
servers:
  - url: https://api.upriver.ai
    description: Production API server
security: []
tags:
  - name: Brands
  - name: Products
  - name: Creators
  - name: Audience
  - name: Sponsorships
  - name: Trends
  - name: Breakout Topics
  - name: Taxonomy
paths:
  /v1/creators/similar:
    post:
      tags:
        - Creators
      summary: Find Similar Creators (Beta)
      description: >-
        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, country, and shared-content-language controls constrain
        which peers may appear. The first returned channel is the channel that
        qualified each creator.


        Beta: this endpoint is unlisted and its response shape may change
        without notice.
      operationId: creator_similar_search
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatorSimilarInput'
            examples:
              by_creator_id:
                summary: By creator ID
                value:
                  creator_id: cb4f53f0-c905-4c0a-86df-9a6c7551c408
                  limit: 10
              by_channel_url:
                summary: By channel URL
                value:
                  channel_url: https://www.youtube.com/@example
                  platforms:
                    - youtube
                    - tiktok
                  limit: 10
        required: true
      responses:
        '200':
          description: Ordered canonical creator peers with factual match reasons
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatorSimilarResponse'
        '400':
          description: Invalid request or unsupported similarity platform.
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/CreatorSimilarErrorResponse'
                  - $ref: '#/components/schemas/CreatorSimilarValidationErrorResponse'
                title: Response 400 Creator Similar Search
              examples:
                invalid_fields:
                  summary: Request fields failed validation
                  value:
                    detail: Provide exactly one of creator_id or channel_url
                invalid_similarity_request:
                  summary: Invalid anchor or filter combination
                  value:
                    detail:
                      code: invalid_similarity_request
                      message: The similarity request is invalid.
                unsupported_platform:
                  summary: Unsupported result platform
                  value:
                    detail:
                      code: unsupported_platform
                      message: 'Unsupported platform(s): x.'
        '404':
          description: The requested creator or channel does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatorSimilarErrorResponse'
              examples:
                creator_not_found:
                  summary: Creator ID was not found
                  value:
                    detail:
                      code: creator_not_found
                      message: The requested creator was not found.
                channel_not_found:
                  summary: Channel URL was not found
                  value:
                    detail:
                      code: channel_not_found
                      message: The requested channel was not found.
        '409':
          description: >-
            The channel anchor is ambiguous, the creator does not yet have
            enough content evidence, or a requested content-language profile is
            not ready.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatorSimilarErrorResponse'
              examples:
                channel_anchor_ambiguous:
                  summary: Channel maps to multiple creator records
                  value:
                    detail:
                      code: channel_anchor_ambiguous
                      message: >-
                        The requested channel resolves to multiple creator
                        records.
                anchor_profile_not_ready:
                  summary: Content evidence is not ready
                  value:
                    detail:
                      code: anchor_profile_not_ready
                      message: >-
                        This creator does not yet have enough evidence for
                        similarity.
                anchor_language_not_ready:
                  summary: Language evidence is not ready
                  value:
                    detail:
                      code: anchor_language_not_ready
                      message: >-
                        This creator does not yet have a ready content-language
                        profile.
        '429':
          description: Creator API quota exceeded.
        '500':
          description: Unexpected creator-similarity failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatorSimilarErrorResponse'
              examples:
                similarity_internal_error:
                  summary: Unexpected server failure
                  value:
                    detail:
                      code: similarity_internal_error
                      message: Failed to find similar creators. Please try again later.
        '503':
          description: Creator similarity is temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatorSimilarErrorResponse'
              examples:
                similarity_unavailable:
                  summary: Similarity dependency is unavailable
                  value:
                    detail:
                      code: similarity_unavailable
                      message: Creator similarity is temporarily unavailable.
        4XX:
          description: Other authentication or request error.
      security:
        - APIKeyHeader: []
components:
  schemas:
    CreatorSimilarInput:
      oneOf:
        - required:
            - creator_id
          title: By creator ID
        - required:
            - channel_url
          title: By channel URL
      properties:
        creator_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Creator Id
          description: >-
            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`.
          examples:
            - cb4f53f0-c905-4c0a-86df-9a6c7551c408
        channel_url:
          anyOf:
            - type: string
              minLength: 1
              format: uri
            - type: 'null'
          title: Channel Url
          description: >-
            Optional known Instagram, TikTok, or YouTube profile URL used as a
            channel-specific similarity anchor. Provide exactly one of
            `creator_id` or `channel_url`.
          examples:
            - https://www.youtube.com/@example
        limit:
          type: integer
          maximum: 50
          minimum: 1
          title: Limit
          description: Maximum number of similar creators to return, from 1 to 50.
          default: 10
        platforms:
          anyOf:
            - items:
                type: string
              type: array
              maxItems: 3
            - type: 'null'
          title: Platforms
          description: >-
            Optional platform filter. Supported values are instagram, tiktok,
            and youtube. A matching result must have an eligible channel on at
            least one requested platform.
          examples:
            - - youtube
              - tiktok
        category_ids:
          anyOf:
            - items:
                type: string
              type: array
              maxItems: 20
            - type: 'null'
          title: Category Ids
          description: >-
            Optional category filter using exact taxonomy IDs. A matching
            channel may satisfy any supplied category.
          examples:
            - - technology
              - tech_news_lifestyle
        min_followers:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Min Followers
          description: Optional minimum follower/subscriber count filter.
          examples:
            - 10000
        max_followers:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Max Followers
          description: Optional maximum follower/subscriber count filter.
          examples:
            - 5000000
        creator_country:
          anyOf:
            - anyOf:
                - type: string
                - items:
                    type: string
                  type: array
              maxLength: 20
            - type: 'null'
          title: Creator Country
          description: >-
            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.
          examples:
            - - US
            - - US
              - GB
        match_content_language:
          type: boolean
          title: Match Content Language
          description: >-
            When true, require the matching channel to share a material content
            language with the anchor creator.
          default: false
        exclude_creator_ids:
          anyOf:
            - items:
                type: string
              type: array
              maxItems: 100
            - type: 'null'
          title: Exclude Creator Ids
          description: Optional creator IDs to exclude from similar results.
          examples:
            - - 72f3a038-b304-49ea-9048-c17bf31f52d1
      additionalProperties: false
      type: object
      title: CreatorSimilarInput
      description: Input payload for canonical creator-peer discovery.
    CreatorSimilarResponse:
      properties:
        beta:
          type: string
          title: Beta
          description: Beta status caveat; the response shape may change without notice.
          default: >-
            Beta: this endpoint is unlisted and its response shape may change
            without notice.
        anchor:
          $ref: '#/components/schemas/CreatorSimilarAnchor'
          description: Requested and canonical metadata for the similarity anchor.
        ranking_version:
          type: string
          minLength: 1
          title: Ranking Version
          description: Opaque version identifier for the ranking behavior.
          examples:
            - creator-peer-2026-07-13.7
        results:
          items:
            $ref: '#/components/schemas/CreatorSimilarResult'
          type: array
          maxItems: 50
          title: Results
          description: Ordered list of creators similar to the requested anchor creator.
      type: object
      required:
        - anchor
        - ranking_version
        - results
      title: CreatorSimilarResponse
      description: Envelope returned by the similar-creators endpoint.
    CreatorSimilarErrorResponse:
      properties:
        detail:
          $ref: '#/components/schemas/CreatorSimilarErrorDetail'
      type: object
      required:
        - detail
      title: CreatorSimilarErrorResponse
      description: Error envelope returned by the similar-creators endpoint.
    CreatorSimilarValidationErrorResponse:
      properties:
        detail:
          type: string
          minLength: 1
          title: Detail
          description: Human-readable request validation error.
          examples:
            - Provide exactly one of creator_id or channel_url
      type: object
      required:
        - detail
      title: CreatorSimilarValidationErrorResponse
      description: Field-validation error returned before similarity execution begins.
    CreatorSimilarAnchor:
      oneOf:
        - properties:
            scope:
              const: creator
            requested_channel_url:
              type: 'null'
            channel_url:
              type: 'null'
          required:
            - scope
            - requested_creator_id
            - creator_id
        - properties:
            scope:
              const: channel
            requested_creator_id:
              type: 'null'
          required:
            - scope
            - creator_id
            - requested_channel_url
            - channel_url
      properties:
        scope:
          type: string
          enum:
            - creator
            - channel
          title: Scope
          description: >-
            Whether similarity used the creator's eligible channel cluster or
            one specific channel as its evidence anchor. A creator-scoped result
            may qualify through one coherent channel expression.
        requested_creator_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Requested Creator Id
          description: >-
            The creator ID supplied in a creator-scoped request. Omitted for a
            channel-scoped request.
          examples:
            - d91b83e4-0e38-40dd-ad08-cbf1d2b2e947
        creator_id:
          type: string
          title: Creator Id
          description: The current canonical creator ID used for similarity.
          examples:
            - cb4f53f0-c905-4c0a-86df-9a6c7551c408
        requested_channel_url:
          anyOf:
            - type: string
              minLength: 1
              format: uri
            - type: 'null'
          title: Requested Channel Url
          description: >-
            The profile URL supplied in a channel-scoped request. Omitted for a
            creator-scoped request.
          examples:
            - https://youtube.com/@example
        channel_url:
          anyOf:
            - type: string
              minLength: 1
              format: uri
            - type: 'null'
          title: Channel Url
          description: >-
            The canonical stored profile URL used for channel-scoped similarity.
            Omitted for a creator-scoped request.
          examples:
            - https://www.youtube.com/@example
      type: object
      required:
        - scope
        - creator_id
      title: CreatorSimilarAnchor
      description: Requested and resolved identity for a similarity search.
    CreatorSimilarResult:
      properties:
        creator_id:
          type: string
          title: Creator Id
          description: Canonical Upriver creator ID.
          examples:
            - f1985b79-b891-40cc-b7af-df850e197f8d
        name:
          type: string
          minLength: 1
          title: Name
          description: Creator display name.
        labels:
          items:
            type: string
          type: array
          maxItems: 5
          title: Labels
          description: Human-readable category, topic, identity, and profession labels.
        channel_count:
          type: integer
          minimum: 1
          title: Channel Count
          description: >-
            Number of active owned Instagram, TikTok, and YouTube channels for
            the creator, including channels omitted from this lean response.
        channels:
          items:
            $ref: '#/components/schemas/CreatorSimilarChannel'
          type: array
          maxItems: 3
          minItems: 1
          title: Channels
          description: >-
            Ordered owned channels. The first entry is the channel that
            qualified the creator for this request.
        similarity:
          $ref: '#/components/schemas/CreatorSimilarity'
          description: Factual evidence supporting this creator-peer result.
      type: object
      required:
        - creator_id
        - name
        - channel_count
        - channels
        - similarity
      title: CreatorSimilarResult
      description: Lean canonical creator returned by creator-peer discovery.
    CreatorSimilarErrorDetail:
      properties:
        code:
          type: string
          minLength: 1
          title: Code
          description: Stable error code suitable for programmatic handling.
          examples:
            - creator_not_found
        message:
          type: string
          minLength: 1
          title: Message
          description: Human-readable description of the error.
          examples:
            - The requested creator was not found.
      type: object
      required:
        - code
        - message
      title: CreatorSimilarErrorDetail
      description: Stable machine-readable creator-similarity error.
    CreatorSimilarChannel:
      properties:
        platform:
          type: string
          enum:
            - instagram
            - tiktok
            - youtube
          title: Platform
          description: Platform for this owned creator channel.
        url:
          type: string
          minLength: 1
          format: uri
          title: Url
          description: Canonical profile URL for the channel.
        handle:
          anyOf:
            - type: string
            - type: 'null'
          title: Handle
          description: Canonical public handle when available.
          examples:
            - '@example'
        subscriber_count:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Subscriber Count
          description: Most recently known follower or subscriber count.
          examples:
            - 184000
      type: object
      required:
        - platform
        - url
      title: CreatorSimilarChannel
      description: Lean owned-channel reference returned for a similar creator.
    CreatorSimilarity:
      properties:
        reasons:
          items:
            $ref: '#/components/schemas/CreatorSimilarityReason'
          type: array
          maxItems: 3
          minItems: 1
          title: Reasons
          description: Ordered factual reasons supporting the creator match.
      type: object
      required:
        - reasons
      title: CreatorSimilarity
      description: Evidence supporting one creator-peer result.
    CreatorSimilarityReason:
      properties:
        code:
          type: string
          minLength: 1
          title: Code
          description: >-
            Stable reason code. The vocabulary is extensible; clients should
            ignore codes they do not recognize.
          examples:
            - shared_topics
        values:
          items:
            type: string
          type: array
          maxItems: 3
          minItems: 1
          title: Values
          description: Human-readable values supporting this reason.
          examples:
            - - Consumer technology
              - Product reviews
      type: object
      required:
        - code
        - values
      title: CreatorSimilarityReason
      description: Factual display evidence explaining a similarity result.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key

````