> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topyappers.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Creators (v1)

> Returns full creator profiles matching filters. Query parameters are identical to GET /api/v2/creators/search (search is free and returns IDs only; this endpoint costs credits per creator returned).



## OpenAPI

````yaml GET /api/v1/creators
openapi: 3.1.0
info:
  title: Creators API
  description: >-
    Creators API — v1 GET and v2 search share the same query parameters (posting
    cadence, average video duration, monetization post counts, demographics,
    etc.). Creator objects in responses use **snake_case** keys (see `Creator`
    schema).
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.topyappers.com
security:
  - apiKeyAuth: []
paths:
  /api/v1/creators:
    get:
      summary: Get creators (v1)
      description: >-
        Returns full creator profiles matching filters. Query parameters are
        identical to GET /api/v2/creators/search (search is free and returns IDs
        only; this endpoint costs credits per creator returned).
      parameters:
        - name: followersMin
          in: query
          description: Minimum number of followers
          schema:
            type: integer
          example: 10000
        - name: followersMax
          in: query
          description: Maximum number of followers
          schema:
            type: integer
          example: 1000000
        - name: averageViewsMin
          in: query
          description: Minimum average views per post
          schema:
            type: integer
          example: 5000
        - name: averageViewsMax
          in: query
          description: Maximum average views per post
          schema:
            type: integer
          example: 500000
        - name: averageLikesMin
          in: query
          description: Minimum average likes per post
          schema:
            type: integer
          example: 100
        - name: averageLikesMax
          in: query
          description: Maximum average likes per post
          schema:
            type: integer
          example: 50000
        - name: engagementRateMin
          in: query
          description: >-
            Minimum engagement rate (percentage). 1-3% average, 3-6% good, 6%+
            excellent
          schema:
            type: number
            format: float
          example: 2.5
        - name: engagementRateMax
          in: query
          description: Maximum engagement rate (percentage)
          schema:
            type: number
            format: float
          example: 10
        - name: uploadsPerWeekMin
          in: query
          description: >-
            Minimum average posts per week (posting cadence). Omit or use 0 for
            no lower bound.
          schema:
            type: number
            format: float
          example: 3
        - name: uploadsPerWeekMax
          in: query
          description: Maximum average posts per week. Omit or use 0 for no upper bound.
          schema:
            type: number
            format: float
          example: 14
        - name: uploadsPerMonthMin
          in: query
          description: Minimum average posts per month. Omit or use 0 for no lower bound.
          schema:
            type: number
            format: float
          example: 10
        - name: uploadsPerMonthMax
          in: query
          description: Maximum average posts per month. Omit or use 0 for no upper bound.
          schema:
            type: number
            format: float
          example: 60
        - name: avgVideoDurationSecondsMin
          in: query
          description: >-
            Minimum average video duration in seconds. Omit or use 0 for no
            lower bound.
          schema:
            type: number
            format: float
          example: 15
        - name: avgVideoDurationSecondsMax
          in: query
          description: >-
            Maximum average video duration in seconds. Omit or use 0 for no
            upper bound.
          schema:
            type: number
            format: float
          example: 120
        - name: promotionsCountMin
          in: query
          description: >-
            Minimum count of promotion-type posts in the analyzed sample. Omit
            or use 0 for no lower bound.
          schema:
            type: integer
          example: 1
        - name: promotionsCountMax
          in: query
          description: Maximum promotion posts count. Omit or use 0 for no upper bound.
          schema:
            type: integer
          example: 50
        - name: affiliatePostsCountMin
          in: query
          description: >-
            Minimum count of affiliate-linked posts. Omit or use 0 for no lower
            bound.
          schema:
            type: integer
          example: 0
        - name: affiliatePostsCountMax
          in: query
          description: Maximum affiliate posts count. Omit or use 0 for no upper bound.
          schema:
            type: integer
          example: 20
        - name: sponsorshipPostsCountMin
          in: query
          description: Minimum count of sponsored posts. Omit or use 0 for no lower bound.
          schema:
            type: integer
          example: 0
        - name: sponsorshipPostsCountMax
          in: query
          description: Maximum sponsored posts count. Omit or use 0 for no upper bound.
          schema:
            type: integer
          example: 30
        - name: age
          in: query
          description: Age group (comma-separated for multiple)
          schema:
            type: string
            enum:
              - 0-9
              - 10-19
              - 20-29
              - 30-39
              - 40-49
              - 50-59
              - 60-69
              - 70-79
              - 80-89
              - 90-99
          example: 20-29,30-39
        - name: gender
          in: query
          description: Gender filter
          schema:
            type: string
            enum:
              - male
              - female
          example: female
        - name: race
          in: query
          description: Ethnicity filter (comma-separated for multiple)
          schema:
            type: string
            enum:
              - White
              - Black
              - Indian
              - East Asian
              - Southeast Asian
              - Middle Eastern
              - Latino Hispanic
          example: East Asian,Southeast Asian
        - name: hairColor
          in: query
          description: Hair color filter (comma-separated for multiple)
          schema:
            type: string
            enum:
              - Blonde hair
              - Brunette hair
              - Black hair
              - Red hair
              - White hair
          example: Blonde hair,Black hair
        - name: bodyComplexion
          in: query
          description: Body type / build filter (comma-separated for multiple)
          schema:
            type: string
            enum:
              - Skinny
              - Ordinary
              - Overweight
              - Hulk
          example: Skinny,Ordinary
        - name: mainCategory
          in: query
          description: Main content category
          schema:
            type: string
            enum:
              - Arts
              - Automotive
              - Beauty & Personal Care
              - Books & Literature
              - Business
              - Finance
              - Career & Jobs
              - Collectibles & Hobbies
              - Community
              - Ecommerce
              - Crafts & DIY
              - Culture
              - Education
              - Technology
              - Entertainment
              - Environment
              - Family
              - Parenting
              - Fashion
              - Film
              - Fitness
              - Health
              - Food
              - Gaming
              - Gardening & Agriculture
              - History
              - Home
              - Humor
              - Law
              - Government
              - Lifestyle
              - Marketing
              - Mental Health
              - Music
              - News & Media
              - Outdoors
              - Nature
              - Pets
              - Animals
              - Philosophy
              - Spirituality
              - Photography
              - Videography
              - Politics
              - Relationships
              - Religion
              - Science
              - Self-Improvement
              - Shopping
              - Social Media
              - Social Issues & Activism
              - Sports
              - Travel
              - Vehicles & Transportation
              - Virtual Reality
              - Weapons & Defense
              - Writing
              - Kids
          example: Fashion
        - name: subCategory
          in: query
          description: Sub-category of content (free text search)
          schema:
            type: string
          example: streetwear
        - name: bio
          in: query
          description: Keywords in creator's bio
          schema:
            type: string
          example: tiktok shop
        - name: promotedProducts
          in: query
          description: >-
            Products/services promoted by the creator (comma-separated for
            multiple)
          schema:
            type: string
          example: beef tallow,feastables
        - name: nichesToPromote
          in: query
          description: Suggested niches to promote (comma-separated for multiple)
          schema:
            type: string
          example: fashion,streetwear
        - name: country
          in: query
          description: Creator's country (full name)
          schema:
            type: string
          example: France
        - name: source
          in: query
          description: Platform / data source
          schema:
            type: string
            enum:
              - tiktok
              - instagram
              - youtube
          example: tiktok
        - name: accountType
          in: query
          description: Creator account type
          schema:
            type: string
            enum:
              - faceless
              - ugc
              - agc
              - clipper
              - brand
          example: ugc
        - name: username
          in: query
          description: Filter creators by their handle
          schema:
            type: string
          example: creator_handle
        - name: language
          in: query
          description: Primary content language (lowercase)
          schema:
            type: string
            enum:
              - arabic
              - bengali
              - bosnian
              - bulgarian
              - cantonese
              - catalan
              - croatian
              - czech
              - danish
              - dutch
              - english
              - estonian
              - filipino
              - finnish
              - french
              - german
              - greek
              - gujarati
              - hausa
              - hebrew
              - hindi
              - hungarian
              - icelandic
              - indonesian
              - italian
              - japanese
              - javanese
              - kannada
              - kazakh
              - korean
              - latvian
              - lithuanian
              - malay
              - malayalam
              - mandarin
              - marathi
              - nepali
              - norwegian
              - pashto
              - persian
              - polish
              - portuguese
              - punjabi
              - romanian
              - russian
              - serbian
              - sinhala
              - slovak
              - slovenian
              - somali
              - spanish
              - swahili
              - swedish
              - tamil
              - telugu
              - thai
              - turkish
              - ukrainian
              - urdu
              - uzbek
              - vietnamese
              - yoruba
          example: english
        - name: hashtags
          in: query
          description: >-
            Filter by hashtags used in creator content (comma-separated). AND
            matching — all must be present. '#' prefix is optional
          schema:
            type: string
          example: fitness,gym
        - name: emailExists
          in: query
          description: Filter creators with available email
          schema:
            type: boolean
          example: true
        - name: email
          in: query
          description: Find creator by email
          schema:
            type: string
            format: email
          example: creator@example.com
        - name: sortBy
          in: query
          description: 'Field to sort results by. Default: date_created (newest first)'
          schema:
            type: string
            enum:
              - date_created
              - followers
              - engagement_rate
              - avg_views
              - avg_likes
              - avg_comments
          example: date_created
        - name: sortOrder
          in: query
          description: 'Sort direction. Default: desc (highest/newest first)'
          schema:
            type: string
            enum:
              - asc
              - desc
          example: desc
        - name: page
          in: query
          description: Page number for pagination
          schema:
            type: integer
            minimum: 1
          example: 1
        - name: perPage
          in: query
          description: Number of results per page (max 100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
          example: 10
      responses:
        '200':
          description: >-
            Successful response from the public API (`message`, echo of accepted
            `params`, and `response` with paginated creator objects in
            snake_case).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1CreatorsProxyResponse'
        '400':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitExceeded'
components:
  schemas:
    V1CreatorsProxyResponse:
      type: object
      description: Envelope returned by `GET /api/v1/creators` on api.topyappers.com.
      required:
        - message
        - response
      properties:
        message:
          type: string
          example: OK
        params:
          type: object
          additionalProperties: true
          description: Echo of query parameters used for the request.
        response:
          $ref: '#/components/schemas/CreatorsPageResult'
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    RateLimitExceeded:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    CreatorsPageResult:
      type: object
      description: >-
        Paginated list payload inside `response` (from the upstream
        `PageResultItem`).
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Creator'
        page:
          type: integer
          example: 1
        next_page:
          type: integer
          example: 0
        total_pages:
          type: integer
          example: 1
        total:
          type: integer
          description: Total hit count when provided
        is_trial:
          type: boolean
          description: True for demo/trial responses
      required:
        - data
    Creator:
      type: object
      description: >-
        Creator profile as returned by the API (snake_case, from influencer
        projection / index). Fields may be `null` when unknown; some index-only
        fields (e.g. `date_created_timestamp`) appear depending on data source.
      example:
        user_id: UCECuDLnD9j3y901oNxJFerw
        handle: April Apple Tech
        nickname: April Apple Tech
        bio: Tech review and business content.
        source: youtube
        email: null
        categories:
          - Tech Reviews
          - Gadget Reviews
          - Smartphone Comparisons
          - Business Technology
        followers: 2500
        following: 0
        total_videos: 296
        total_likes: 0
        avg_views: 35
        avg_likes: 3
        avg_comments: 1
        engagement_rate: 0.11
        main_website: null
        websites: []
        description: null
        promoted_products:
          - DIHRAMS
          - iphone
        best_promotion_niches:
          - Consumer Electronics
          - Mobile Devices
          - Tech Accessories
          - Online Retailers
          - Business Software
        main_category: Technology
        country: United Arab Emirates
        date_created_timestamp: 1775636932.147
        avatar_url: >-
          https://images.0xw.app/avatars/creators/bd6493d02eaf43ad9740efa20ec08cd1.png
        age: 10-19
        gender: male
        account_type: ugc
        race: black
        hair_color: white
        body_complexion: hulk
        language: english
        hashtags:
          - iphone17
          - cinimaticvideo
          - iphoneair
          - shotoniphone
        uploads_per_week: 0.39
        uploads_per_month: 1.66
        avg_video_duration_seconds: null
        promotions_count: 2
        affiliate_posts_count: 0
        sponsorship_posts_count: 0
      required:
        - user_id
        - handle
        - nickname
        - avatar_url
        - followers
        - following
        - total_videos
        - total_likes
        - source
        - categories
        - websites
        - promoted_products
        - best_promotion_niches
        - avg_views
        - avg_likes
        - avg_comments
        - engagement_rate
      properties:
        user_id:
          type: string
          description: >-
            Stable creator id (includes platform prefix, e.g. youtube_,
            instagram_, tiktok_)
        handle:
          type: string
          description: Public handle / channel name
        nickname:
          type: string
        bio:
          type:
            - string
            - 'null'
          description: Profile bio text
        source:
          type: string
          enum:
            - tiktok
            - instagram
            - youtube
          description: Platform / data source
        email:
          type:
            - string
            - 'null'
          format: email
        categories:
          type: array
          items:
            type: string
          description: Detected content category labels
        followers:
          type: integer
        following:
          type: integer
        total_videos:
          type: integer
        total_likes:
          type: integer
        avg_views:
          type: number
          format: float
        avg_likes:
          type: number
          format: float
        avg_comments:
          type: number
          format: float
        engagement_rate:
          type: number
          format: float
          description: Engagement rate (ratio stored as fraction, e.g. 0.11 = 11%)
        main_website:
          type:
            - string
            - 'null'
        websites:
          type: array
          items:
            type: string
        description:
          type:
            - string
            - 'null'
          description: Longer description when available (distinct from bio)
        promoted_products:
          type: array
          items:
            type: string
        best_promotion_niches:
          type: array
          items:
            type: string
          description: AI-derived niches the creator is suited to promote
        main_category:
          type:
            - string
            - 'null'
          description: Primary canonical category
        country:
          type:
            - string
            - 'null'
        date_created_timestamp:
          type:
            - number
            - 'null'
          format: double
          description: >-
            Unix timestamp (seconds) for creator record creation when provided
            by index
        avatar_url:
          type: string
          format: uri
        age:
          type:
            - string
            - 'null'
          description: Age bucket, e.g. 20-29
        gender:
          type:
            - string
            - 'null'
        account_type:
          type:
            - string
            - 'null'
          description: >-
            Creator account type when classified: `faceless`, `ugc`, `agc`,
            `clipper`, `brand`
        race:
          type:
            - string
            - 'null'
        hair_color:
          type:
            - string
            - 'null'
        body_complexion:
          type:
            - string
            - 'null'
        language:
          type:
            - string
            - 'null'
          description: Primary content language (lowercase)
          example: english
        hashtags:
          type: array
          items:
            type: string
          description: Top hashtags used by the creator
        uploads_per_week:
          type:
            - number
            - 'null'
          format: float
          description: Average posts per week (posting cadence)
        uploads_per_month:
          type:
            - number
            - 'null'
          format: float
        avg_video_duration_seconds:
          type:
            - number
            - 'null'
          format: float
          description: Average video length in seconds across analyzed content
        promotions_count:
          type:
            - integer
            - 'null'
          description: Promotion-type posts in analyzed sample
        affiliate_posts_count:
          type:
            - integer
            - 'null'
        sponsorship_posts_count:
          type:
            - integer
            - 'null'
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-ty-api-key
      description: API key for TopYappers API authentication

````