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

# Get top performing creators by aggregated metrics

`GET /analytics/top-creators`

## Request

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

Retrieves top performing creators ranked by specified metrics aggregated across all their linked accounts. Includes lifetime totals (viewCount, engagementRate) and period-specific gains (viewCountInPeriod, videoCountInPeriod). Returns creator details, user information, and all linked accounts. Metrics are summed across all accounts for comprehensive creator performance analysis. Filter by platforms, accounts, projects, and content types.

## 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' | 'videoCount' | 'engagementRate' | 'averageViewsPerVideo' | 'viewCountInPeriod' | 'likeCountInPeriod' | 'commentCountInPeriod' | 'shareCountInPeriod' | 'bookmarkCountInPeriod' | 'videoCountInPeriod' | 'engagementRateInPeriod' | 'averageViewsPerVideoInPeriod': Metric to sort creators by. Supports both lifetime totals and period-specific gains. Aggregates across all linked accounts.

## Response `200`

OK

- object[]: Array of top performing creators with comprehensive analytics aggregated from all their accounts
  - `id` string, required: Organization creator ID
  - `creatorUserId` string, required: The user ID of the creator
  - `notes` string, nullable, required: Internal notes about this creator
  - `createdAt` string, date-time, required: When this creator was added to the organization
  - `updatedAt` string, date-time, required: When this creator record was last updated
  - `user` object, required: Creator user details
    - `id` string, required: User ID
    - `name` string, required: Creator's full name
    - `email` string, required: Creator's email address
    - `image` string, nullable, required: Creator's profile picture URL
    - `firstName` string, required: Creator's first name
    - `lastName` string, required: Creator's last name
  - `accounts` object[], required: All accounts linked to this creator
    - `id` string, required: Organization account ID
    - `platform` 'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat', required: Social media platform
    - `platformAccountId` string, required: Native platform account identifier
    - `isCompetitor` boolean, required: Whether this account is marked as a competitor
    - `username` string, nullable, required: Account username/handle on the platform
    - `maxVideos` number, required: Maximum number of videos to track for this account
  - `viewCount` number, required: Total lifetime views across all creator's accounts
  - `likeCount` number, required: Total lifetime likes across all creator's accounts
  - `commentCount` number, required: Total lifetime comments across all creator's accounts
  - `shareCount` number, required: Total lifetime shares across all creator's accounts
  - `bookmarkCount` number, required: Total lifetime bookmarks across all creator's accounts
  - `videoCount` number, required: Total number of videos across all creator's accounts
  - `averageViewsPerVideo` number, required: Average views per video across all creator's content
  - `engagementRate` number, required: Overall engagement rate (likes+comments+shares+bookmarks)/views across all accounts
  - `followerCount` number, nullable, required: Total followers aggregated across all creator's linked accounts
  - `viralityRate` number, required: Rate of viral content based on performance thresholds (aggregated)
  - `viewCountInPeriod` number, required: Total views gained during the specified date range across all accounts
  - `likeCountInPeriod` number, required: Total likes gained during the specified date range across all accounts
  - `commentCountInPeriod` number, required: Total comments gained during the specified date range across all accounts
  - `shareCountInPeriod` number, required: Total shares gained during the specified date range across all accounts
  - `bookmarkCountInPeriod` number, required: Total bookmarks gained during the specified date range across all accounts
  - `videoCountInPeriod` number, required: Number of videos published during the specified date range across all accounts
  - `averageViewsPerVideoInPeriod` number, required: Average views per video for content published in the period across all accounts
  - `engagementRateInPeriod` number, required: Engagement rate calculated from period gains (likes+comments+shares+bookmarks)/views across all accounts

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