---
title: "Get views grouped by country tag"
method: GET
path: "/analytics/views-by-country"
tags: ["General Analytics"]
---

# Get views grouped by country tag

`GET /analytics/views-by-country`

## Request

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

Aggregates period view gains of the filtered videos by their effective country tags (assigned directly or through account rules). A video with multiple country tags counts toward each of them. Each country includes its top accounts and top videos by view gains, and the response carries filtered dataset totals so callers can derive tag coverage and per-country view share.

## 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: View gains grouped by effective country tag, plus filtered dataset totals. All fields are zero until the country system tags have been seeded.
  - `totalVideos` number, required: Distinct videos contributing view gains in the filtered dataset
  - `taggedVideos` number, required: Of those, distinct videos with at least one effective country tag
  - `totalViews` number, required: Total view gains of the filtered dataset within the date range
  - `countries` object[], required: Per-country view gains, sorted descending. A video with multiple country tags counts toward each of them.
    - `countryCode` string, required: ISO 3166-1 alpha-2 code of the effective country tag
    - `views` number, required: View gains within the date range across videos carrying this country tag
    - `accounts` object[], required: The country's top accounts by view gains, sorted descending (up to 3)
      - `platform` 'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat', required: Social media platform (facebook, instagram, tiktok, youtube, snapchat)
      - `platformAccountId` string, required: Platform-native account id
      - `username` string, nullable, required: Latest known account username
      - `displayName` string, nullable, required: Latest known account display name
      - `views` number, required: View gains within the date range from this account's videos carrying the country tag
    - `videos` object[], required: The country's top videos by view gains, sorted descending (up to 3)
      - `id` string, required: Internal video content id
      - `platform` 'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat', required: Social media platform (facebook, instagram, tiktok, youtube, snapchat)
      - `platformVideoId` string, required: Platform-native video id
      - `caption` string, nullable, required
      - `thumbnailUrl` string, nullable, required
      - `contentType` string, nullable, required
      - `accountUsername` string, nullable, required
      - `accountDisplayName` string, nullable, required
      - `platformAccountId` string, required
      - `views` number, required: View gains within the date range for this video
  - `assignedCountryCodes` string[], required: Countries with any tag assignment in the organization — a positive video tag or an active account rule — regardless of the current filters

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