Pricing (v1)
The v1 Creators API (GET /api/v1/creators) costs 1 credit per influencer returned.
Response shape (profiles are snake_case)
Onhttps://www.topyappers.com, GET /api/v1/creators returns { "message", "params", "response" }. Full creator rows are in response.data (not a top-level data array). Each creator uses snake_case fields (user_id, handle, avg_views, promoted_products, best_promotion_niches, uploads_per_week, etc.) — see openapi.json → Creator for the full schema and example.
POST /api/v2/creators/get returns { "message", "requestedIds", "response" } with the same creator objects in response.data.
Available parameters
Query parameters work the same forGET /api/v1/creators and GET /api/v2/creators/search (v2 search returns IDs only; filters are identical). For numeric min/max filters, omit the parameter or use 0 when you do not want a lower or upper bound (see OpenAPI for exact wording).
Performance metrics
| Parameter | Type | Description | Example |
|---|---|---|---|
followersMin | Number | Minimum number of followers | followersMin=10000 |
followersMax | Number | Maximum number of followers | followersMax=1000000 |
averageViewsMin | Number | Minimum average views per post | averageViewsMin=5000 |
averageViewsMax | Number | Maximum average views per post | averageViewsMax=500000 |
averageLikesMin | Number | Minimum average likes per post | averageLikesMin=100 |
averageLikesMax | Number | Maximum average likes per post | averageLikesMax=50000 |
engagementRateMin | Number | Minimum engagement rate (percentage). 1–3% average, 3–6% good, 6%+ excellent | engagementRateMin=2.5 |
engagementRateMax | Number | Maximum engagement rate (percentage) | engagementRateMax=10 |
Posting cadence, duration & monetization (sample-based)
| Parameter | Type | Description | Example |
|---|---|---|---|
uploadsPerWeekMin | Number | Minimum average posts per week | uploadsPerWeekMin=3 |
uploadsPerWeekMax | Number | Maximum average posts per week | uploadsPerWeekMax=14 |
uploadsPerMonthMin | Number | Minimum average posts per month | uploadsPerMonthMin=10 |
uploadsPerMonthMax | Number | Maximum average posts per month | uploadsPerMonthMax=60 |
avgVideoDurationSecondsMin | Number | Minimum average video length (seconds) | avgVideoDurationSecondsMin=15 |
avgVideoDurationSecondsMax | Number | Maximum average video length (seconds) | avgVideoDurationSecondsMax=120 |
promotionsCountMin | Number | Minimum count of promotion-type posts in the analyzed sample | promotionsCountMin=1 |
promotionsCountMax | Number | Maximum promotion posts count | promotionsCountMax=50 |
affiliatePostsCountMin | Number | Minimum affiliate-style posts count | affiliatePostsCountMin=0 |
affiliatePostsCountMax | Number | Maximum affiliate posts count | affiliatePostsCountMax=20 |
sponsorshipPostsCountMin | Number | Minimum sponsored posts count | sponsorshipPostsCountMin=0 |
sponsorshipPostsCountMax | Number | Maximum sponsored posts count | sponsorshipPostsCountMax=30 |
Account type, language, hashtags
| Parameter | Type | Description | Example |
|---|---|---|---|
accountType | String | Creator account type: faceless, ugc, agc, clipper, brand | accountType=ugc |
language | String | Primary content language (lowercase): english, spanish, french, german, japanese, korean, mandarin, hindi, arabic, portuguese, russian, turkish, italian, dutch, polish, thai, vietnamese, indonesian, filipino, swedish, norwegian, danish, finnish, czech, romanian, hungarian, greek, hebrew, persian, urdu, bengali, tamil, telugu, marathi, gujarati, kannada, malayalam, punjabi, sinhala, nepali, pashto, hausa, yoruba, somali, swahili, ukrainian, serbian, croatian, bosnian, bulgarian, slovak, slovenian, estonian, latvian, lithuanian, catalan, icelandic, kazakh, uzbek, javanese, cantonese | language=english |
hashtags | String | Comma-separated; AND logic — all listed hashtags must appear on the creator. # prefix optional | hashtags=fitness,gym |
Demographics
| Parameter | Type | Description | Example |
|---|---|---|---|
age | String | Age buckets (comma-separated): 0-9, 10-19, 20-29, 30-39, 40-49, 50-59, 60-69, 70-79, 80-89, 90-99 | age=20-29,30-39 |
gender | String | male or female | gender=female |
race | String | Ethnicity (comma-separated): White, Black, Indian, East Asian, Southeast Asian, Middle Eastern, Latino Hispanic | race=East Asian |
hairColor | String | Hair color (comma-separated): Blonde hair, Brunette hair, Black hair, Red hair, White hair | hairColor=Blonde hair |
bodyComplexion | String | Body type (comma-separated): Skinny, Ordinary, Overweight, Hulk | bodyComplexion=Skinny |
Content & geography
| Parameter | Type | Description | Example |
|---|---|---|---|
mainCategory | String | Main content category: 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 | mainCategory=Fashion |
subCategory | String | Sub-category of content (free text search) | subCategory=streetwear |
bio | String | Keywords in creator’s bio | bio=tiktok shop |
promotedProducts | String | Products or services promoted (comma-separated) | promotedProducts=beef tallow,feastables |
nichesToPromote | String | Niches to promote — powerful discovery filter (comma-separated) | nichesToPromote=fashion,streetwear |
country | String | Creator’s country (full name) | country=France |
source | String | Platform: tiktok, instagram, youtube | source=tiktok |
Identity, email & pagination
| Parameter | Type | Description | Example |
|---|---|---|---|
username | String | Filter by handle | username=mrbeast |
emailExists | Boolean | Only creators with email on file | emailExists=true |
email | String | Lookup by email | email=john@example.com |
page | Number | Page number (min 1) | page=2 |
perPage | Number | Results per page (max 100) | perPage=50 |
language, mainCategory, accountType) matches openapi.json — use that file as the source of truth if you generate clients or validators.
Sorting
Sorting controls which creators appear first in each page. For discovery workflows — especially “who was added most recently” — usesortBy=date_created with sortOrder=desc.
| Parameter | Type | Description |
|---|---|---|
sortBy | String | Field to order by (see table below) |
sortOrder | String | asc (lowest first) or desc (highest first) |
sortBy=date_created, sortOrder=desc (newest first).
Allowed sortBy values
sortBy | What it sorts by |
|---|---|
date_created | When the creator was added or last refreshed. Use this for “newest in the database” ordering. |
followers | Follower count |
engagement_rate | Engagement rate |
avg_views | Average views per post |
avg_likes | Average likes per post |
avg_comments | Average comments per post |
Examples
Newest creators first:Promoted Products & Niches to Promote
promotedProducts
Search for creators who have promoted specific products. For example, if you search for “Beef Tallow”, you’ll get all creators who have mentioned this product in their content.nichesToPromote
This is one of the most powerful filters for finding relevant creators. It’s a free text search that matches against our AI-analyzed niches for each creator.nichesToPromote=SaaS- Find creators suitable for promoting software productsnichesToPromote=skincare,beauty- Find creators in the skincare/beauty spacenichesToPromote=fitness supplements- Find creators who promote fitness-related products
Tips
- Use comma-separated values for multiple items:
promotedProducts=beef tallow,feastables nichesToPromoteworks best as a discovery tool - be creative with your search terms