---
title: "Get top performing videos by metrics"
method: GET
path: "/analytics/top-videos"
tags: ["General Analytics"]
---

# Get top performing videos by metrics

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

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.

## Query parameters

- `dateRange[from]` string, required
- `dateRange[to]` string, required
- `platforms` string[], nullable: Social media platforms (facebook, instagram, tiktok, youtube, snapchat)
- `accounts` string[], nullable: Organization account IDs
- `contentTypes` string[], nullable: Content types (video, slideshow)
- `projects` string[], nullable: Organization project IDs
- `tags` string[], 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.
- `tagGroups` object[], nullable: Advanced tag filter: groups combine with AND; within a group `any` matches videos carrying at least one of the tags, `all` requires every tag. `none:<category>` ids match videos without any tag of the category. Takes precedence over `tags` when provided. Also accepts the compact string form `all:orgtag_a,orgtag_b;any:systag_de,continent:EU`.
  - `mode` 'any' | 'all', required: How the group's tags combine: `any` = OR, `all` = intersection.
  - `ids` string[], required: Tag IDs, including `continent:<CODE>` and `none:<category>` values.
- `viewMode` 'internal' | 'competitors' | 'all'
- `publicationMode` 'allEligible' | 'onlyPublished'
- `limit` number: Maximum number of results to return (1-100)
- `onlyPublished` boolean: 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

## Response `200`

OK

- object[]: Array of top performing videos with both lifetime totals and period-specific metrics
  - `id` string, required
  - `platformVideoId` string, required
  - `platform` string, required
  - `accountUsername` string, required
  - `platformAccountId` string, required
  - `accountDisplayName` string, nullable, required
  - `accountProfilePictureUrl` string, nullable, required
  - `caption` string, nullable, required
  - `hashtags` string[], required
  - `contentType` string, required
  - `videoIndex` number, required
  - `thumbnailUrl` string, nullable, required
  - `musicId` string, nullable, required
  - `musicTitle` string, nullable, required
  - `musicArtist` string, nullable, required
  - `musicAlbum` string, nullable, required
  - `musicPlayUrl` string, nullable, required
  - `musicCoverUrl` string, nullable, required
  - `isOriginalMusic` number, nullable, required
  - `durationSeconds` number, nullable, required
  - `viewCount` number, nullable, required
  - `organicViewCount` number, nullable
  - `paidViewCount` number, nullable
  - `likeCount` number, nullable, required
  - `commentCount` number, nullable, required
  - `shareCount` number, nullable, required
  - `bookmarkCount` number, nullable, required
  - `engagementRate` number, nullable, required
  - `viralityFactor` number, nullable, required
  - `publishedDate` string, required
  - `publishedAt` string, required
  - `loadAt` string, required
  - `orgAccountId` string, nullable, required: Organization account ID with orgacc_ prefix. Not the same as platform account ID.
  - `isCompetitor` boolean, required: Whether the tracked account is marked as a competitor
  - `tracking_status` union, required: Tracking status indicator: 1 for actively tracked entries, 0 for retained historic data
    - unknown
    - unknown
  - `viewCountInPeriod` number, required: Total views gained during the specified date range
  - `likeCountInPeriod` number, required: Total likes gained during the specified date range
  - `commentCountInPeriod` number, required: Total comments gained during the specified date range
  - `shareCountInPeriod` number, required: Total shares gained during the specified date range
  - `bookmarkCountInPeriod` number, required: Total bookmarks gained during the specified date range
  - `engagementRateInPeriod` number, required: Engagement rate calculated from period gains (likes+comments+shares+bookmarks)/views

## 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)