General Analytics

Get top performing creators by aggregated metrics

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.

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

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 creators by. Supports both lifetime totals and period-specific gains. Aggregates across all linked accounts.

Example:viewCount

Response

OK

idstring required

Organization creator ID

creatorUserIdstring required

The user ID of the creator

notesstring nullable required

Internal notes about this creator

createdAtstring date-time required

When this creator was added to the organization

updatedAtstring date-time required

When this creator record was last updated

viewCountnumber required

Total lifetime views across all creator's accounts

likeCountnumber required

Total lifetime likes across all creator's accounts

commentCountnumber required

Total lifetime comments across all creator's accounts

shareCountnumber required

Total lifetime shares across all creator's accounts

bookmarkCountnumber required

Total lifetime bookmarks across all creator's accounts

videoCountnumber required

Total number of videos across all creator's accounts

averageViewsPerVideonumber required

Average views per video across all creator's content

engagementRatenumber required

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

followerCountnumber nullable required

Total followers aggregated across all creator's linked accounts

viralityRatenumber required

Rate of viral content based on performance thresholds (aggregated)

viewCountInPeriodnumber required

Total views gained during the specified date range across all accounts

likeCountInPeriodnumber required

Total likes gained during the specified date range across all accounts

commentCountInPeriodnumber required

Total comments gained during the specified date range across all accounts

shareCountInPeriodnumber required

Total shares gained during the specified date range across all accounts

bookmarkCountInPeriodnumber required

Total bookmarks gained during the specified date range across all accounts

videoCountInPeriodnumber required

Number of videos published during the specified date range across all accounts

averageViewsPerVideoInPeriodnumber required

Average views per video for content published in the period across all accounts

engagementRateInPeriodnumber required

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

Example response

[
  {
    "id": "orgcre_ABC123XYZ456",
    "creatorUserId": "user_PxyfnFj5JUx5",
    "notes": "Top tier influencer, responds quickly",
    "createdAt": "2025-01-15T10:00:00.000Z",
    "updatedAt": "2025-12-20T08:00:00.000Z",
    "user": {
      "id": "user_PxyfnFj5JUx5",
      "name": "Sarah Johnson",
      "email": "sarah@example.com",
      "image": "https://example.com/sarah-avatar.jpg",
      "firstName": "Sarah",
      "lastName": "Johnson"
    },
    "accounts": [
      {
        "id": "orgacc_W97M6KLWV4Yq",
        "platform": "tiktok",
        "platformAccountId": "7123456789012345678",
        "username": "sarahjfitness",
        "maxVideos": 100
      },
      {
        "id": "orgacc_X98N7LMXW5Zr",
        "platform": "instagram",
        "platformAccountId": "8234567890123456789",
        "username": "sarahjfitness",
        "maxVideos": 100
      }
    ],
    "viewCount": 78000000,
    "likeCount": 5600000,
    "commentCount": 320000,
    "shareCount": 165000,
    "bookmarkCount": 420000,
    "videoCount": 215,
    "averageViewsPerVideo": 362790,
    "engagementRate": 0.0833,
    "followerCount": 3200000,
    "viralityRate": 0.22,
    "viewCountInPeriod": 18500000,
    "likeCountInPeriod": 1340000,
    "commentCountInPeriod": 72000,
    "shareCountInPeriod": 38000,
    "bookmarkCountInPeriod": 95000,
    "videoCountInPeriod": 22,
    "averageViewsPerVideoInPeriod": 840909,
    "engagementRateInPeriod": 0.0835
  }
]

Changes

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