> ## 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. # Available Parameters > Available creators API parameters for the TopYappers API ## 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`**. ## Available parameters 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 (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` | 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: ```bash theme={null} sortBy=date_created&sortOrder=desc ``` Largest accounts first: ```bash theme={null} sortBy=followers&sortOrder=desc ``` Micro-influencers first: ```bash theme={null} 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