Skip to main content
GET
/
api
/
v1
/
creators
Get creators (v1)
curl --request GET \
  --url https://www.topyappers.com/api/v1/creators \
  --header 'x-ty-api-key: <api-key>'
{
  "message": "OK",
  "response": {
    "data": [
      {
        "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
      }
    ],
    "page": 1,
    "next_page": 0,
    "total_pages": 1,
    "total": 123,
    "is_trial": true
  },
  "params": {}
}

Authorizations

​
x-ty-api-key
string
header
required

API key for TopYappers API authentication

Query Parameters

​
followersMin
integer

Minimum number of followers

​
followersMax
integer

Maximum number of followers

​
averageViewsMin
integer

Minimum average views per post

​
averageViewsMax
integer

Maximum average views per post

​
averageLikesMin
integer

Minimum average likes per post

​
averageLikesMax
integer

Maximum average likes per post

​
engagementRateMin
number<float>

Minimum engagement rate (percentage). 1-3% average, 3-6% good, 6%+ excellent

​
engagementRateMax
number<float>

Maximum engagement rate (percentage)

​
uploadsPerWeekMin
number<float>

Minimum average posts per week (posting cadence). Omit or use 0 for no lower bound.

​
uploadsPerWeekMax
number<float>

Maximum average posts per week. Omit or use 0 for no upper bound.

​
uploadsPerMonthMin
number<float>

Minimum average posts per month. Omit or use 0 for no lower bound.

​
uploadsPerMonthMax
number<float>

Maximum average posts per month. Omit or use 0 for no upper bound.

​
avgVideoDurationSecondsMin
number<float>

Minimum average video duration in seconds. Omit or use 0 for no lower bound.

​
avgVideoDurationSecondsMax
number<float>

Maximum average video duration in seconds. Omit or use 0 for no upper bound.

​
promotionsCountMin
integer

Minimum count of promotion-type posts in the analyzed sample. Omit or use 0 for no lower bound.

​
promotionsCountMax
integer

Maximum promotion posts count. Omit or use 0 for no upper bound.

​
affiliatePostsCountMin
integer

Minimum count of affiliate-linked posts. Omit or use 0 for no lower bound.

​
affiliatePostsCountMax
integer

Maximum affiliate posts count. Omit or use 0 for no upper bound.

​
sponsorshipPostsCountMin
integer

Minimum count of sponsored posts. Omit or use 0 for no lower bound.

​
sponsorshipPostsCountMax
integer

Maximum sponsored posts count. Omit or use 0 for no upper bound.

​
age
enum<string>

Age group (comma-separated for multiple)

Available options:
0-9,
10-19,
20-29,
30-39,
40-49,
50-59,
60-69,
70-79,
80-89,
90-99
​
gender
enum<string>

Gender filter

Available options:
male,
female
​
race
enum<string>

Ethnicity filter (comma-separated for multiple)

Available options:
White,
Black,
Indian,
East Asian,
Southeast Asian,
Middle Eastern,
Latino Hispanic
​
hairColor
enum<string>

Hair color filter (comma-separated for multiple)

Available options:
Blonde hair,
Brunette hair,
Black hair,
Red hair,
White hair
​
bodyComplexion
enum<string>

Body type / build filter (comma-separated for multiple)

Available options:
Skinny,
Ordinary,
Overweight,
Hulk
​
mainCategory
enum<string>

Main content category

Available options:
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
​
subCategory
string

Sub-category of content (free text search)

​
bio
string

Keywords in creator's bio

​
promotedProducts
string

Products/services promoted by the creator (comma-separated for multiple)

​
nichesToPromote
string

Suggested niches to promote (comma-separated for multiple)

​
country
string

Creator's country (full name)

​
source
enum<string>

Platform / data source

Available options:
tiktok,
instagram,
youtube
​
accountType
enum<string>

Creator account type

Available options:
faceless,
ugc,
agc,
clipper,
brand
​
username
string

Filter creators by their handle

​
language
enum<string>

Primary content language (lowercase)

Available options:
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
​
hashtags
string

Filter by hashtags used in creator content (comma-separated). AND matching — all must be present. '#' prefix is optional

​
emailExists
boolean

Filter creators with available email

​
email
string<email>

Find creator by email

​
sortBy
enum<string>

Field to sort results by. Default: date_created (newest first)

Available options:
date_created,
followers,
engagement_rate,
avg_views,
avg_likes,
avg_comments
​
sortOrder
enum<string>

Sort direction. Default: desc (highest/newest first)

Available options:
asc,
desc
​
page
integer

Page number for pagination

Required range: x >= 1
​
perPage
integer

Number of results per page (max 100)

Required range: 1 <= x <= 100

Response

Successful response from the public API (message, echo of accepted params, and response with paginated creator objects in snake_case).

Envelope returned by GET /api/v1/creators on www.topyappers.com.

​
message
string
required
Example:

"OK"

​
response
object
required

Paginated list payload inside response (from the upstream PageResultItem).

​
params
object

Echo of query parameters used for the request.