---
title: "List viral videos"
method: GET
path: "/library/viral-videos"
tags: ["Viral Video Library"]
---

# List viral videos

`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`

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.

## Query parameters

- `search` string
- `related` boolean: 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.
- `brandId` string
- `platform` 'all' | 'tiktok' | 'instagram': Restrict to one platform (`tiktok`, `instagram`); `all` lists both
- `dateRange` 'all' | '7d' | '14d' | '30d'
- `sort` 'recent' | 'latest' | 'views' | 'engagement' | 'outlier'
- `minViews` integer, nullable
- `minOutlierFactor` integer, nullable
- `languages` string[]: 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.
- `regions` string[]
- `productTypes` string[]
- `verticals` string[]
- `formats` string[]: 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`.
- `hookArchetypes` string[]
- `productDetected` 'any' | 'yes' | 'no'
- `brandDetected` 'any' | 'yes' | 'no'
- `matchedTerms` string[]
- `bookmarkedOnly` boolean: Only videos the caller bookmarked: the organization's shared bookmarks, or a creator's own
- `limit` integer
- `offset` integer
- `asOf` string, date-time

## Response `200`

OK

- object
  - `data` object[], required
    - `id` string, required
    - `platform` 'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat', required: Social media platform (facebook, instagram, tiktok, youtube, snapchat)
    - `platformVideoId` string, required
    - `platformAccountId` string, nullable, required
    - `accountUsername` string, nullable, required
    - `accountDisplayName` string, nullable, required
    - `accountProfilePictureUrl` string, nullable, required
    - `accountFollowerCount` number, nullable, required
    - `region` string, nullable: Region code (2-letter ISO country code)
    - `caption` string, nullable, required
    - `hashtags` string[], nullable, required
    - `downloadUrl` string, nullable, required
    - `musicTitle` string, nullable, required
    - `musicArtist` string, nullable, required
    - `durationSeconds` number, nullable, required
    - `thumbnailUrl` string, nullable, required
    - `viewCount` number, nullable, required
    - `likeCount` number, nullable, required
    - `commentCount` number, nullable, required
    - `shareCount` number, nullable, required
    - `bookmarkCount` number, nullable, required
    - `engagementRate` number, nullable, required
    - `outlierFactor` number, nullable, required
    - `publishedAt` string, date-time, nullable, required
    - `lastSeenAt` string, date-time, required
    - `addedAt` string, date-time, required: When the video entered the library
    - `matchedTerms` string[], nullable, required
    - `isUgc` boolean, nullable, required
    - `ugcConfidence` number, nullable, required
    - `vertical` string, nullable, required: Research vertical (niche), e.g. education_study
    - `formatPrimary` string, nullable, required: Primary video format, e.g. product_demo_review
    - `hookArchetype` string, nullable, required: Hook archetype, e.g. curiosity_gap
    - `hookTextOverlay` string, nullable, required: The on-screen hook text in the first seconds, if any
    - `whyItWorked` string, nullable, required: One-paragraph research verdict on why it went viral
    - `replicationTip` string, nullable, required: How a marketer could adapt the pattern
    - `copies` object[], nullable, required: Other posts of the same creative (a re-upload, the copy on the other platform) that the library folded into this video; null when it is the only post
      - `platform` 'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat', required: Social media platform (facebook, instagram, tiktok, youtube, snapchat)
      - `platformVideoId` string, required
      - `url` string, required
      - `viewCount` number, nullable, required
      - `publishedAt` string, nullable, required
    - `relatedMatch` unknown
  - `nextOffset` integer, nullable, required
  - `note` string: Set when a filter was relaxed to answer: verticals no library video carries are dropped and the niche is matched by meaning instead

## Other responses

- `400`: 400
- `401`: 401
- `402`: 402
- `404`: 404
- `408`: 408
- `429`: 429
- `500`: 500

---

[API](https://skmtc.dev/viral/apis/viral-app-api.md) · [All operations](https://skmtc.dev/viral/apis/viral-app-api/llms.txt) · [OpenAPI document](https://skmtc.dev/viral/apis/viral-app-api/revisions/31e97fa79ef1?raw)