Video Analytics

List all tracked videos with analytics

Retrieves paginated videos with comprehensive analytics data. Supports filtering by platforms (TikTok, Instagram, YouTube, Facebook, Snapchat), accounts, content types, projects, and date ranges.

get/videos

Request

  • Base URL: https://viral.app/api/v1
  • URL: https://viral.app/api/v1/videos
  • Auth: API key in header x-api-key

Query parameters

pagenumber

Page number (1-based index)

Example:1
perPagenumber

Number of items per page (1-100)

Example:10
sortColstring

Sort column

Example:publishedAt
sortDir'asc' | 'desc'

Sort direction

Example:asc
platformsstring[] nullable

Social media platforms (facebook, instagram, tiktok, youtube, snapchat)

[
  "facebook",
  "instagram"
]
accountUsernamestring

Account username on the platform

Example:acme
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"
    ]
  }
]
dateRange[from]string
Example:2025-01-01

Start date in ISO format (YYYY-MM-DD)

dateRange[to]string
Example:2025-01-31

End date in ISO format (YYYY-MM-DD)

expandstring[]

Expand related resources in the response

viewMode'internal' | 'competitors' | 'all'
visibility'visible' | 'excluded'

Exclusion-state filter: "visible" (default) hides excluded videos, "excluded" returns only excluded videos

Response

OK

pageCountnumber required

Total number of pages

totalRowsnumber required

Total number of rows

Example response

{
  "data": [
    {
      "id": "vid_91rBGUI9L6Db",
      "platformVideoId": "74567890689123456789001",
      "platform": "tiktok",
      "accountUsername": "viral_creator",
      "platformAccountId": "68968912345678900",
      "accountDisplayName": "Viral Creator",
      "accountProfilePictureUrl": "https://example.com/profile.jpg",
      "caption": "Amazing viral content! #trending #viral #fyp",
      "hashtags": [
        "trending",
        "viral",
        "fyp"
      ],
      "contentType": "video",
      "videoIndex": 1,
      "thumbnailUrl": "https://example.com/thumbnail.jpg",
      "musicId": "music_123",
      "musicTitle": "Trending Song",
      "musicArtist": "Popular Artist",
      "musicAlbum": "Hit Album",
      "musicPlayUrl": "https://example.com/music.mp3",
      "musicCoverUrl": "https://example.com/cover.jpg",
      "isOriginalMusic": false,
      "durationSeconds": 45,
      "viewCount": 1250000,
      "likeCount": 125000,
      "commentCount": 8500,
      "shareCount": 15000,
      "bookmarkCount": 35000,
      "engagementRate": 0.1464,
      "viralityFactor": 8.5,
      "publishedDate": "2025-12-15",
      "publishedAt": "2025-12-15T18:30:00Z",
      "loadAt": "2025-12-20T08:00:00Z",
      "tracking_status": 1,
      "lastErrorAt": null,
      "lastErrorCode": null,
      "orgAccountId": "orgacc_W97M6KLWV4Yq",
      "orgVideoId": "orgvid_91rBGUI9L6Db",
      "projects": [
        "orgproj_1A2B3C4D5E6F"
      ]
    }
  ],
  "pageCount": 8,
  "totalRows": 150
}

Changes

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