Available Parameters

Pricing (v1)

The v1 Creators API (GET /api/v1/creators) costs 1 credit per influencer returned.

Response shape (profiles are snake_case)

On https://api.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.

Query parameters work the same for GET /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 in percent (`5` means 5%); profile `engagement_rate` uses a fraction (`0.03` means 3%)	`engagementRateMin=2.5`
`engagementRateMax`	Number	Maximum engagement rate in percent (`5` means 5%); profile `engagement_rate` uses a fraction (`0.03` means 3%)	`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`, `twitch`, `linkedin`, `twitter` (X/Twitter)	`source=twitch`

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`

The full list of allowed values for enums (e.g. 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” — use sortBy=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)

Defaults: 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:

sortBy=date_created&sortOrder=desc

Largest accounts first:

sortBy=followers&sortOrder=desc

Micro-influencers first:

sortBy=followers&sortOrder=asc

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 products
nichesToPromote=skincare,beauty - Find creators in the skincare/beauty space
nichesToPromote=fitness supplements - Find creators who promote fitness-related products

Tips

Use comma-separated values for multiple items: promotedProducts=beef tallow,feastables
nichesToPromote works best as a discovery tool - be creative with your search terms

​Pricing (v1)

​Response shape (profiles are snake_case)