> ## 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 Viral Posts > Retrieve viral TikTok content filtered by categories, countries, views, virality and follower ranges, dates, music and hook, AI tag arrays and text-contains fields, and boolean content flags. See `ViralPostsRequest` in components/schemas. ## OpenAPI ````yaml POST /api/v1/viral-content openapi: 3.1.0 info: title: Viral Content API description: >- API for discovering viral TikTok content with filtering by categories, countries, views, virality scores, AI-derived tags (format, tone, visual style, setting, demographics, production, CTA, emotion), substring fields, and boolean content flags (face, product, branded, etc.). Enum values must match exactly (snake_case). license: name: MIT version: 1.0.0 servers: - url: https://api.topyappers.com security: - apiKeyAuth: [] paths: /api/v1/viral-content: post: summary: Get Viral Posts description: >- Retrieve viral TikTok content filtered by categories, countries, views, virality and follower ranges, dates, music and hook, AI tag arrays and text-contains fields, and boolean content flags. See `ViralPostsRequest` in components/schemas. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ViralPostsRequest' example: categories: - Music countries: - United States viewsMin: 10000 viralityScoreMin: 0.5 contentFormats: - tutorial - talking_head contentTones: - educational hasFace: true videoTopicContains: skincare page: 1 pageSize: 12 responses: '200': description: Successful response with viral posts content: application/json: schema: $ref: '#/components/schemas/ViralPostsResponse' '400': description: Invalid JSON in request body content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing API key content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/RateLimitExceeded' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: ViralPostsRequest: type: object description: >- Results are always sorted by post creation time, newest first. There are no sortBy/sortOrder fields; use dateCreatedFrom/dateCreatedTo to limit the time range. For array fields of analyzed tags, the API matches posts where the corresponding field equals any one of the supplied values (logical OR per field). Omit optional filters or use empty arrays / null to leave them unset. properties: categories: type: array items: 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 description: Filter by content categories example: - comedy countries: type: array items: type: string enum: - United States - China - Japan - Germany - United Kingdom - India - France - Canada - Italy - South Korea - Australia - Brazil - Spain - Mexico - Indonesia - Netherlands - Saudi Arabia - Turkey - Switzerland - Taiwan - Poland - Sweden - Belgium - Thailand - Argentina - Nigeria - Austria - Iran - Norway - United Arab Emirates - Ireland - Israel - South Africa - Denmark - Singapore - Malaysia - Philippines - Hong Kong - Colombia - Bangladesh - Egypt - Finland - Chile - Vietnam - Czechia - Romania - New Zealand - Portugal - Greece - Iraq - Qatar - Peru - Hungary - Kuwait - Ukraine - Morocco - Slovakia - Puerto Rico - Ecuador - Oman - Kenya - Luxembourg - Cuba - Sri Lanka - Uzbekistan - Bulgaria - Croatia - Côte d'Ivoire - Belarus - Uruguay - Panama - Slovenia - Turkmenistan - Lithuania - Lebanon - Tanzania - Jordan - Bahrain - Serbia - Cameroon - Bolivia - Paraguay - Ghana - Estonia - Uganda - Zambia - Afghanistan - Bosnia and Herzegovina - Mozambique - Armenia - Georgia - Honduras - Albania - Madagascar - Namibia - Senegal - Malta - Chad - Niger - Mali - Kyrgyzstan - Malawi - Rwanda - Burundi - Comoros - Lesotho - Tajikistan - Suriname - Montenegro - Eswatini - Sierra Leone - Gambia - Guyana - Timor-Leste - Mauritania - Burkina Faso - Liberia - Cape Verde - Mauritius - Bhutan - Benin - Central African Republic - Togo - Guinea - Gabon - São Tomé and Príncipe - Equatorial Guinea - Antigua and Barbuda - Belize - Barbados - Saint Kitts and Nevis - Vanuatu - Solomon Islands - Saint Vincent and the Grenadines - Fiji - Samoa - Tonga - Dominica - Russia - Other description: Filter by countries (use full country names) example: - United States viewsMin: type: integer description: Minimum number of views example: 100000 viewsMax: type: integer description: Maximum number of views example: 10000000 viralityScoreMin: type: number format: float description: Minimum virality score example: 0.5 viralityScoreMax: type: number format: float description: Maximum virality score example: 1 followersMin: type: integer description: Minimum number of followers example: 1000 followersMax: type: integer description: Maximum number of followers example: 1000000 dateCreatedFrom: type: string format: date description: Filter posts created on or after this date (YYYY-MM-DD) example: '2024-01-01' dateCreatedTo: type: string format: date description: Filter posts created on or before this date (YYYY-MM-DD) example: '2024-12-31' musicTitle: type: string description: Filter by music/sound title (case-insensitive, partial match) example: original sound hook: type: string description: Filter by video hook text (case-insensitive, partial match) example: wait for it contentFormats: type: array items: $ref: '#/components/schemas/ContentFormat' description: >- Exact match on analyzed `content_format`. Posts matching any listed value are included. contentTones: type: array items: $ref: '#/components/schemas/ContentTone' description: >- Exact match on analyzed `content_tone`. Posts matching any listed value are included. visualStyles: type: array items: $ref: '#/components/schemas/VisualStyle' description: >- Exact match on analyzed `visual_style`. Posts matching any listed value are included. videoSettings: type: array items: $ref: '#/components/schemas/VideoSetting' description: >- Exact match on analyzed filming setting (stored as `setting`). Posts matching any listed value are included. targetDemographics: type: array items: $ref: '#/components/schemas/TargetDemographic' description: >- Exact match on analyzed `target_demographic`. Posts matching any listed value are included. productionQualities: type: array items: $ref: '#/components/schemas/ProductionQuality' description: >- Exact match on analyzed `production_quality`. Posts matching any listed value are included. ctaTypes: type: array items: $ref: '#/components/schemas/CtaType' description: >- Exact match on analyzed `cta_type`. Posts matching any listed value are included. primaryEmotions: type: array items: $ref: '#/components/schemas/PrimaryEmotion' description: >- Exact match on analyzed `primary_emotion`. Posts matching any listed value are included. videoTopicContains: type: string description: >- Case-insensitive substring match on analyzed video topic (`video_topic`). The string is matched literally (special regex characters are escaped). contentCategoryContains: type: string description: >- Case-insensitive substring match on analyzed content niche / category (`content_category`). productCategoryContains: type: string description: >- Case-insensitive substring match on analyzed product category (`product_category`). brandMentionedContains: type: string description: >- Case-insensitive substring match on analyzed brand mention text (`brand_mentioned`). colorPaletteContains: type: string description: >- Case-insensitive substring match on analyzed color palette description (`color_palette`). hasFace: type: boolean description: >- When `true`, only posts analyzed as having a visible face. When `false`, only posts without. Omit for no filter. hasProduct: type: boolean description: >- When `true`, only posts with a visible product. When `false`, only without. Omit for no filter. isBranded: type: boolean description: >- When `true`, only branded or sponsored-style posts. When `false`, exclude those. Omit for no filter. isPromotional: type: boolean description: >- When `true`, only promotional posts. When `false`, only non-promotional. Omit for no filter. hasTextOverlay: type: boolean description: >- When `true`, only posts with on-screen text overlay. When `false`, only without. Omit for no filter. isTrendingFormat: type: boolean description: >- When `true`, only posts tagged as a trending format. When `false`, only not. Omit for no filter. isAiGenerated: type: boolean description: >- When `true`, only posts with an AI-generated look. When `false`, only not. Omit for no filter. page: type: integer minimum: 1 description: Page number for pagination example: 1 pageSize: type: integer minimum: 1 maximum: 100 description: 'Number of results per page (default: 12)' example: 12 ViralPostsResponse: type: object properties: message: type: string example: OK params: $ref: '#/components/schemas/ViralPostsRequest' response: type: object properties: data: type: array items: $ref: '#/components/schemas/ViralPost' page: type: integer example: 1 pageSize: type: integer example: 12 totalPages: type: integer example: 100 totalResults: type: integer example: 1200 required: - message - response Error: type: object required: - error properties: error: type: string RateLimitExceeded: type: object required: - error properties: error: type: string example: Too many requests retryAfter: type: integer description: Seconds to wait before retrying example: 60 ContentFormat: type: string description: >- Analyzed primary content format (stored as `content_format`). Must match exactly. enum: - talking_head - voiceover - slideshow - skit - tutorial - vlog - challenge - reaction - product_review - asmr - before_after - storytime - grwm - unboxing - compilation - interview - day_in_life - pov - dance - lip_sync - cooking - fitness - diy - meme - music_video - podcast_clip - gaming - other ContentTone: type: string description: Analyzed content tone (stored as `content_tone`). Must match exactly. enum: - funny - serious - educational - emotional - shocking - inspiring - controversial - relatable - aesthetic - dramatic - wholesome - sarcastic - informative - provocative - calming - energetic - nostalgic - suspenseful - motivational - romantic VisualStyle: type: string description: Analyzed visual style (stored as `visual_style`). Must match exactly. enum: - minimalist - colorful - dark - bright - pastel - neon - vintage - natural - cinematic - raw - polished - lo_fi - high_contrast - warm - cool - aesthetic - luxurious - gritty VideoSetting: type: string description: >- Analyzed filming setting (stored as `setting`; request field `videoSettings`). Must match exactly. enum: - indoor - outdoor - studio - car - gym - kitchen - bedroom - bathroom - office - nature - restaurant - store - street - beach - travel - event - school - medical - other TargetDemographic: type: string description: >- Analyzed target audience (stored as `target_demographic`). Must match exactly. enum: - gen_z - gen_alpha - millennial - gen_x - boomer - all_ages - teens - young_adults - parents - professionals - students - women - men ProductionQuality: type: string description: >- Analyzed production quality tier (stored as `production_quality`). Must match exactly. enum: - low - medium - high - professional CtaType: type: string description: Analyzed call-to-action type (stored as `cta_type`). Must match exactly. enum: - none - follow - like - comment - share - link_in_bio - shop - subscribe - download - save - other PrimaryEmotion: type: string description: >- Analyzed dominant emotion (stored as `primary_emotion`). Must match exactly. enum: - joy - surprise - fear - anger - sadness - neutral - excitement - curiosity - amusement - awe - desire - nostalgia - satisfaction - empathy ViralPost: type: object properties: id: type: string description: Unique post identifier videoUrl: type: string description: URL to the video thumbnailUrl: type: string description: URL to the video thumbnail caption: type: string description: Post caption/description views: type: integer description: Number of views likes: type: integer description: Number of likes comments: type: integer description: Number of comments shares: type: integer description: Number of shares viralityScore: type: number format: float description: Virality score (views / followers ratio) followers: type: integer description: Number of creator followers at time of discovery category: type: string description: Content category country: type: string description: Country of origin musicTitle: type: string description: Music/sound title used in the video creatorUsername: type: string description: Creator's username hook: type: string nullable: true description: Opening hook text of the video createdAt: type: string format: date-time description: Date and time the post was created securitySchemes: apiKeyAuth: type: apiKey in: header name: x-ty-api-key description: API key for TopYappers API authentication ````