Skip to main content

​
Viral Content API

The Viral Content API allows you to discover and analyze viral TikTok content. Filter by categories, countries, views, virality and follower ranges, dates, music and hook text, AI-derived tags (format, tone, look, setting, audience, production, CTA, emotion), substring fields on analyzed text, and boolean content flags (face visible, product, branded, and more).

​
Key Features

Category Filtering

Filter viral posts by content categories like comedy, dance, food, and more.

Geographic Targeting

Find viral content from specific countries and regions.

Virality Scoring

Filter by our proprietary virality score to find the most engaging content.

Music Discovery

Search for viral posts using specific trending sounds and music.

​
Authentication

All requests require an API key passed in the x-ty-api-key header. 
curl -X POST https://www.topyappers.com/api/v1/viral-content \
  -H "x-ty-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "categories": ["Music"],
    "viewsMin": 100000,
    "page": 1,
    "pageSize": 12
  }'

​
Request parameters

All parameters are sent in the JSON request body (optional unless noted). Omit a field, use an empty array [], or null where documented to apply no filter for that field.

​
Core filters

ParameterTypeDescription
categoriesstring[]Content categories. Values must match the category enum in OpenAPI (e.g. Arts, Fashion, Gaming, Music, …).
countriesstring[]Full country names as in OpenAPI (e.g. United States, United Kingdom).
viewsMinintegerMinimum view count (omit or 0 for no lower bound).
viewsMaxintegerMaximum view count (omit or 0 for no upper bound).
viralityScoreMinfloatMinimum virality score.
viralityScoreMaxfloatMaximum virality score.
followersMinintegerMinimum creator follower count.
followersMaxintegerMaximum creator follower count.
dateCreatedFromstringPost created on or after this date (YYYY-MM-DD).
dateCreatedTostringPost created on or before this date (YYYY-MM-DD).
musicTitlestringCase-insensitive partial match on music/sound title.
hookstringCase-insensitive partial match on analyzed hook text.

​
AI analysis — tag arrays (OR within each field)

For each array below, a post matches if its stored tag equals any value you send. Values are fixed snake_case strings; see the linked schema in openapi.json for the complete enum per field.
ParameterTypeOpenAPI schema (enum)Maps to analyzed field
contentFormatsstring[]ContentFormatcontent_format
contentTonesstring[]ContentTonecontent_tone
visualStylesstring[]VisualStylevisual_style
videoSettingsstring[]VideoSettingsetting (filming setting)
targetDemographicsstring[]TargetDemographictarget_demographic
productionQualitiesstring[]ProductionQualityproduction_quality
ctaTypesstring[]CtaTypecta_type
primaryEmotionsstring[]PrimaryEmotionprimary_emotion

​
AI analysis — text contains

Case-insensitive substring match. Special regex characters in your string are treated literally (escaped server-side).
ParameterTypeDescription
videoTopicContainsstringSubstring match on video_topic.
contentCategoryContainsstringSubstring match on content niche / content_category.
productCategoryContainsstringSubstring match on product_category.
brandMentionedContainsstringSubstring match on brand_mentioned.
colorPaletteContainsstringSubstring match on color_palette.

​
Content flags (booleans)

Omit the field for no filter. true / false restrict to posts that pass the corresponding analyzed signal.
ParameterTypeDescription
hasFacebooleanVisible face in the video.
hasProductbooleanProduct visible.
isBrandedbooleanBranded / sponsored-style.
isPromotionalbooleanPromotional.
hasTextOverlaybooleanOn-screen text overlay.
isTrendingFormatbooleanTagged as trending format.
isAiGeneratedbooleanAI-generated look.

​
Pagination

ParameterTypeDescription
pageintegerPage number (default: 1, minimum: 1).
pageSizeintegerResults per page (default: 12, maximum: 100).

​
Sorting

The Viral Content API does not take sortBy / sortOrder in the request body. Results are always returned in a fixed order:
  • Primary: post creation time (date_created on the post), newest first (descending).
So the first items on page 1 are the most recently created viral posts that match your filters. Use dateCreatedFrom / dateCreatedTo to narrow the time window; ordering within that window remains newest first.

​
Pricing

Each request costs 1 credit per returned content. For example, if you request pageSize: 12 and receive 12 results, that costs 12 credits.

​
Rate Limits

The Viral Content API is subject to rate limits. If you exceed the limit, you’ll receive a 429 response with a retryAfter field indicating how long to wait before retrying.