---
title: "Get key performance indicators with period comparison"
method: GET
path: "/analytics/kpis"
tags: ["General Analytics"]
---

# Get key performance indicators with period comparison

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

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.

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

## Response `200`

OK

- object: KPI comparison data with current period, previous period, and absolute changes
  - `videoCount` number, required: Total number of videos tracked in the period
  - `accountCount` number, required: Total number of accounts tracked
  - `viewCount` number, required: Total video views across all content
  - `organicViewCount` number, required: Video views excluding paid ad views (TikTok Spark Ads); equals total views when no ads integration is connected
  - `paidViewCount` number, required: Paid ad views attributed to tracked videos (TikTok Spark Ads); 0 when no ads integration is connected
  - `likeCount` number, required: Total likes received across all videos
  - `commentCount` number, required: Total comments received across all videos
  - `shareCount` number, required: Total shares across all videos
  - `bookmarkCount` number, required: Total bookmarks/saves across all videos
  - `engagementRate` number, required: Overall engagement rate calculated as (likes+comments+shares+bookmarks)/views
  - `appRevenue` number, required: Revenue generated from mobile app downloads and in-app purchases (USD)
  - `newAppInstalls` number, required: Number of new mobile app installations
  - `appNewCustomers` number, required: New app customers from RevenueCat or Superwall when connected, with Apple first-time installs as fallback
  - `appNewTrials` number, required: New app trials from RevenueCat or Superwall
  - `appNewPaidSubscriptions` number, required: New paid app subscriptions from RevenueCat or Superwall
  - `previous` object, required: KPI values from the previous period for comparison
    - `videoCount` number, required: Total number of videos tracked in the period
    - `accountCount` number, required: Total number of accounts tracked
    - `viewCount` number, required: Total video views across all content
    - `organicViewCount` number, required: Video views excluding paid ad views (TikTok Spark Ads); equals total views when no ads integration is connected
    - `paidViewCount` number, required: Paid ad views attributed to tracked videos (TikTok Spark Ads); 0 when no ads integration is connected
    - `likeCount` number, required: Total likes received across all videos
    - `commentCount` number, required: Total comments received across all videos
    - `shareCount` number, required: Total shares across all videos
    - `bookmarkCount` number, required: Total bookmarks/saves across all videos
    - `engagementRate` number, required: Overall engagement rate calculated as (likes+comments+shares+bookmarks)/views
    - `appRevenue` number, required: Revenue generated from mobile app downloads and in-app purchases (USD)
    - `newAppInstalls` number, required: Number of new mobile app installations
    - `appNewCustomers` number, required: New app customers from RevenueCat or Superwall when connected, with Apple first-time installs as fallback
    - `appNewTrials` number, required: New app trials from RevenueCat or Superwall
    - `appNewPaidSubscriptions` number, required: New paid app subscriptions from RevenueCat or Superwall
  - `changes` object, required: Absolute change values between current and previous period (current - previous)
    - `videoCount` number, required: Total number of videos tracked in the period
    - `accountCount` number, required: Total number of accounts tracked
    - `viewCount` number, required: Total video views across all content
    - `organicViewCount` number, required: Video views excluding paid ad views (TikTok Spark Ads); equals total views when no ads integration is connected
    - `paidViewCount` number, required: Paid ad views attributed to tracked videos (TikTok Spark Ads); 0 when no ads integration is connected
    - `likeCount` number, required: Total likes received across all videos
    - `commentCount` number, required: Total comments received across all videos
    - `shareCount` number, required: Total shares across all videos
    - `bookmarkCount` number, required: Total bookmarks/saves across all videos
    - `engagementRate` number, required: Overall engagement rate calculated as (likes+comments+shares+bookmarks)/views
    - `appRevenue` number, required: Revenue generated from mobile app downloads and in-app purchases (USD)
    - `newAppInstalls` number, required: Number of new mobile app installations
    - `appNewCustomers` number, required: New app customers from RevenueCat or Superwall when connected, with Apple first-time installs as fallback
    - `appNewTrials` number, required: New app trials from RevenueCat or Superwall
    - `appNewPaidSubscriptions` number, required: New paid app subscriptions from RevenueCat or Superwall
  - `currency` string: Display currency for monetary KPIs such as appRevenue (the organization's default currency)

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