General Analytics

Get top performing accounts by metrics

Retrieves top performing accounts ranked by specified metrics. Includes lifetime totals (viewCount, engagementRate) and period-specific gains (viewCountInPeriod, videoCountInPeriod). Returns account analytics including follower counts, posting frequency, and performance averages. Filter by platforms, accounts, projects, and content types.

get/analytics/top-accounts

Request

  • Base URL: https://viral.app/api/v1
  • URL: https://viral.app/api/v1/analytics/top-accounts
  • 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' | 'videoCount' | 'engagementRate' | 'averageViewsPerVideo' | 'viewCountInPeriod' | 'likeCountInPeriod' | 'commentCountInPeriod' | 'shareCountInPeriod' | 'bookmarkCountInPeriod' | 'videoCountInPeriod' | 'engagementRateInPeriod' | 'averageViewsPerVideoInPeriod'

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

Example:viewCount

Response

OK

idstring required

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

platform'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat' required

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

platformAccountIdstring required

Native platform account id

isCompetitorboolean required

Whether the tracked account is marked as a competitor

usernamestring nullable required

Account username/handle on the platform

loadAtstring nullable required

Timestamp when account data was last loaded

followerCountnumber nullable required

Number of followers for this account

followingCountnumber nullable required

Number of accounts this account is following

profilePictureUrlstring nullable required

URL to the account's profile picture

displayNamestring nullable required

Display name of the account

countryCodestring nullable required

Country code where the account is based

viewCountnumber required

Total lifetime views across all videos

likeCountnumber required

Total lifetime likes across all videos

commentCountnumber required

Total lifetime comments across all videos

shareCountnumber required

Total lifetime shares across all videos

bookmarkCountnumber required

Total lifetime bookmarks across all videos

videoCountnumber required

Total number of videos published by this account

averageViewsPerVideonumber required

Average views per video across all content

engagementRatenumber required

Overall engagement rate (likes+comments+shares+bookmarks)/views

viralityRatenumber required

Rate of viral content based on performance thresholds

latestVideoPublishedAtstring nullable required

Timestamp of when the latest video was published

daysSinceLastPostnumber nullable required

Number of days since the last video was published

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

videoCountInPeriodnumber required

Number of videos published during the specified date range

averageViewsPerVideoInPeriodnumber required

Average views per video for content published in the period

engagementRateInPeriodnumber required

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

Example response

[
  {
    "id": "orgacc_W97M6KLWV4Yq",
    "platform": "tiktok",
    "username": "viral_creator",
    "loadAt": "2025-12-20T08:00:00Z",
    "followerCount": 2500000,
    "followingCount": 150,
    "profilePictureUrl": "https://example.com/profile.jpg",
    "displayName": "Viral Creator",
    "countryCode": "US",
    "viewCount": 45000000,
    "likeCount": 3200000,
    "commentCount": 180000,
    "shareCount": 95000,
    "bookmarkCount": 250000,
    "videoCount": 120,
    "averageViewsPerVideo": 375000,
    "engagementRate": 0.0811,
    "viralityRate": 0.25,
    "latestVideoPublishedAt": "2025-12-18T15:30:00Z",
    "daysSinceLastPost": 2,
    "user": {
      "id": "track_91rBGUI9L6Db",
      "platform": "tiktok",
      "username": "viral_creator",
      "maxVideos": 100,
      "userId": "user_PxyfnFj5JUx5",
      "orgId": "org_GbuDqv3RjdSW",
      "createdAt": "2025-01-15T10:00:00.000Z",
      "updatedAt": "2025-12-20T08:00:00.000Z"
    },
    "viewCountInPeriod": 12500000,
    "likeCountInPeriod": 890000,
    "commentCountInPeriod": 48000,
    "shareCountInPeriod": 25000,
    "bookmarkCountInPeriod": 67000,
    "videoCountInPeriod": 15,
    "averageViewsPerVideoInPeriod": 833333,
    "engagementRateInPeriod": 0.0824
  }
]

Changes

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