General Analytics

Get overview metrics history

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.

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

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'
metricsstring[] 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

OK

aggregation'day' | 'week' | 'month' required

Time-series aggregation used for the returned metrics

currencystring

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

Example response

{
  "stacking": {
    "entities": [
      "facebook"
    ]
  }
}

Changes

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