Skip to main content
POST
/
api
/
v1
/
viral-content
Get Viral Posts
curl --request POST \
  --url https://www.topyappers.com/api/v1/viral-content \
  --header 'Content-Type: application/json' \
  --header 'x-ty-api-key: <api-key>' \
  --data '
{
  "categories": [
    "Music"
  ],
  "countries": [
    "United States"
  ],
  "viewsMin": 10000,
  "viralityScoreMin": 0.5,
  "contentFormats": [
    "tutorial",
    "talking_head"
  ],
  "contentTones": [
    "educational"
  ],
  "hasFace": true,
  "videoTopicContains": "skincare",
  "page": 1,
  "pageSize": 12
}
'
{
  "message": "OK",
  "response": {
    "data": [
      {
        "id": "<string>",
        "videoUrl": "<string>",
        "thumbnailUrl": "<string>",
        "caption": "<string>",
        "views": 123,
        "likes": 123,
        "comments": 123,
        "shares": 123,
        "viralityScore": 123,
        "followers": 123,
        "category": "<string>",
        "country": "<string>",
        "musicTitle": "<string>",
        "creatorUsername": "<string>",
        "hook": "<string>",
        "createdAt": "2023-11-07T05:31:56Z"
      }
    ],
    "page": 1,
    "pageSize": 12,
    "totalPages": 100,
    "totalResults": 1200
  },
  "params": {
    "categories": [
      "comedy"
    ],
    "countries": [
      "United States"
    ],
    "viewsMin": 100000,
    "viewsMax": 10000000,
    "viralityScoreMin": 0.5,
    "viralityScoreMax": 1,
    "followersMin": 1000,
    "followersMax": 1000000,
    "dateCreatedFrom": "2024-01-01",
    "dateCreatedTo": "2024-12-31",
    "musicTitle": "original sound",
    "hook": "wait for it",
    "contentFormats": [
      "talking_head"
    ],
    "contentTones": [
      "funny"
    ],
    "visualStyles": [
      "minimalist"
    ],
    "videoSettings": [
      "indoor"
    ],
    "targetDemographics": [
      "gen_z"
    ],
    "productionQualities": [
      "low"
    ],
    "ctaTypes": [
      "none"
    ],
    "primaryEmotions": [
      "joy"
    ],
    "videoTopicContains": "<string>",
    "contentCategoryContains": "<string>",
    "productCategoryContains": "<string>",
    "brandMentionedContains": "<string>",
    "colorPaletteContains": "<string>",
    "hasFace": true,
    "hasProduct": true,
    "isBranded": true,
    "isPromotional": true,
    "hasTextOverlay": true,
    "isTrendingFormat": true,
    "isAiGenerated": true,
    "page": 1,
    "pageSize": 12
  }
}

Authorizations

x-ty-api-key
string
header
required

API key for TopYappers API authentication

Body

application/json

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.

categories
enum<string>[]

Filter by content categories

Available options:
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
Example:
["comedy"]
countries
enum<string>[]

Filter by countries (use full country names)

Available options:
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
Example:
["United States"]
viewsMin
integer

Minimum number of views

Example:

100000

viewsMax
integer

Maximum number of views

Example:

10000000

viralityScoreMin
number<float>

Minimum virality score

Example:

0.5

viralityScoreMax
number<float>

Maximum virality score

Example:

1

followersMin
integer

Minimum number of followers

Example:

1000

followersMax
integer

Maximum number of followers

Example:

1000000

dateCreatedFrom
string<date>

Filter posts created on or after this date (YYYY-MM-DD)

Example:

"2024-01-01"

dateCreatedTo
string<date>

Filter posts created on or before this date (YYYY-MM-DD)

Example:

"2024-12-31"

musicTitle
string

Filter by music/sound title (case-insensitive, partial match)

Example:

"original sound"

hook
string

Filter by video hook text (case-insensitive, partial match)

Example:

"wait for it"

contentFormats
enum<string>[]

Exact match on analyzed content_format. Posts matching any listed value are included.

Analyzed primary content format (stored as content_format). Must match exactly.

Available options:
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
contentTones
enum<string>[]

Exact match on analyzed content_tone. Posts matching any listed value are included.

Analyzed content tone (stored as content_tone). Must match exactly.

Available options:
funny,
serious,
educational,
emotional,
shocking,
inspiring,
controversial,
relatable,
aesthetic,
dramatic,
wholesome,
sarcastic,
informative,
provocative,
calming,
energetic,
nostalgic,
suspenseful,
motivational,
romantic
visualStyles
enum<string>[]

Exact match on analyzed visual_style. Posts matching any listed value are included.

Analyzed visual style (stored as visual_style). Must match exactly.

Available options:
minimalist,
colorful,
dark,
bright,
pastel,
neon,
vintage,
natural,
cinematic,
raw,
polished,
lo_fi,
high_contrast,
warm,
cool,
aesthetic,
luxurious,
gritty
videoSettings
enum<string>[]

Exact match on analyzed filming setting (stored as setting). Posts matching any listed value are included.

Analyzed filming setting (stored as setting; request field videoSettings). Must match exactly.

Available options:
indoor,
outdoor,
studio,
car,
gym,
kitchen,
bedroom,
bathroom,
office,
nature,
restaurant,
store,
street,
beach,
travel,
event,
school,
medical,
other
targetDemographics
enum<string>[]

Exact match on analyzed target_demographic. Posts matching any listed value are included.

Analyzed target audience (stored as target_demographic). Must match exactly.

Available options:
gen_z,
gen_alpha,
millennial,
gen_x,
boomer,
all_ages,
teens,
young_adults,
parents,
professionals,
students,
women,
men
productionQualities
enum<string>[]

Exact match on analyzed production_quality. Posts matching any listed value are included.

Analyzed production quality tier (stored as production_quality). Must match exactly.

Available options:
low,
medium,
high,
professional
ctaTypes
enum<string>[]

Exact match on analyzed cta_type. Posts matching any listed value are included.

Analyzed call-to-action type (stored as cta_type). Must match exactly.

Available options:
none,
follow,
like,
comment,
share,
link_in_bio,
shop,
subscribe,
download,
save,
other
primaryEmotions
enum<string>[]

Exact match on analyzed primary_emotion. Posts matching any listed value are included.

Analyzed dominant emotion (stored as primary_emotion). Must match exactly.

Available options:
joy,
surprise,
fear,
anger,
sadness,
neutral,
excitement,
curiosity,
amusement,
awe,
desire,
nostalgia,
satisfaction,
empathy
videoTopicContains
string

Case-insensitive substring match on analyzed video topic (video_topic). The string is matched literally (special regex characters are escaped).

contentCategoryContains
string

Case-insensitive substring match on analyzed content niche / category (content_category).

productCategoryContains
string

Case-insensitive substring match on analyzed product category (product_category).

brandMentionedContains
string

Case-insensitive substring match on analyzed brand mention text (brand_mentioned).

colorPaletteContains
string

Case-insensitive substring match on analyzed color palette description (color_palette).

hasFace
boolean

When true, only posts analyzed as having a visible face. When false, only posts without. Omit for no filter.

hasProduct
boolean

When true, only posts with a visible product. When false, only without. Omit for no filter.

isBranded
boolean

When true, only branded or sponsored-style posts. When false, exclude those. Omit for no filter.

isPromotional
boolean

When true, only promotional posts. When false, only non-promotional. Omit for no filter.

hasTextOverlay
boolean

When true, only posts with on-screen text overlay. When false, only without. Omit for no filter.

When true, only posts tagged as a trending format. When false, only not. Omit for no filter.

isAiGenerated
boolean

When true, only posts with an AI-generated look. When false, only not. Omit for no filter.

page
integer

Page number for pagination

Required range: x >= 1
Example:

1

pageSize
integer

Number of results per page (default: 12)

Required range: 1 <= x <= 100
Example:

12

Response

Successful response with viral posts

message
string
required
Example:

"OK"

response
object
required
params
object

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.