General Analytics

Get top performing videos by metrics

Retrieves top performing videos ranked by specified metrics. Supports both lifetime totals (viewCount, likeCount) and period-specific gains (viewCountInPeriod, likeCountInPeriod). Filter by platforms, accounts, projects, and publication date. Set onlyPublished=true to include only videos published within the date range.

get/analytics/top-videos

Request

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

Query parameters

dateRange[from]string required
Example:2025-01-01

Start date in ISO format (YYYY-MM-DD)

dateRange[to]string required
Example:2025-01-31

End date in ISO format (YYYY-MM-DD)

platformsstring[] nullable

Social media platforms (facebook, instagram, tiktok, youtube, snapchat)

[
  "facebook",
  "instagram"
]
accountsstring[] nullable

Organization account IDs

[
  "orgacc_1A2B3C4D5E6F"
]
contentTypesstring[] nullable

Content types (video, slideshow)

[
  "video"
]
projectsstring[] nullable

Organization project IDs

Deprecated. Use tag filters (tags / tagGroups) instead — a project's virtual project tag id (orgproj_…) works as a tag id. See the migration guide.

[
  "orgproj_1A2B3C4D5E6F"
]
tagsstring[] nullable

Tag IDs. Custom and project tags must all match (intersection); country tags and continent:<CODE> values combine into one geographic group satisfied by any of them. none:<category> values (custom/project/country/continent) match entities WITHOUT any tag of the category. Ignored when tagGroups is provided.

[
  "orgtag_1A2B3C4D5E6F"
]
mode'any' | 'all' required

How the group's tags combine: any = OR, all = intersection.

idsstring[] required

Tag IDs, including continent:<CODE> and none:<category> values.

[
  {
    "mode": "all",
    "ids": [
      "orgtag_1A2B3C4D5E6F"
    ]
  },
  {
    "mode": "any",
    "ids": [
      "systag_1A2B3C4D5E6F",
      "continent:EU"
    ]
  }
]
viewMode'internal' | 'competitors' | 'all'
publicationMode'allEligible' | 'onlyPublished'
limitnumber

Maximum number of results to return (1-100)

Example:5
onlyPublishedboolean

Whether to only include content published within the date range

metric'viewCount' | 'likeCount' | 'commentCount' | 'shareCount' | 'bookmarkCount' | 'engagementRate' | 'viewCountInPeriod' | 'likeCountInPeriod' | 'commentCountInPeriod' | 'shareCountInPeriod' | 'bookmarkCountInPeriod' | 'engagementRateInPeriod'

Metric to sort videos by. Supports both lifetime totals and period-specific gains

Example:viewCount

Response

OK

idstring required
platformVideoIdstring required
platformstring required
accountUsernamestring required
platformAccountIdstring required
accountDisplayNamestring nullable required
accountProfilePictureUrlstring nullable required
captionstring nullable required
hashtagsstring[] required
contentTypestring required
videoIndexnumber required
thumbnailUrlstring nullable required
musicIdstring nullable required
musicTitlestring nullable required
musicArtiststring nullable required
musicAlbumstring nullable required
musicPlayUrlstring nullable required
musicCoverUrlstring nullable required
isOriginalMusicnumber nullable required
durationSecondsnumber nullable required
viewCountnumber nullable required
organicViewCountnumber nullable
paidViewCountnumber nullable
likeCountnumber nullable required
commentCountnumber nullable required
shareCountnumber nullable required
bookmarkCountnumber nullable required
engagementRatenumber nullable required
viralityFactornumber nullable required
publishedDatestring required
publishedAtstring required
loadAtstring required
orgAccountIdstring nullable required

Organization account ID with orgacc_ prefix. Not the same as platform account ID.

isCompetitorboolean required

Whether the tracked account is marked as a competitor

viewCountInPeriodnumber required

Total views gained during the specified date range

likeCountInPeriodnumber required

Total likes gained during the specified date range

commentCountInPeriodnumber required

Total comments gained during the specified date range

shareCountInPeriodnumber required

Total shares gained during the specified date range

bookmarkCountInPeriodnumber required

Total bookmarks gained during the specified date range

engagementRateInPeriodnumber required

Engagement rate calculated from period gains (likes+comments+shares+bookmarks)/views

Example response

[
  {
    "id": "orgvid_91rBGUI9L6Db",
    "platformVideoId": "76891234567890012345678",
    "platform": "tiktok",
    "accountUsername": "influencer_account",
    "platformAccountId": "tiktok_user_123456",
    "accountDisplayName": "Influencer Account",
    "accountProfilePictureUrl": "https://example.com/profile.jpg",
    "caption": "Amazing content that went viral! #trending #viral",
    "hashtags": [
      "trending",
      "viral",
      "content"
    ],
    "contentType": "video",
    "videoIndex": 1,
    "thumbnailUrl": "https://example.com/thumbnail.jpg",
    "musicId": "music_123",
    "musicTitle": "Trending Song",
    "musicArtist": "Popular Artist",
    "musicAlbum": "Latest Album",
    "musicPlayUrl": "https://example.com/music.mp3",
    "musicCoverUrl": "https://example.com/music-cover.jpg",
    "isOriginalMusic": 0,
    "durationSeconds": 30,
    "viewCount": 1250000,
    "likeCount": 89500,
    "commentCount": 2340,
    "shareCount": 1890,
    "bookmarkCount": 4567,
    "engagementRate": 0.0789,
    "viralityFactor": 2.34,
    "publishedDate": "2025-12-15",
    "publishedAt": "2025-12-15T10:30:00Z",
    "loadAt": "2025-12-20T08:00:00Z",
    "orgAccountId": "orgacc_W97M6KLWV4Yq",
    "tracking_status": 1,
    "viewCountInPeriod": 850000,
    "likeCountInPeriod": 60000,
    "commentCountInPeriod": 1500,
    "shareCountInPeriod": 1200,
    "bookmarkCountInPeriod": 3000,
    "engagementRateInPeriod": 0.0762
  }
]

Changes

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