--- title: "List all accounts with analytics" method: GET path: "/accounts" tags: ["Account Analytics"] --- # List all accounts with analytics `GET /accounts` ## Request - Base URL: `https://viral.app/api/v1` - URL: `https://viral.app/api/v1/accounts` - Auth: API key in header `x-api-key` Retrieves paginated accounts with comprehensive analytics including profile data (followers, following, display name), computed metrics (total views, engagement rate, virality rate), and tracking metadata. Video totals are provided as totalVideosTracked, totalVideosRetained, totalVideosExcluded, and totalVideosPublished. Supports sorting, searching by username, and filtering by platforms, tags, legacy 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 - `search` string: Account username on the platform - `platforms` string[], nullable: Social media platforms (facebook, instagram, tiktok, youtube, snapchat) - `accounts` string[], nullable: Organization account IDs - `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. - `tagsMatch` 'rules' | 'videos': How the tag filter targets rows: `rules` (default) matches entity-level tag rules only; `videos` matches rows with at least one video satisfying the whole filter. - `dateRange[from]` string - `dateRange[to]` string - `contentTypes` string[], nullable: Content types (video, slideshow) - `viewMode` 'internal' | 'competitors' | 'all' ## Response `200` OK - object: Paginated response containing accounts with analytics data, profile information, and pagination metadata - `data` object[], required: Array of accounts with comprehensive analytics and profile data - `id` string, required: Organization-specific account ID - `platform` 'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat', required: Social media platform (tiktok, instagram, youtube) - `platformAccountId` string, required: Platform-specific account identifier - `maxVideos` integer, required: Maximum number of videos to track for this account - `lastErrorAt` string, date-time, nullable, required: Timestamp of last sync error, if any - `lastErrorCode` 'NOT_FOUND' | 'INVALID_DATA' | 'PRIVATE_CONTENT' | 'RESTRICTED' | 'UNSUPPORTED_CONTENT' | 'APPLE_REQUIRED_AGREEMENT' | 'APPLE_INVALID_VENDOR' | 'APPLE_INVALID_CREDENTIALS', nullable, required: Error code from last failed sync attempt - `createdAt` string, date-time, required: When this account tracking was created - `updatedAt` string, date-time, required: When this account tracking was last updated - `userId` string, required: ID of the user who added this account - `orgId` string, required: Organization that owns this account tracking - `orgCreatorId` string, nullable, required: Assigned organization creator ID, if linked - `creatorUserId` string, nullable, required: Assigned creator user ID for this account, if linked - `creatorName` string, nullable, required: Assigned creator display name, if linked - `creatorEmail` string, nullable, required: Assigned creator email, if linked - `creatorImage` string, nullable, required: Assigned creator profile image URL, if linked - `username` string, nullable, required: Account username/handle on the platform - `loadAt` string, nullable, required: Timestamp when account data was last loaded - `followerCount` number, nullable, required: Number of followers for this account - `followingCount` number, nullable, required: Number of accounts this account is following - `profilePictureUrl` string, nullable, required: URL to the account's profile picture - `displayName` string, nullable, required: Display name of the account - `countryCode` string, nullable, required: Country code where the account is based - `isCompetitor` boolean, required: Whether the tracked account is marked as a competitor - `tags` object[]: Account-level tag rules applied to every current and future video of the account. 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 - `viaCreator` object, nullable - `id` string, required: Organization creator ID with orgcre_ prefix - `name` string, required - `videoTags` object[]: Tags carried by some of the account's videos without an account-level rule, each with the number of videos carrying it. 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 - `videoCount` integer, required - `totalVideosTracked` number, nullable, required: Count of videos actively tracked within the max videos setting - `totalVideosRetained` number, nullable, required: Count of historic videos retained beyond the active tracking limit - `totalVideosExcluded` number, required: Count of videos within the tracking window hidden from analytics by the Excluded tag (exclusion workflows or manual exclusions); 0 when the organization excludes nothing - `totalVideosPublished` number, nullable, required: Total number of all-time videos published by this account. Null on platforms that publish no such total (YouTube, Facebook, Snapchat); sorting by this field orders those accounts by totalVideosTracked + totalVideosRetained instead - `totalViews` number, nullable, required: Total lifetime views across all videos - `totalLikes` number, nullable, required: Total lifetime likes across all videos - `totalComments` number, nullable, required: Total lifetime comments across all videos - `totalShares` number, nullable, required: Total lifetime shares across all videos - `totalBookmarks` number, nullable, required: Total lifetime bookmarks across all videos - `averageViewsPerVideo` number, nullable, required: Average views across all tracked videos, rounded to whole views - `p10Views` number, nullable, required: 10th percentile views across all tracked videos, rounded to whole views - `p50Views` number, nullable, required: Median (50th percentile) views across all tracked videos, rounded to whole views - `p90Views` number, nullable, required: 90th percentile views across all tracked videos, rounded to whole views - `viralityRate` number, nullable, required: Virality rate based on capped P90/P50 lift (0–100) - `latestVideoPublishedAt` string, nullable, required: Timestamp of when the latest video was published - `postActivity` object, required: Daily posted-video activity across the most recent dayCount days (10 on list responses) - `dayCount` integer, required - `days` object[], required - `date` string, required - `postedVideos` number, required - `weeklyViewStats` object, required: Avg/P10/P50/P90 views (rounded to whole views) of videos published in each of the trailing 4 calendar weeks (Monday start, UTC), oldest week first; values are null for weeks without published videos - `weeks` object[], required - `weekStart` string, required - `avgViews` number, nullable, required - `p10Views` number, nullable, required - `p50Views` number, nullable, required - `p90Views` number, nullable, required - `daysSinceLastPost` number, nullable, required: Number of days since the last video was published - `engagementRate` number, nullable, required: Overall engagement rate (likes+comments+shares+bookmarks)/views - `user` object, required: Internal tracking metadata for this account - `id` string, required: Internal tracking record ID - `platform` 'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat', required: Platform identifier - `username` string, nullable, required: Username for tracking purposes - `maxVideos` integer, required: Maximum number of videos to track - `userId` string, required: ID of the user who added this account - `orgId` string, required: Organization that owns this account tracking - `createdAt` string, date-time, required: When this account tracking was created - `updatedAt` string, date-time, required: When this account tracking was last updated - `lastErrorAt` string, date-time, nullable, required: Timestamp of last sync error, if any - `lastErrorCode` 'NOT_FOUND' | 'INVALID_DATA' | 'PRIVATE_CONTENT' | 'RESTRICTED' | 'UNSUPPORTED_CONTENT' | 'APPLE_REQUIRED_AGREEMENT' | 'APPLE_INVALID_VENDOR' | 'APPLE_INVALID_CREDENTIALS', nullable, required: Error code from last failed sync attempt - `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)