--- title: "List all tracked videos with analytics" method: GET path: "/videos" tags: ["Video Analytics"] --- # List all tracked videos with analytics `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` Retrieves paginated videos with comprehensive analytics data. Supports filtering by platforms (TikTok, Instagram, YouTube, Facebook, Snapchat), accounts, content types, projects, and date ranges. ## Query parameters - `page` number: Page number (1-based index) - `perPage` number: Number of items per page (1-100) - `sortCol` string: Sort column - `sortDir` 'asc' | 'desc': Sort direction - `platforms` string[], nullable: Social media platforms (facebook, instagram, tiktok, youtube, snapchat) - `accountUsername` string: Account username on the platform - `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:` values combine into one geographic group satisfied by any of them. `none:` 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:` 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:` and `none:` values. - `dateRange[from]` string - `dateRange[to]` string - `expand` string[]: 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 `200` OK - object: Paginated response containing videos with analytics data and pagination metadata - `data` object[], required: Array of video objects with comprehensive analytics and metadata - `id` string, nullable, required: Internal video ID, null if not in analytics view - `platformVideoId` string, required: Platform-specific video ID (e.g., TikTok video ID) - `platform` string, required: Social media platform where the video was posted - `accountUsername` string, nullable, required: Account username on the platform - `isCompetitor` boolean: Whether the owning account is marked as a competitor - `platformAccountId` string, nullable, required: Platform-specific account ID - `accountDisplayName` string, nullable, required: Display name of the account - `accountProfilePictureUrl` string, nullable, required: URL to the account's profile picture - `caption` string, nullable, required: Video caption or description text - `hashtags` string[], nullable, required: Array of hashtags extracted from the caption - `contentType` string, nullable, required: Type of content (video, image, carousel) - `videoIndex` number, nullable, required: Index of video in carousel posts (1-based) - `thumbnailUrl` string, nullable, required: URL to the video thumbnail image - `musicId` string, nullable, required: Platform-specific music track ID - `musicTitle` string, nullable, required: Title of the background music - `musicArtist` string, nullable, required: Artist of the background music - `musicAlbum` string, nullable, required: Album of the background music - `musicPlayUrl` string, nullable, required: URL to play the background music - `musicCoverUrl` string, nullable, required: URL to the music cover art - `isOriginalMusic` number, nullable, required: Whether the music is original content by the creator - `durationSeconds` number, nullable, required: Video duration in seconds - `viewCount` number, nullable, required: Total number of views - `organicViewCount` number, nullable: Views excluding paid Spark Ads views (TikTok only; equals total views when no ads data is connected) - `paidViewCount` number, nullable: Cumulative paid Spark Ads views attributed to the video (TikTok only) - `likeCount` number, nullable, required: Total number of likes - `commentCount` number, nullable, required: Total number of comments - `shareCount` number, nullable, required: Total number of shares - `bookmarkCount` number, nullable, required: Total number of bookmarks/saves - `engagementRate` number, nullable, required: Engagement rate calculated as (likes + comments + shares + bookmarks) / views - `viralityFactor` number, nullable, required: Proprietary virality score based on engagement patterns - `publishedDate` string, nullable, required: Date when the video was published (YYYY-MM-DD) - `publishedAt` string, nullable, required: Timestamp when the video was published (ISO 8601) - `loadAt` string, nullable, required: Timestamp when the video data was last loaded into our system - `tracking_status` union, required: Tracking status indicator: 1 for actively tracked entries, 0 for retained historic data - unknown - unknown - `isFromAnalytics` boolean, required: Whether the row came from the analytics video table - `lastErrorAt` string, date-time, nullable, required: Timestamp of the last sync error for this video - `lastErrorCode` 'NOT_FOUND' | 'INVALID_DATA' | 'PRIVATE_CONTENT' | 'RESTRICTED' | 'UNSUPPORTED_CONTENT' | 'APPLE_REQUIRED_AGREEMENT' | 'APPLE_INVALID_VENDOR' | 'APPLE_INVALID_CREDENTIALS', nullable, required: Error code from the last failed sync attempt - `orgAccountId` string, nullable, required: Organization-specific account ID that owns this video - `orgVideoId` string, nullable, required: Organization-specific video tracking ID - `orgAccountMaxVideos` integer, nullable, required: Tracking limit (max_videos) of the account that owns this video; 0 means the account is paused or only holds individually tracked videos - `projects` union[], required: Projects linked to the video. Returns project IDs by default, or full objects when using expand[]=projects. - union - string: Returned when expand[]=projects is omitted. - object: Returned when expand[]=projects is provided. - `id` string, required - `name` string, required - `url` string, nullable, required - `logo` string, nullable, required - `description` string, nullable, required - `videoTags` object[]: Tags effective on the video, including suppressed automated assignments (isSuppressed). Omitted when the tag lookup is skipped or fails. - `id` string, required - `name` string, required - `description` string, nullable, required - `scope` 'system' | 'org' | 'project', required: Tag scope - `color` string, nullable, required: Tag color in hex format - `kind` string, nullable, required - `refId` string, nullable, required - `logo` string, nullable, required - `sourceType` 'manual' | 'account_rule' | 'workflow' | 'ai' | 'creative', required: Where the tag on this video comes from: manual (added to the video), account_rule (a tag on its account or creator), workflow (a tag workflow), ai (an AI tagging rule) or creative (a tag on the creative the video is a copy of, which every copy carries; removing it from one copy opts only that copy out) - `isSuppressed` boolean, required - `viaCreator` object, nullable - `id` string, required: Organization creator ID with orgcre_ prefix - `name` string, required - `pageCount` number, required: Total number of pages - `totalRows` number, required: Total number of rows ## 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)