Viral Video Library

List viral videos

Retrieves viral videos from the research library using offset pagination. Supports filtering by search term, brand, region, language, date range, minimum views, outlier factor, taxonomy facets, and detected entities.

get/library/viral-videos

Request

  • Base URL: https://viral.app/api/v1
  • URL: https://viral.app/api/v1/library/viral-videos
  • Auth: API key in header x-api-key

Query parameters

searchstring
relatedboolean

Top a search with fewer than 12 close matches up with related videos, listed after them and flagged relatedMatch. For browsing; leave it off when an empty result should mean the library has nothing on the topic.

brandIdstring
platform'all' | 'tiktok' | 'instagram'

Restrict to one platform (tiktok, instagram); all lists both

dateRange'all' | '7d' | '14d' | '30d'
sort'recent' | 'latest' | 'views' | 'engagement' | 'outlier'
minViewsinteger nullable
minOutlierFactorinteger nullable
languagesstring[]

ISO 639-1 codes of the language spoken or written in the video, as classified from the video itself (not the account's region). Omit for every language on the API; the library page and the Copilot default to English.

[
  "es"
]
regionsstring[] 
[
  "US"
]
productTypesstring[]
verticalsstring[]
formatsstring[]

Primary formats; several widen the match. talking_head (a creator speaking on camera) and screen_recording match how the video is presented, not formatPrimary, so their results carry a structural formatPrimary such as product_demo_review.

hookArchetypesstring[]
productDetected'any' | 'yes' | 'no'
brandDetected'any' | 'yes' | 'no'
matchedTermsstring[]
bookmarkedOnlyboolean

Only videos the caller bookmarked: the organization's shared bookmarks, or a creator's own

limitinteger
offsetinteger
asOfstring date-time

Response

OK

nextOffsetinteger nullable required
notestring

Set when a filter was relaxed to answer: verticals no library video carries are dropped and the niche is matched by meaning instead

Example response

{
  "data": [
    {
      "platform": "facebook",
      "region": "US",
      "copies": [
        {
          "platform": "facebook"
        }
      ]
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.