---
title: "Get overview metrics history"
method: GET
path: "/analytics/metrics"
tags: ["General Analytics"]
---

# Get overview metrics history

`GET /analytics/metrics`

## Request

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

Retrieves only the requested overview metric series for the specified date range. Supports day, week, or month aggregation for video gains, posted videos, app revenue, installs, and engagement rate. Zero-fills missing buckets and respects the standard analytics overview filters.

## 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'
- `metrics` string[], required
- `aggregation` 'day' | 'week' | 'month'
- `stackMetric` 'views' | 'organicViews' | 'paidViews' | 'likes' | 'comments' | 'shares' | 'bookmarks' | 'postedVideos' | 'activeAccounts' | 'appRevenue' | 'newAppInstalls' | 'appNewCustomers' | 'appNewTrials' | 'appNewPaidSubscriptions' | 'engagementRate'
- `stackBy` 'platform' | 'contentType' | 'source'

## Response `200`

OK

- object: Overview metrics with only the requested metric series populated in each returned bucket
  - `aggregation` 'day' | 'week' | 'month', required: Time-series aggregation used for the returned metrics
  - `stacking` object
    - `metric` 'views' | 'organicViews' | 'paidViews' | 'likes' | 'comments' | 'shares' | 'bookmarks' | 'postedVideos' | 'activeAccounts' | 'appRevenue' | 'newAppInstalls' | 'appNewCustomers' | 'appNewTrials' | 'appNewPaidSubscriptions' | 'engagementRate', required
    - `by` 'platform' | 'contentType' | 'source', required
    - `entities` union[], required
      - union
        - 'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat': Social media platform (facebook, instagram, tiktok, youtube, snapchat)
        - 'video' | 'slideshow': Filter by content types (video, slideshow)
        - 'organic' | 'paid'
  - `dailyMetrics` object[], required: Array of aggregated metric buckets for the requested date range
    - `date` string, required: Bucket start date in ISO format (YYYY-MM-DD)
    - `endDate` string, required: Bucket end date in ISO format (YYYY-MM-DD)
    - `views` number
    - `organicViews` number
    - `paidViews` number
    - `likes` number
    - `comments` number
    - `shares` number
    - `bookmarks` number
    - `postedVideos` number
    - `activeAccounts` number
    - `appRevenue` number
    - `newAppInstalls` number
    - `appNewCustomers` number
    - `appNewTrials` number
    - `appNewPaidSubscriptions` number
    - `engagementRate` number
    - `stackedValues` object
  - `currency` string: Display currency for monetary series 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)