General Analytics

Get key performance indicators with period comparison

Retrieves key performance indicators for the specified date range with automatic comparison to the previous period of equal length. Returns content metrics (video/account counts), engagement metrics (views, likes, comments, shares, bookmarks), app performance (revenue, installs), and absolute changes between periods. Filter by platforms, accounts, content types, or projects.

get/analytics/kpis

Request

  • Base URL: https://viral.app/api/v1
  • URL: https://viral.app/api/v1/analytics/kpis
  • 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'

Response

OK

videoCountnumber required

Total number of videos tracked in the period

accountCountnumber required

Total number of accounts tracked

viewCountnumber required

Total video views across all content

organicViewCountnumber required

Video views excluding paid ad views (TikTok Spark Ads); equals total views when no ads integration is connected

paidViewCountnumber required

Paid ad views attributed to tracked videos (TikTok Spark Ads); 0 when no ads integration is connected

likeCountnumber required

Total likes received across all videos

commentCountnumber required

Total comments received across all videos

shareCountnumber required

Total shares across all videos

bookmarkCountnumber required

Total bookmarks/saves across all videos

engagementRatenumber required

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

appRevenuenumber required

Revenue generated from mobile app downloads and in-app purchases (USD)

newAppInstallsnumber required

Number of new mobile app installations

appNewCustomersnumber required

New app customers from RevenueCat or Superwall when connected, with Apple first-time installs as fallback

appNewTrialsnumber required

New app trials from RevenueCat or Superwall

appNewPaidSubscriptionsnumber required

New paid app subscriptions from RevenueCat or Superwall

currencystring

Display currency for monetary KPIs such as appRevenue (the organization's default currency)

Example response

{
  "videoCount": 245,
  "accountCount": 18,
  "viewCount": 15420000,
  "organicViewCount": 14980000,
  "paidViewCount": 440000,
  "likeCount": 1280000,
  "commentCount": 95000,
  "shareCount": 78000,
  "bookmarkCount": 156000,
  "engagementRate": 0.1076,
  "appRevenue": 24680.5,
  "newAppInstalls": 3420,
  "appNewCustomers": 3420,
  "appNewTrials": 820,
  "appNewPaidSubscriptions": 410,
  "previous": {
    "videoCount": 198,
    "accountCount": 16,
    "viewCount": 12100000,
    "organicViewCount": 11840000,
    "paidViewCount": 260000,
    "likeCount": 985000,
    "commentCount": 72000,
    "shareCount": 58000,
    "bookmarkCount": 118000,
    "engagementRate": 0.1018,
    "appRevenue": 18950.25,
    "newAppInstalls": 2680,
    "appNewCustomers": 2680,
    "appNewTrials": 690,
    "appNewPaidSubscriptions": 330
  },
  "changes": {
    "videoCount": 47,
    "accountCount": 2,
    "viewCount": 3320000,
    "organicViewCount": 3140000,
    "paidViewCount": 180000,
    "likeCount": 295000,
    "commentCount": 23000,
    "shareCount": 20000,
    "bookmarkCount": 38000,
    "engagementRate": 0.0058,
    "appRevenue": 5730.25,
    "newAppInstalls": 740,
    "appNewCustomers": 740,
    "appNewTrials": 130,
    "appNewPaidSubscriptions": 80
  }
}

Changes

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