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,
  "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",
    "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.

​
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"

​
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.