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

Parameter	Type	Description
`categories`	string[]	Content categories. Values must match the category enum in OpenAPI (e.g. Arts, Fashion, Gaming, Music, …).
`countries`	string[]	Full country names as in OpenAPI (e.g. `United States`, `United Kingdom`).
`viewsMin`	integer	Minimum view count (omit or `0` for no lower bound).
`viewsMax`	integer	Maximum view count (omit or `0` for no upper bound).
`viralityScoreMin`	float	Minimum virality score.
`viralityScoreMax`	float	Maximum virality score.
`followersMin`	integer	Minimum creator follower count.
`followersMax`	integer	Maximum creator follower count.
`dateCreatedFrom`	string	Post created on or after this date (`YYYY-MM-DD`).
`dateCreatedTo`	string	Post created on or before this date (`YYYY-MM-DD`).
`musicTitle`	string	Case-insensitive partial match on music/sound title.
`hook`	string	Case-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.

Parameter	Type	OpenAPI schema (enum)	Maps to analyzed field
`contentFormats`	string[]	`ContentFormat`	`content_format`
`contentTones`	string[]	`ContentTone`	`content_tone`
`visualStyles`	string[]	`VisualStyle`	`visual_style`
`videoSettings`	string[]	`VideoSetting`	`setting` (filming setting)
`targetDemographics`	string[]	`TargetDemographic`	`target_demographic`
`productionQualities`	string[]	`ProductionQuality`	`production_quality`
`ctaTypes`	string[]	`CtaType`	`cta_type`
`primaryEmotions`	string[]	`PrimaryEmotion`	`primary_emotion`

AI analysis — text contains

Case-insensitive substring match. Special regex characters in your string are treated literally (escaped server-side).

Parameter	Type	Description
`videoTopicContains`	string	Substring match on `video_topic`.
`contentCategoryContains`	string	Substring match on content niche / `content_category`.
`productCategoryContains`	string	Substring match on `product_category`.
`brandMentionedContains`	string	Substring match on `brand_mentioned`.
`colorPaletteContains`	string	Substring match on `color_palette`.

Content flags (booleans)

Omit the field for no filter. true / false restrict to posts that pass the corresponding analyzed signal.

Parameter	Type	Description
`hasFace`	boolean	Visible face in the video.
`hasProduct`	boolean	Product visible.
`isBranded`	boolean	Branded / sponsored-style.
`isPromotional`	boolean	Promotional.
`hasTextOverlay`	boolean	On-screen text overlay.
`isTrendingFormat`	boolean	Tagged as trending format.
`isAiGenerated`	boolean	AI-generated look.

Pagination

Parameter	Type	Description
`page`	integer	Page number (default: `1`, minimum: `1`).
`pageSize`	integer	Results 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.

Overview

Viral Content API

Key Features

Category Filtering

Geographic Targeting

Virality Scoring

Music Discovery

Authentication

Request parameters

Core filters

AI analysis — tag arrays (OR within each field)

AI analysis — text contains

Content flags (booleans)

Sorting

Pricing

Rate Limits

Get Viral Posts

​Viral Content API

​Key Features

Category Filtering

Geographic Targeting

Virality Scoring

Music Discovery

​Authentication

​Request parameters

​Core filters

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

​AI analysis — text contains

​Content flags (booleans)

​Pagination

​Sorting

​Pricing

​Rate Limits

Get Viral Posts

Viral Content API

Key Features

Authentication

Request parameters

Core filters

AI analysis — tag arrays (OR within each field)

AI analysis — text contains

Content flags (booleans)

Pagination

Sorting

Pricing

Rate Limits