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,
        "category": "<string>",
        "country": "<string>",
        "musicTitle": "<string>",
        "creatorUsername": "<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,
    "dateCreatedFrom": "2024-01-01",
    "dateCreatedTo": "2024-12-31",
    "musicTitle": "original sound",
    "page": 1,
    "pageSize": 12
  }
}

Authorizations

​
x-ty-api-key
string
header
required

API key for TopYappers API authentication

Body

application/json
​
categories
enum<string>[]

Filter by content categories. See /reference/enums#categories for all values

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). See /reference/enums#countries for all values

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

​
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

Example:

"original sound"

​
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